Add wiki documentation: Home, SDLC, Architecture
- Home.md: Project overview, quick links, current status - SDLC.md: PR workflow, review gates (@engineering, @trust, @market, @cos) - Architecture.md: System diagram, data flow, database schema, API endpoints Wiki pages establish project documentation baseline. Refs #27
This commit is contained in:
Marcus
parent
7dd427a5f2
commit
abda61d5e8
3 changed files with 266 additions and 0 deletions
155
.gitea/wiki/Architecture.md
Normal file
155
.gitea/wiki/Architecture.md
Normal file
|
|
@ -0,0 +1,155 @@
|
|||
# Architecture
|
||||
|
||||
## System Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ USER │
|
||||
└──────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────┴──────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────┐ ┌──────────────────┐
|
||||
│ Static Site │ │ Chat Service │
|
||||
│ (Storj) │ │ (Railway/Fly) │
|
||||
│ │ │ │
|
||||
│ Landing │ │ Real-time AI │
|
||||
│ Style Form │ │ Style Interview │
|
||||
│ Box Display │ │ WebSocket/SSE │
|
||||
└────────┬────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
└──────────┬───────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ API + Database │
|
||||
│ (Railway/Render) │
|
||||
│ │
|
||||
│ • User profiles │
|
||||
│ • Product catalog │
|
||||
│ • Matching engine │
|
||||
│ • Feedback store │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
## Components
|
||||
|
||||
### Static Site (Storj)
|
||||
- **Domain**: `wardrobeai.scoble.me`
|
||||
- **Tech**: Astro SSG or plain HTML/CSS/JS
|
||||
- **Purpose**: Landing, forms, box display, affiliate links
|
||||
- **CDN**: Storj edge
|
||||
|
||||
### Chat Service
|
||||
- **Domain**: `chat.wardrobeai.scoble.me`
|
||||
- **Tech**: Node.js + WebSocket or Python + SSE
|
||||
- **Purpose**: Real-time conversational style interview
|
||||
- **Deploy**: Railway or Fly.io
|
||||
|
||||
### API + Database
|
||||
- **Tech**: Express.js or FastAPI + PostgreSQL
|
||||
- **Purpose**: CRUD operations, matching algorithm, feedback
|
||||
- **Deploy**: Railway, Render, or Fly.io
|
||||
|
||||
## Data Flow
|
||||
|
||||
1. User visits static site → sees landing page
|
||||
2. Clicks "Start Interview" → loads chat interface from chat service
|
||||
3. Chat service conducts AI interview, stores to API
|
||||
4. Chat redirects to static site with profile ID
|
||||
5. Static site calls API to generate box
|
||||
6. API returns curated items → static site displays
|
||||
7. User clicks Amazon links with `greybeardhold-20` affiliate ID
|
||||
8. User provides feedback → stored via API
|
||||
|
||||
## Database Schema (MVP)
|
||||
|
||||
```sql
|
||||
-- Users
|
||||
CREATE TABLE users (
|
||||
id TEXT PRIMARY KEY,
|
||||
email TEXT UNIQUE,
|
||||
name TEXT,
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- Style Profiles
|
||||
CREATE TABLE profiles (
|
||||
id TEXT PRIMARY KEY,
|
||||
user_id TEXT REFERENCES users(id),
|
||||
budget INTEGER, -- 100 or 250
|
||||
sizes JSON, -- {tops, bottoms, dresses, shoes}
|
||||
colors_preferred JSON, -- array
|
||||
colors_avoided JSON, -- array
|
||||
style_ratings JSON, -- {classic, casual, professional, boho, feminine, edgy}
|
||||
lifestyle JSON, -- array of activities
|
||||
invariants JSON, -- array of hard lines
|
||||
must_haves JSON, -- array
|
||||
wardrobe_gaps JSON, -- array
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- Products (Amazon items with metadata)
|
||||
CREATE TABLE products (
|
||||
id TEXT PRIMARY KEY,
|
||||
asin TEXT UNIQUE,
|
||||
name TEXT,
|
||||
brand TEXT,
|
||||
category TEXT,
|
||||
color TEXT,
|
||||
style_tags JSON, -- array
|
||||
price INTEGER,
|
||||
image_url TEXT,
|
||||
affiliate_url TEXT,
|
||||
description TEXT
|
||||
);
|
||||
|
||||
-- Boxes
|
||||
CREATE TABLE boxes (
|
||||
id TEXT PRIMARY KEY,
|
||||
user_id TEXT REFERENCES users(id),
|
||||
items JSON, -- array of product IDs
|
||||
total_price INTEGER,
|
||||
status TEXT, -- pending, shipped, delivered
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
|
||||
-- Feedback
|
||||
CREATE TABLE feedback (
|
||||
id TEXT PRIMARY KEY,
|
||||
box_id TEXT REFERENCES boxes(id),
|
||||
product_id TEXT REFERENCES products(id),
|
||||
user_id TEXT REFERENCES users(id),
|
||||
kept BOOLEAN,
|
||||
fit_rating INTEGER, -- 1-5
|
||||
style_rating INTEGER,
|
||||
color_rating INTEGER,
|
||||
quality_rating INTEGER,
|
||||
comment TEXT,
|
||||
created_at TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| POST | /api/users | Create user |
|
||||
| GET | /api/users/:id | Get user |
|
||||
| POST | /api/profiles | Create profile |
|
||||
| GET | /api/profiles/:userId | Get profile |
|
||||
| GET | /api/products | List all products |
|
||||
| GET | /api/products/:id | Get product |
|
||||
| POST | /api/boxes | Generate box |
|
||||
| GET | /api/boxes/:id | Get box |
|
||||
| POST | /api/feedback | Submit feedback |
|
||||
| GET | /api/feedback/:userId | Get user's feedback |
|
||||
|
||||
## Tech Stack Rationale
|
||||
|
||||
- **Next.js/Astro**: Fast SSG, good for SEO, easy to deploy
|
||||
- **Express/FastAPI**: Simple, fast, well-documented
|
||||
- **PostgreSQL**: Reliable, scalable, good JSON support
|
||||
- **Railway/Fly**: Easy deploy, good free tiers, fast setup
|
||||
- **Storj**: Already in use, cost-effective, fast CDN
|
||||
38
.gitea/wiki/Home.md
Normal file
38
.gitea/wiki/Home.md
Normal file
|
|
@ -0,0 +1,38 @@
|
|||
# WardrobeAI Wiki
|
||||
|
||||
Welcome to the WardrobeAI project documentation.
|
||||
|
||||
## Quick Links
|
||||
- [Repository](https://os.scoble.me/forgejo/sscoble/wardrobe-ai)
|
||||
- [Issues Board](https://os.scoble.me/forgejo/sscoble/wardrobe-ai/issues)
|
||||
- [README](../README.md)
|
||||
|
||||
## Current Status
|
||||
**Phase 0: Foundation** — Establishing SDLC, code review processes, and MVP architecture.
|
||||
|
||||
## Project Overview
|
||||
WardrobeAI is a curated clothing subscription service sourcing from small businesses and boutique brands. We learn your personal style through conversation, match pieces within your budget, and improve with every box.
|
||||
|
||||
## Architecture
|
||||
- **Static Site**: Storj-hosted landing and box display at `wardrobeai.scoble.me`
|
||||
- **Chat Service**: Real-time AI style interview (Railway/Fly.io)
|
||||
- **API + Database**: User profiles, product catalog, matching algorithm
|
||||
|
||||
## Key Features
|
||||
- Style interview (conversational, not a quiz)
|
||||
- Budget-based curation ($100 or $250/month)
|
||||
- Fit feedback loop that learns
|
||||
- Invariants system (your hard lines, honored)
|
||||
- Amazon affiliate integration (MVP)
|
||||
|
||||
## Phases
|
||||
| Phase | Status | Goal |
|
||||
|---|---|---|
|
||||
| 0: Foundation | 🔄 In Progress | SDLC, planning, MVP architecture |
|
||||
| 1: MVP | ⏳ Pending | Working curation engine for personal use |
|
||||
| 2: Growth | ⏳ Pending | 100 subscribers, algorithm improvements |
|
||||
| 3: Scale | ⏳ Pending | 500+ subscribers, warehousing |
|
||||
| 4: Expansion | ⏳ Pending | 2000+, men's line, Series A |
|
||||
|
||||
## Contributing
|
||||
All code changes require PR + review from @engineering, @trust, and @market. See [SDLC](SDLC) for details.
|
||||
73
.gitea/wiki/SDLC.md
Normal file
73
.gitea/wiki/SDLC.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
# Software Development Lifecycle
|
||||
|
||||
## Overview
|
||||
WardrobeAI follows a strict PR-based workflow with multi-agent review gates.
|
||||
|
||||
## Branch Protection
|
||||
- `main` is protected — no direct commits
|
||||
- All changes via Pull Request
|
||||
- Require 3 approvals before merge
|
||||
|
||||
## Review Gates
|
||||
|
||||
### 1. @engineering — Code Quality
|
||||
- Architecture review
|
||||
- Test coverage check
|
||||
- Performance assessment
|
||||
- Technical debt flagging
|
||||
|
||||
### 2. @trust — Security Review
|
||||
- Input validation
|
||||
- SQL injection prevention
|
||||
- XSS prevention
|
||||
- API security (rate limiting, auth)
|
||||
- Dependency vulnerability scan
|
||||
- Secrets management verification
|
||||
|
||||
### 3. @market — Product Review
|
||||
- Feature matches requirements
|
||||
- User experience validation
|
||||
- Business logic correctness
|
||||
- Affiliate integration verification
|
||||
|
||||
### 4. @cos — Final Approval
|
||||
- Cross-functional consensus confirmation
|
||||
- Merge execution
|
||||
|
||||
## Workflow
|
||||
1. Create feature branch from `main`
|
||||
2. Develop and commit to feature branch
|
||||
3. Open PR with clear description
|
||||
4. Auto-assign reviewers: @engineering @trust @market
|
||||
5. Address feedback, push updates
|
||||
6. All approvals received → @cos merges
|
||||
7. Delete feature branch after merge
|
||||
|
||||
## PR Template
|
||||
```
|
||||
## Summary
|
||||
Brief description of changes
|
||||
|
||||
## Type
|
||||
- [ ] Feature
|
||||
- [ ] Bug fix
|
||||
- [ ] Documentation
|
||||
- [ ] Refactor
|
||||
|
||||
## Testing
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Manual testing completed
|
||||
- [ ] Security scan clean
|
||||
|
||||
## Checklist
|
||||
- [ ] Code follows style guide
|
||||
- [ ] No secrets committed
|
||||
- [ ] Documentation updated
|
||||
- [ ] Reviewers assigned
|
||||
```
|
||||
|
||||
## Emergency Process
|
||||
If critical hotfix needed:
|
||||
1. Still open PR
|
||||
2. Expedited review (2 hours max per reviewer)
|
||||
3. @cos can merge with 2 approvals if 3rd unresponsive 4+ hours
|
||||
Loading…
Add table
Add a link
Reference in a new issue