comparaison/docs/development.md

ComparAIson — Development Guide

Getting Started

# 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:

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:

   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