ShipyardAI Plan

# ShipyardAI MVP Plan (Free-Tier First)

## 1) Recommended Architecture

### Stack (recommended)
- **Frontend + API:** Next.js (App Router) on Vercel (Hobby)
- **Auth + DB + Storage:** Supabase Free (Postgres + Auth + RLS + Storage)
- **LLM for guided wizard:** Google Gemini 1.5 Flash / 2.0 Flash (cheap tier)
- **Optional fallback LLM:** Groq free model for high-throughput Q&A
- **Build runner:** Background jobs in app + queued build records in DB
- **Generated app hosting:**
  - MVP: generate static/Next app artifact and host as static output in Supabase Storage + proxied in Shipyard iframe/viewer
  - Phase 2: one-click deploy generated app to Vercel project per user/project

### Why this stack
- Lowest operational cost while production-capable
- Fast auth integration and social providers via Supabase
- Vercel + Next has smooth DX and easy CI/CD
- Keeps infra simple: 2 core providers (Vercel + Supabase)

## 2) Alternatives + Tradeoffs

### Option A (recommended): Supabase + Gemini
- Pros: easy auth, SQL, cheap inference, great speed
- Cons: depends on Google API for wizard quality

### Option B: Supabase + Groq only
- Pros: can be very low-cost/free
- Cons: model quality/consistency varies for requirements engineering

### Option C: Firebase stack
- Pros: tight Google integration
- Cons: data model complexity and SQL-like querying weaker for this workflow

## 3) Core Product Flow
1. User signs up/in (email+password or social)
2. User creates Project
3. Wizard starts: asks intent + constraints + goals
4. LLM proposes 2-3 architecture options with tradeoffs
5. User selects option + confirms scope
6. Context store reaches readiness threshold
7. Build pipeline generates app artifact
8. Shipyard hosts and previews generated app inside project

## 4) Data Model (MVP)

- `profiles` (id, email, name, created_at)
- `projects` (id, owner_id, name, status, created_at)
- `wizard_sessions` (id, project_id, state, llm_model, readiness_score)
- `wizard_messages` (id, session_id, role, content, created_at)
- `architecture_options` (id, session_id, option_key, summary, pros, cons, cost_notes)
- `project_context` (id, project_id, context_json, last_updated_at)
- `build_jobs` (id, project_id, status, started_at, ended_at, logs)
- `build_artifacts` (id, project_id, type, storage_path, preview_url, created_at)

## 5) API Routes (MVP)

- `POST /api/projects` create project
- `GET /api/projects` list projects
- `POST /api/wizard/:projectId/start` start wizard
- `POST /api/wizard/:projectId/message` user message -> llm response
- `POST /api/wizard/:projectId/choose-option` pick architecture option
- `POST /api/wizard/:projectId/finalize` freeze context + enqueue build
- `GET /api/builds/:projectId` build status + logs
- `GET /api/artifacts/:projectId` hosted app metadata

## 6) Risks
- **Prompt drift / low-quality specs:** enforce structured response JSON + validation
- **Runaway LLM costs:** model caps, token budgets, max wizard turns
- **Unsafe generated code:** sandbox generation, no secret interpolation, static analysis pass
- **Auth complexity:** start with Google + email, add others later
- **Build failures:** retry policy + visible error guidance for users

## 7) Visual Validation Strategy (mandatory)
For each shipped step:
1. Open page in browser
2. Screenshot before/after
3. Verify no console errors
4. Verify mobile layout for changed pages

## 8) 2-Week MVP Schedule

### Week 1
- Day 1: Scaffold + auth screens + Supabase integration
- Day 2: Social login + protected dashboard
- Day 3: Project creation flow + project list
- Day 4: Wizard UI + message persistence
- Day 5: LLM integration + option proposal UX

### Week 2
- Day 6: Context assembler + readiness scoring
- Day 7: Build job queue + worker endpoint
- Day 8: Artifact storage + hosted viewer in Shipyard
- Day 9: End-to-end test pass + polish
- Day 10: Deploy hardening + launch checklist