# 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