# ComparAIson — Implementation Plan

**Goal:** Web app where users query an LLM to perform deep research comparing 2+ items, displayed with interactive visualizations, saved as blog-style posts on user profiles.

**Architecture:** Next.js 15 full-stack (App Router), Server Actions, SSE streaming for research progress. PostgreSQL for persistence. Better Auth for users. Multi-provider LLM research engine (Tavily → Perplexity → OpenAI).

**Tech Stack:** Next.js 15, TypeScript, Tailwind CSS, shadcn/ui, Recharts, Drizzle ORM, PostgreSQL 16, Better Auth, Docker Compose + Traefik

---

## Phase 1: Project Scaffold (COMPLETE)
- [x] Next.js 15 init with TypeScript + Tailwind
- [x] Install deps: drizzle-orm, postgres, better-auth, recharts, openai, drizzle-kit

## Phase 2: Database + Auth
- [ ] 2.1 Define Drizzle schema (users, comparisons, comparison_items, comparison_dimensions)
- [ ] 2.2 Setup Better Auth (server config + client + catch-all route)
- [ ] 2.3 Auth UI pages (sign-in, sign-up forms with shadcn)

## Phase 3: LLM Research Engine
- [ ] 3.1 Research engine types + orchestration (src/lib/llm/)
- [ ] 3.2 OpenAI provider (structured JSON output for comparison data)
- [ ] 3.3 SSE streaming endpoint for research progress
- [ ] 3.4 Server Action: createComparison (kicks off research pipeline)

## Phase 4: Frontend — Comparison UI
- [ ] 4.1 shadcn/ui init + core components
- [ ] 4.2 Comparison input page (tag-style item entry, start research)
- [ ] 4.3 Radar chart visualization (Recharts)
- [ ] 4.4 Comparison table (feature matrix, color-coded)
- [ ] 4.5 Score cards + pros/cons lists
- [ ] 4.6 Grouped bar chart
- [ ] 4.7 Comparison results page (assembles all viz components)

## Phase 5: User Profiles + Blog
- [ ] 5.1 User profile page (avatar, comparison history grid)
- [ ] 5.2 Explore/feed page (public comparisons, search, filter)
- [ ] 5.3 Layout + navigation (header, sidebar, footer)

## Phase 6: Deploy
- [ ] 6.1 Docker Compose (Next.js standalone + PostgreSQL)
- [ ] 6.2 Traefik route + domain config
- [ ] 6.3 Environment secrets

---

## Data Model

### users (managed by Better Auth)
- id, name, email, emailVerified, image, createdAt, updatedAt

### comparisons
- id, userId, title, query, slug, status (researching|completed|failed)
- summary, overallData (JSONB), tags (text[]), isPublic, viewCount
- createdAt, updatedAt

### comparison_items
- id, comparisonId, name, description, imageUrl
- researchData (JSONB), scores (JSONB), pros (text[]), cons (text[]), order

### comparison_dimensions
- id, comparisonId, name, description, weight, order

## JSONB Schema for comparison_data
```json
{
  "overall_score": 8.5,
  "dimensions": {
    "price": { "score": 9, "summary": "...", "details": "..." },
    "performance": { "score": 8, "summary": "...", "benchmark_data": [...] },
    "ease_of_use": { "score": 9, "summary": "...", "pros": [...], "cons": [...] }
  }
}
```