docs: comprehensive documentation - README, specs, architecture, API reference, UI/UX flow, dev guide

docs/development.md

@@ -0,0 +1,86 @@
+# ComparAIson — Development Guide
+
+## Getting Started
+
+```bash
+# Clone
+git clone https://gitea.tophermayor.com/TopherMayor/comparaison.git
+cd comparaison
+
+# Install
+npm install
+
+# Environment
+cp .env.example .env.local
+# Edit .env.local with your keys
+
+# Database
+docker compose up db -d  # Start just PostgreSQL
+npx drizzle-kit generate  # Generate migrations
+npx drizzle-kit migrate   # Apply migrations
+
+# Dev server
+npm run dev
+```
+
+## Commands
+
+| Command | Description |
+|---|---|
+| `npm run dev` | Start dev server (port 3000) |
+| `npm run build` | Production build (standalone output) |
+| `npm run start` | Start production server |
+| `npm run lint` | ESLint check |
+| `npx tsc --noEmit` | Type check without building |
+| `npx drizzle-kit generate` | Generate DB migrations from schema |
+| `npx drizzle-kit migrate` | Apply migrations to database |
+| `npx drizzle-kit studio` | Open Drizzle Studio (DB browser) |
+
+## Branch Strategy
+
+| Branch | Purpose |
+|---|---|
+| `main` | Stable, deployable code |
+| `feat/backend` | DB schema, auth, Docker, config changes |
+| `feat/llm-engine` | LLM provider changes, research pipeline |
+| `feat/frontend` | UI components, pages, layouts |
+
+Worktrees are used for parallel development:
+```bash
+git worktree add ../comparaison-backend -b feat/backend main
+```
+
+## Database Schema Changes
+
+1. Edit `src/lib/db/schema.ts`
+2. Run `npx drizzle-kit generate` to create migration SQL
+3. Run `npx drizzle-kit migrate` to apply
+4. Commit both schema.ts and the generated SQL in `drizzle/`
+
+## Adding a New LLM Provider
+
+1. Create `src/lib/llm/providers/your-provider.ts`
+2. Implement the provider function matching the `Provider` interface:
+   ```typescript
+   export async function synthesize(
+     request: ComparisonRequest,
+     searchResults: Record<string, SearchResult[]>
+   ): Promise<ComparisonResult>
+   ```
+3. Register in `src/lib/llm/providers/index.ts` — add to the fallback chain
+4. Add API key to `.env.example` and document in README
+
+## Adding a New Visualization
+
+1. Create `src/components/comparison/your-chart.tsx`
+2. Accept `ComparisonData` as props (or relevant subset)
+3. Use Recharts for chart components
+4. Import and add to the tab layout in `results-client.tsx`
+
+## Key Conventions
+
+- **Server Components** by default, `"use client"` only when needed (hooks, interactivity)
+- **Drizzle ORM** for all database queries — no raw SQL
+- **shadcn/ui** for UI components — no external component libraries
+- **Tailwind** for styling — no CSS modules or styled-components
+- **TypeScript strict mode** — no `any` types