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

2026-04-24 15:02:40 -07:00
parent 5bde4e3aa6
commit aac0e2f5b1
6 changed files with 1057 additions and 20 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,148 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# ComparAIson

-## Getting Started
+**AI-Powered Deep Research Comparison Platform**

-First, run the development server:
+Compare anything with intelligent, multi-dimensional analysis. ComparAIson uses LLM-powered research to generate comprehensive, visual comparisons — then saves them as shareable posts on your profile.
+
+## Features
+
+- **Deep Research Engine** — Multi-provider LLM pipeline (Tavily search → Perplexity/OpenAI synthesis) with automatic fallback
+- **Interactive Visualizations** — Radar charts, grouped bar charts, feature comparison tables, score cards, pros/cons breakdowns
+- **Real-Time Streaming** — Watch research progress live via Server-Sent Events
+- **User Profiles** — Save comparisons to your profile, browse a public feed
+- **Self-Hosted** — Docker Compose deployment, runs on a Raspberry Pi
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js 15 (App Router, Server Components, Server Actions) |
+| Language | TypeScript |
+| Database | PostgreSQL 16 |
+| ORM | Drizzle ORM |
+| Auth | Better Auth (email + password) |
+| UI | Tailwind CSS + shadcn/ui |
+| Charts | Recharts |
+| LLM | OpenAI GPT-4o-mini + Tavily Search + Perplexity Sonar |
+| Deployment | Docker Compose + Traefik reverse proxy |
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js 20+
+- PostgreSQL 16+ (or Docker)
+- At least one LLM API key
+
+### 1. Clone & Install
+
+```bash
+git clone https://gitea.tophermayor.com/TopherMayor/comparaison.git
+cd comparaison
+npm install
+```
+
+### 2. Configure Environment
+
+```bash
+cp .env.example .env.local
+# Edit .env.local with your API keys and database URL
+```
+
+Required environment variables:
+
+| Variable | Description | Required |
+|---|---|---|
+| `DATABASE_URL` | PostgreSQL connection string | Yes |
+| `BETTER_AUTH_SECRET` | Random secret for session signing | Yes |
+| `OPENAI_API_KEY` | OpenAI API key (GPT-4o-mini) | Yes* |
+| `TAVILY_API_KEY` | Tavily search API key | Recommended |
+| `PERPLEXITY_API_KEY` | Perplexity Sonar API key | Optional |
+| `NEXT_PUBLIC_APP_URL` | Public URL of the app | Yes |
+
+*At minimum, one LLM provider key is required. OpenAI works standalone; Tavily adds web search; Perplexity adds cheaper synthesis.
+
+### 3. Database Setup
+
+```bash
+# Generate migration
+npx drizzle-kit generate
+
+# Run migration
+npx drizzle-kit migrate
+```
+
+### 4. Development

 ```bash
 npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+# App runs at http://localhost:3000
 ```

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+### 5. Docker Deployment

-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+```bash
+docker compose up -d
+```

-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+## Project Structure

-## Learn More
+```
+src/
+├── app/
+│   ├── (auth)/              # Auth route group
+│   │   ├── sign-in/         # Sign in page
+│   │   └── sign-up/         # Sign up page
+│   ├── (main)/              # Main app route group (with nav)
+│   │   ├── compare/         # Comparison input + results
+│   │   ├── explore/         # Public comparisons feed
+│   │   └── profile/         # User profile + saved comparisons
+│   ├── api/
+│   │   ├── auth/[...all]/   # Better Auth catch-all
+│   │   └── compare/         # SSE streaming research endpoint
+│   ├── layout.tsx           # Root layout
+│   └── page.tsx             # Landing page
+├── components/
+│   ├── comparison/          # Visualization components
+│   │   ├── radar-chart.tsx
+│   │   ├── bar-chart.tsx
+│   │   ├── comparison-table.tsx
+│   │   ├── score-card.tsx
+│   │   └── pros-cons-card.tsx
+│   └── ui/                  # shadcn/ui components
+├── hooks/
+│   └── use-comparison-stream.ts  # SSE streaming hook
+├── lib/
+│   ├── auth.ts              # Better Auth server config
+│   ├── auth-client.ts       # Better Auth client
+│   ├── db/
+│   │   ├── index.ts         # Drizzle client
+│   │   └── schema.ts        # Database schema
+│   ├── llm/
+│   │   ├── index.ts         # Research pipeline orchestrator
+│   │   ├── types.ts         # LLM type definitions
+│   │   └── providers/
+│   │       ├── index.ts     # Provider fallback chain
+│   │       ├── openai.ts    # OpenAI GPT-4o-mini provider
+│   │       ├── tavily.ts    # Tavily search provider
+│   │       └── perplexity.ts # Perplexity Sonar provider
+│   ├── types.ts             # Shared type definitions
+│   └── utils.ts             # Utility functions
+└── middleware.ts             # Auth middleware + route protection
+```

-To learn more about Next.js, take a look at the following resources:
+## Architecture

- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+See [docs/architecture.md](docs/architecture.md) for detailed architecture documentation.

-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+## API Reference

-## Deploy on Vercel
+See [docs/api-reference.md](docs/api-reference.md) for endpoint documentation.

-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+## UI/UX Flow

-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+See [docs/ui-ux-flow.md](docs/ui-ux-flow.md) for user journey and wireframe descriptions.
+
+## License
+
+MIT