Decisions
Architecture Decision Records (ADRs) for WardrobeAI.
ADR-001: Amazon as Initial Vendor Source for MVP
Date: 2026-05-02 Status: ✅ Accepted Issue: #21
Context
For MVP, we need a product source to test the curation engine. Options were:
- Establish direct wholesale relationships with boutique vendors
- Source from Amazon via affiliate program
- Use generic product data (no fulfillment)
Decision
Use Amazon as the initial vendor source for MVP.
Rationale
- Speed: No vendor negotiation required — start curating immediately
- Selection: Amazon's massive catalog lets us test curation across style profiles
- Fulfillment: Prime shipping and easy returns handled by Amazon
- Revenue: Affiliate commissions (2-4%) generate some income during validation
- Learning: Use real shopping data to train the matching algorithm before investing in vendor relationships
Consequences
- Positive: Fastest path to a working product
- Positive: Proven customer experience (Prime shipping, Amazon returns)
- Negative: Lower margins (2-4% vs 50-70% wholesale margin)
- Negative: Products not exclusive — competitors could use same items
- Negative: Amazon prices fluctuate — need price tracking
Transition Plan
Phase 1 → Amazon only. Phase 2-3 → Add boutique vendors. Phase 3+ → Boutique-first, Amazon as fallback.
ADR-002: SQLite for MVP Database
Date: 2026-05-02 Status: ✅ Accepted
Context
Choose a database for the MVP. Options considered:
- SQLite (file-based, zero configuration)
- PostgreSQL (full-featured relational)
- MongoDB (document store)
Decision
Use SQLite for the MVP.
Rationale
- Zero infrastructure: No database server to install or configure
- Simple deployment: Single file — easy to backup, move, reset
- Sufficient performance: SQLite handles hundreds of concurrent reads; adequate for MVP scale (<100 users)
- Ubiquitous: Node.js has built-in sqlite3 support
- Fast iteration: Easy to reset schema during development (
rm wardrobe-ai.db && npm start)
Consequences
- Positive: Fastest setup, no DevOps overhead
- Positive: Simple schema migrations (drop and recreate for now)
- Negative: Not suitable for production at scale (>1000 concurrent users)
- Negative: No connection pooling, limited write concurrency
- Negative: Schema changes require migrations
Post-MVP Plan
Switch to PostgreSQL for production (Phase 2+). The schema is designed to be portable — foreign keys and standard SQL types.
ADR-003: Split Architecture — Static Site + Chat Service
Date: 2026-05-02 Status: 📋 Planned (Phase 2+)
Context
How should the WardrobeAI application be architected for production?
Decision
Use a split architecture:
- Static site (Astro SSG) for marketing pages, style interview, brand content
- Chat/API service (Node.js + Express) for curation logic and user data
- Deployed separately on different infrastructure
Rationale
- Performance: Static site loads instantly from CDN (Storj/Vercel edge)
- Cost: Static hosting is nearly free; API service scales independently
- Security: Attack surface is smaller — no server-rendered pages
- UX: Fast page loads for content; async API calls for dynamic features
- Simplicity: Each service does one thing well
Current MVP Architecture (Deviation)
The MVP currently runs as a monolith Next.js app + Express backend. The static/challenge split is a Phase 2 optimization.
ADR-004: Next.js for Frontend
Date: 2026-05-02 Status: ✅ Accepted
Decision
Use Next.js (React) for the frontend.
Rationale
- Developer productivity: React ecosystem, fast iteration
- SSR/SSG: Supports both static generation and server rendering
- Great developer experience: Hot reload, TypeScript, built-in routing
- Team familiarity: The engineering team has React experience
Migration Path
The current Next.js app will transition to:
- Astro SSG for static pages (landing, brand, style interview flow)
- Keep Next.js (or similar) for the authenticated app experience (boxes, feedback, history)
ADR-005: Manual Returns Processing for MVP
Date: 2026-05-02 Status: ✅ Accepted
Context
Need a returns process for MVP. Options:
- Automated/managed returns (e.g., Returnly, Happy Returns)
- Amazon-managed returns (items sourced from Amazon)
- Manual return processing (founder handles)
Decision
Use Amazon's return policy for MVP (items sourced from Amazon). Manual handling for any non-Amazon items.
Rationale
- Amazon handles their own returns seamlessly
- Customers already trust Amazon's return process
- Zero implementation cost — use Amazon's existing infrastructure
- Track return reasons via customer feedback form (not return logistics)
Future Plan
Phase 2+ → Transition to managed returns platform (Returnly, Loop Returns) when boutique vendors become primary source.