From aac0e2f5b1083d195f1abe1eec06a90ee0ae8ff3 Mon Sep 17 00:00:00 2001 From: Christopher Mayor Date: Fri, 24 Apr 2026 15:02:40 -0700 Subject: [PATCH] docs: comprehensive documentation - README, specs, architecture, API reference, UI/UX flow, dev guide --- README.md | 152 ++++++++++++++++--- docs/api-reference.md | 204 +++++++++++++++++++++++++ docs/architecture.md | 129 ++++++++++++++++ docs/development.md | 86 +++++++++++ docs/specs.md | 163 ++++++++++++++++++++ docs/ui-ux-flow.md | 343 ++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 1057 insertions(+), 20 deletions(-) create mode 100644 docs/api-reference.md create mode 100644 docs/architecture.md create mode 100644 docs/development.md create mode 100644 docs/specs.md create mode 100644 docs/ui-ux-flow.md diff --git a/README.md b/README.md index e215bc4..1956891 100644 --- 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 diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..e5dd8a2 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,204 @@ +# ComparAIson — API Reference + +## Base URL + +``` +Development: http://localhost:3000 +Production: https://comparaison.tophermayor.com +``` + +--- + +## Authentication + +All authenticated endpoints use Better Auth session cookies. + +### POST `/api/auth/sign-up` +Create a new account. + +**Request:** +```json +{ + "name": "Alex Johnson", + "email": "alex@example.com", + "password": "securepassword123" +} +``` + +**Response:** `200 OK` — Sets session cookie, returns user object + +### POST `/api/auth/sign-in` +Sign in to existing account. + +**Request:** +```json +{ + "email": "alex@example.com", + "password": "securepassword123" +} +``` + +**Response:** `200 OK` — Sets session cookie, redirects to callbackUrl + +### POST `/api/auth/sign-out` +Sign out, clears session. + +**Response:** `200 OK` — Redirects to `/` + +--- + +## Comparison Endpoints + +### POST `/api/compare` +Start a new comparison research. Returns a Server-Sent Events stream. + +**Authentication:** Required + +**Request:** +```json +{ + "query": "for modern web development", + "items": ["React", "Vue", "Svelte"], + "dimensions": ["Performance", "Developer Experience"] +} +``` + +| Field | Type | Required | Description | +|---|---|---|---| +| `query` | string | No | Context/focus for the comparison | +| `items` | string[] | Yes | Items to compare (2-10) | +| `dimensions` | string[] | No | Optional dimension hints | + +**Response:** `200 OK` — `text/event-stream` + +SSE event format: +``` +event: progress +data: {"status":"researching","message":"Analyzing comparison request...","itemsCompleted":0,"totalItems":3,"currentStep":"Analyzing comparison request..."} + +event: progress +data: {"status":"researching","message":"Researching React...","itemsCompleted":1,"totalItems":3,"currentStep":"Analyzing React"} + +event: progress +data: {"status":"completed","message":"Research complete!","itemsCompleted":3,"totalItems":3,"currentStep":"Done"} + +event: done +data: {"id":"clx123abc","slug":"react-vs-vue-vs-svelte-clx123","data":{...full comparison data...}} +``` + +**Error Response:** `400 Bad Request` +```json +{ "error": "At least 2 items are required" } +``` + +--- + +## Page Routes + +### `GET /` +Landing page. Public. Shows hero, example comparisons, features. + +### `GET /sign-in` +Sign in form. Public. Redirects to `/compare` on success. + +### `GET /sign-up` +Sign up form. Public. Redirects to `/compare` on success. + +### `GET /compare` +Comparison creation page. **Protected.** Shows item input form + streaming progress. + +### `GET /compare/[slug]` +Comparison results page. Public (if comparison is public). Shows tabbed visualization layout. + +**URL format:** `/compare/react-vs-vue-vs-svelte-clx123a` + +### `GET /explore` +Public comparisons feed. Public. Grid layout with search + category filter. + +### `GET /profile` +User profile page. **Protected.** Shows user info, stats, and saved comparisons. + +--- + +## TypeScript Types + +### ComparisonRequest +```typescript +interface ComparisonRequest { + query: string; + items: string[]; + dimensions?: string[]; +} +``` + +### ComparisonResult +```typescript +interface ComparisonResult { + items: ItemResearch[]; + dimensions: string[]; + summary: string; + recommendation: string; +} +``` + +### ItemResearch +```typescript +interface ItemResearch { + name: string; + description: string; + overallScore: number; + dimensions: Record; + pros: string[]; + cons: string[]; + sources: { title: string; url: string; snippet: string }[]; +} +``` + +### DimensionResult +```typescript +interface DimensionResult { + score: number; // 1-10 + summary: string; + details: string; + pros: string[]; + cons: string[]; +} +``` + +### ResearchProgress (SSE) +```typescript +type ResearchProgress = + | { stage: "parsing"; message: string } + | { stage: "searching"; item: string; results: number } + | { stage: "researching"; item: string; progress: number } + | { stage: "synthesizing"; message: string } + | { stage: "complete"; result: ComparisonResult } + | { stage: "error"; error: string }; +``` + +### ComparisonData (Frontend) +```typescript +interface ComparisonData { + id: string; + userId: string; + title: string; + query: string; + slug: string; + status: "researching" | "completed" | "failed"; + summary: string; + items: { + name: string; + description: string; + overallScore: number; + dimensions: Record; + pros: string[]; + cons: string[]; + }[]; + dimensions: string[]; + tags: string[]; + isPublic: boolean; + viewCount: number; + createdAt: string; + updatedAt: string; +} +``` diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1746fb5 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,129 @@ +# ComparAIson — Architecture + +## System Overview + +``` +┌─────────────┐ ┌──────────────┐ ┌─────────────┐ +│ Browser │────▶│ Traefik │────▶│ Next.js │ +│ (React SPA) │◀────│ (Reverse │◀────│ (Port 3000)│ +│ │ │ Proxy) │ │ │ +└─────────────┘ └──────────────┘ └──────┬──────┘ + │ + ┌─────────────┼─────────────┐ + ▼ ▼ ▼ + ┌──────────┐ ┌──────────┐ ┌──────────┐ + │PostgreSQL│ │ Tavily │ │ OpenAI │ + │ (DB) │ │ (Search) │ │ (LLM) │ + └──────────┘ └──────────┘ └──────────┘ + ┌──────────┐ + │Perplexity│ + │ (LLM) │ + └──────────┘ +``` + +## Component Architecture + +### Frontend (Next.js App Router) + +``` +Route Groups: +├── (auth)/ — Unauthenticated pages (sign-in, sign-up) +├── (main)/ — Authenticated pages with shared nav layout +│ ├── compare/ — Comparison creation + results viewing +│ ├── explore/ — Public feed browsing +│ └── profile/ — User profile + comparison history +└── api/ — Server-side API routes + ├── auth/ — Better Auth endpoints + └── compare/ — SSE research streaming endpoint +``` + +**Key patterns:** +- **Server Components** for data-fetching pages (profile, explore) +- **Client Components** for interactive UI (compare input, charts, streaming) +- **Server Actions** for mutations (save comparison, update profile) +- **SSE streaming** for real-time research progress + +### Backend Services + +#### Research Pipeline (`src/lib/llm/`) +Orchestrates the multi-stage research process: +1. **Input parsing** — Validate items, extract dimensions +2. **Provider detection** — Check available API keys, select best provider chain +3. **Web search** — Tavily API searches per item +4. **LLM synthesis** — Structured JSON generation via Perplexity or OpenAI +5. **Validation** — Runtime type checking of LLM output +6. **Persistence** — Store results in PostgreSQL via Drizzle ORM + +#### Auth System (`src/lib/auth.ts`) +- Better Auth with Drizzle adapter +- Email + password authentication +- 7-day session expiry +- Middleware-based route protection + +#### Database (`src/lib/db/`) +- Drizzle ORM with PostgreSQL +- 5 tables: users, sessions, comparisons, comparison_items, comparison_dimensions +- JSONB columns for flexible research data storage +- Indexed on userId, slug, status for query performance + +## Data Flow + +### Comparison Creation Flow + +``` +1. User enters items + query on /compare +2. Client calls POST /api/compare with { items, query, dimensions } +3. Server creates comparison record (status: "researching") +4. Server opens SSE stream to client +5. Research pipeline runs: + a. Parsing → emits SSE "parsing" event + b. For each item: + - Tavily search → emits SSE "searching" event + - Process results → emits SSE "researching" event with progress % + c. Synthesize all data → emits SSE "synthesizing" event + d. Validate + structure → emits SSE "complete" event with full data +6. Server persists results to comparisons + comparison_items tables +7. Client renders visualization components with result data +8. User redirected to /compare/[slug] with full results +``` + +### Comparison Viewing Flow + +``` +1. User navigates to /compare/[slug] +2. Server component fetches comparison from DB by slug +3. If status === "researching": show streaming progress UI +4. If status === "completed": render full results with all viz components +5. If status === "failed": show error with retry option +6. Increment viewCount on each visit +``` + +## Deployment Architecture + +### Docker Compose + +```yaml +services: + app: # Next.js standalone (~150-300MB RAM) + db: # PostgreSQL 16 Alpine (~200-400MB RAM) +``` + +Total estimated RAM: **400-800MB** — fits comfortably on an 8GB Raspberry Pi. + +### Traefik Integration + +The app is exposed via Traefik reverse proxy with: +- HTTPS termination +- Domain routing (e.g., `comparaison.tophermayor.com`) +- Automatic SSL certificate management + +## Error Handling + +| Layer | Strategy | +|---|---| +| LLM API failures | 3x retry with exponential backoff | +| Provider unavailable | Automatic fallback to next provider in chain | +| Invalid LLM output | Runtime validation + retry with new prompt | +| Database errors | Transaction rollback, error logged, user sees "failed" status | +| SSE connection lost | Client auto-reconnects, polls comparison status from DB | +| Auth failures | Redirect to sign-in with callback URL | diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..a99d0a7 --- /dev/null +++ b/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 + ): Promise + ``` +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 diff --git a/docs/specs.md b/docs/specs.md new file mode 100644 index 0000000..00f6754 --- /dev/null +++ b/docs/specs.md @@ -0,0 +1,163 @@ +# ComparAIson — Product Specification + +## 1. Product Overview + +**ComparAIson** is a self-hosted web application that enables users to compare two or more items using AI-powered deep research. The system performs multi-source research, generates structured comparison data, and presents results through interactive visualizations. Completed comparisons are saved as posts on user profiles, creating a browsable library of research. + +## 2. Problem Statement + +Comparing products, technologies, or services requires gathering data from multiple sources, synthesizing findings, and presenting them clearly. This is time-consuming and often produces inconsistent results. ComparAIson automates this process with LLM-powered research that produces structured, visual, and comparable outputs. + +## 3. Target Users + +- **Developers** comparing frameworks, tools, cloud services +- **Consumers** comparing products before purchase +- **Researchers** comparing methodologies, papers, or approaches +- **Teams** evaluating options for technical decisions + +## 4. Core Features + +### 4.1 AI Research Engine +- Multi-item comparison (2-10 items) +- Multi-dimensional scoring (5-8 dimensions per comparison) +- Web search integration via Tavily API +- LLM synthesis via OpenAI GPT-4o-mini or Perplexity Sonar +- Automatic provider fallback chain +- Structured JSON output with validation +- Server-Sent Events for real-time progress + +### 4.2 Interactive Visualizations +- **Radar/Spider Chart** — Multi-dimensional overlay showing all items +- **Grouped Bar Chart** — Side-by-side metric comparison +- **Comparison Table** — Feature matrix with color-coded cells +- **Score Cards** — Animated progress bars with overall + per-dimension scores +- **Pros/Cons Cards** — Expandable per-item breakdown + +### 4.3 User System +- Email + password authentication (Better Auth) +- Session management (7-day expiry) +- Protected routes for compare/profile actions +- Public profile pages with comparison history + +### 4.4 Social/Feed Features +- Public comparisons feed (Explore page) +- Per-comparison view count tracking +- Tag-based categorization and filtering +- Search across public comparisons +- Shareable URLs for each comparison + +## 5. Technical Constraints + +| Constraint | Value | +|---|---| +| Deployment target | Raspberry Pi ARM64, 8GB RAM | +| Concurrent users | Low (homelab, <20) | +| Total RAM budget | ~500MB-1GB (app + DB + reverse proxy) | +| Cost target | Minimal (free tier APIs where possible) | +| Network | Behind Traefik reverse proxy with HTTPS | + +## 6. Data Model + +### 6.1 Users (Better Auth managed) +``` +users: id, name, email, emailVerified, image, createdAt, updatedAt +sessions: id, userId (FK), token, expiresAt, createdAt, updatedAt +``` + +### 6.2 Comparisons +``` +comparisons: id, userId (FK), title, query, slug, status (researching|completed|failed), + summary, overallData (JSONB), tags[], isPublic, viewCount, createdAt, updatedAt +``` + +### 6.3 Comparison Items +``` +comparison_items: id, comparisonId (FK), name, description, imageUrl, + researchData (JSONB), scores (JSONB), pros[], cons[], order +``` + +### 6.4 Comparison Dimensions +``` +comparison_dimensions: id, comparisonId (FK), name, description, weight, order +``` + +### 6.5 JSONB Schemas + +**overallData (on comparisons):** +```json +{ + "title": "React vs Vue vs Svelte", + "query": "for modern web development", + "status": "completed", + "summary": "...", + "items": [ + { + "name": "React", + "description": "...", + "overallScore": 8.5, + "dimensions": { + "Performance": { "score": 8, "summary": "...", "details": "...", "pros": [], "cons": [] } + }, + "pros": ["..."], + "cons": ["..."] + } + ], + "dimensions": ["Performance", "Developer Experience", "Ecosystem", ...] +} +``` + +**researchData (on comparison_items):** +Full `ItemResearch` object including dimensions, sources, and scores. + +## 7. LLM Research Pipeline + +### 7.1 Flow +``` +User submits query + → Parse request (validate items ≥ 2) + → Detect available providers (Tavily? Perplexity? OpenAI?) + → If Tavily available: search each item individually + → Synthesize via best available provider: + Priority 1: Tavily search + Perplexity synthesis + Priority 2: Tavily search + OpenAI synthesis + Priority 3: OpenAI only (no web search) + → Validate structured JSON output + → Persist to database + → Stream results to client +``` + +### 7.2 Provider Details + +| Provider | Role | Model | Cost | +|---|---|---|---| +| Tavily | Web search | Search API | ~$0.005/search | +| Perplexity | Synthesis | Sonar | ~$0.002/query | +| OpenAI | Synthesis | GPT-4o-mini | ~$0.15/1M tokens | + +### 7.3 Progress Stages (SSE) +1. `parsing` — Validating query and extracting items +2. `searching` — Running web search for each item (Tavily only) +3. `researching` — Processing research per item +4. `synthesizing` — LLM generating structured comparison +5. `complete` — Final result with all data +6. `error` — Failure with error message + +## 8. Security Considerations + +- Auth middleware protects `/compare` and `/profile` routes +- Session tokens stored in HTTP-only cookies +- API keys never exposed to client (server-only LLM calls) +- Input validation on all API endpoints (min 2 items, max 10) +- SQL injection prevented via Drizzle ORM parameterized queries +- CSRF protection via Better Auth +- Rate limiting placeholder in compare API route + +## 9. Future Considerations + +- [ ] OAuth providers (Google, GitHub) +- [ ] Comparison comments/likes +- [ ] Export to PDF/image +- [ ] Embeddable comparison widgets +- [ ] Comparison templates +- [ ] Batch comparison queue for heavy loads +- [ ] Local Ollama fallback for offline operation diff --git a/docs/ui-ux-flow.md b/docs/ui-ux-flow.md new file mode 100644 index 0000000..abd3383 --- /dev/null +++ b/docs/ui-ux-flow.md @@ -0,0 +1,343 @@ +# ComparAIson — UI/UX Flow + +## User Journeys + +### Journey 1: New User Discovers → Signs Up → First Comparison + +``` +Landing Page (/) + │ + ▼ "Start Comparing" CTA or /compare URL +Sign In Page (/sign-in) + │ ─── "Don't have an account? Sign up" + ▼ +Sign Up Page (/sign-up) + │ User enters: name, email, password + │ On success → redirect to /compare + ▼ +Compare Page (/compare) + │ User enters items (2-10) + query + │ Clicks "Start Research" + ▼ +Streaming Progress + │ Progress bar + current step label + │ Steps: "Analyzing..." → "Searching React..." → "Synthesizing..." + ▼ +Results Page (/compare/[slug]) + │ Tab layout: Overview | Charts | Table | Details + │ User explores visualizations + │ Comparison auto-saved to profile + ▼ +Profile Page (/profile) + │ Sees their first comparison in the grid + └── Can click to view again +``` + +### Journey 2: Returning User Quick Compare + +``` +Home (/) → already logged in + │ + ▼ Click "Compare" in nav +Compare Page (/compare) + │ Enter items + query → "Start Research" + ▼ +Results Page (/compare/[slug]) + │ Review results, share URL + └── Return to profile or start new compare +``` + +### Journey 3: Anonymous User Browses Public Comparisons + +``` +Landing Page (/) + │ + ▼ "Explore" in nav or example comparison card +Explore Page (/explore) + │ Grid of public comparisons + │ Filter by category tags + │ Search by keyword + ▼ Click a comparison card +Results Page (/compare/[slug]) + │ View full results (read-only) + │ "Start Your Own Comparison" CTA if not logged in + └── Sign up flow from Journey 1 +``` + +--- + +## Page Descriptions + +### 1. Landing Page (`/`) +**Purpose:** First impression, explain the product, drive sign-ups + +**Layout:** +``` +┌─────────────────────────────────────────────┐ +│ Header: Logo "ComparAIson" | [Sign In] │ +├─────────────────────────────────────────────┤ +│ │ +│ ✨ AI-Powered Research │ +│ │ +│ Compare Anything with │ +│ AI-Powered Deep Research │ +│ │ +│ [🚀 Start Comparing] [Explore Examples] │ +│ │ +├─────────────────────────────────────────────┤ +│ Example Comparisons (2x2 grid) │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ React vs Vue │ │ GPT-4 vs │ │ +│ │ vs Svelte │ │ Claude vs │ │ +│ │ ⭐ 8.5 │ │ Gemini ⭐ 8.8│ │ +│ └──────────────┘ └──────────────┘ │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ Notion vs │ │ AWS vs GCP │ │ +│ │ Obsidian │ │ vs Azure │ │ +│ └──────────────┘ └──────────────┘ │ +├─────────────────────────────────────────────┤ +│ Features (3 columns) │ +│ 📊 Rich Viz 🔍 Deep Research 🔗 Share │ +├─────────────────────────────────────────────┤ +│ Footer │ +└─────────────────────────────────────────────┘ +``` + +### 2. Sign In Page (`/sign-in`) +**Purpose:** Authenticate existing users + +**Layout:** +``` +Centered card, max-w-md: +┌─────────────────────────────┐ +│ Sign In │ +│ Welcome back │ +│ │ +│ Email [______________] │ +│ Password [______________] │ +│ │ +│ [ Sign In ] │ +│ │ +│ Don't have an account? │ +│ [Sign Up] │ +└─────────────────────────────┘ +``` + +- Error state: Red text below form on invalid credentials +- Loading state: Spinner on button, disabled inputs +- Success: Redirect to callbackUrl or /compare + +### 3. Sign Up Page (`/sign-up`) +**Purpose:** Register new users + +**Layout:** Same as sign in but with Name field added +``` +Name [______________] +Email [______________] +Password [______________] +[ Create Account ] +Already have an account? [Sign In] +``` + +### 4. Compare Page (`/compare`) +**Purpose:** Main comparison creation interface + +**Layout:** +``` +Centered card, max-w-2xl: +┌─────────────────────────────────────────┐ +│ ✨ Start a Comparison │ +│ Enter items to compare and let AI │ +│ do deep research for you. │ +│ │ +│ What would you like to compare? │ +│ [________________________________] │ +│ (textarea for natural language query) │ +│ │ +│ Items to compare (min 2, max 10) │ +│ [React ×] [Vue ×] [Svelte ×] [+ Add] │ +│ [________________________] [Add] │ +│ │ +│ Comparison dimensions (optional) │ +│ [________________________________] │ +│ (comma-separated hints) │ +│ │ +│ [🚀 Start Research] │ +│ │ +│ ┌─ Progress (shown during research) ──┐ │ +│ │ [████████████░░░░░░░] 60% │ │ +│ │ 🔍 Researching Svelte... │ │ +│ └─────────────────────────────────────┘ │ +└─────────────────────────────────────────┘ +``` + +**Interactions:** +- Tag-style item input: type + Enter to add, X to remove +- Minimum 2 items required to start +- Progress bar appears after "Start Research" clicked +- Cancel button during research +- Auto-redirect to results on completion + +### 5. Results Page (`/compare/[slug]`) +**Purpose:** Display completed comparison with visualizations + +**Layout:** +``` +┌─────────────────────────────────────────────────┐ +│ ← Back React vs Vue vs Svelte [Share] │ +│ Overall: React ⭐ 8.5 | Vue ⭐ 7.8 | Svelte ⭐ 8.2│ +├─────────────────────────────────────────────────┤ +│ [Overview] [Charts] [Table] [Details] │ +├─────────────────────────────────────────────────┤ +│ │ +│ ┌── Overview Tab ─────────────────────────────┐ │ +│ │ │ │ +│ │ Summary text from AI │ │ +│ │ "React excels in ecosystem size..." │ │ +│ │ │ │ +│ │ ┌─ Score Cards ────────────────────────┐ │ │ +│ │ │ React: ⭐ 8.5 │ │ │ +│ │ │ [█████████░] Performance: 8/10 │ │ │ +│ │ │ [████████░░] DX: 9/10 │ │ │ +│ │ │ ... │ │ │ +│ │ └──────────────────────────────────────┘ │ │ +│ │ │ │ +│ │ 🏆 Recommendation: "For most projects..." │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ┌── Charts Tab ──────────────────────────────┐ │ +│ │ │ │ +│ │ Radar Chart Bar Chart │ │ +│ │ ┌─────────────┐ ┌──────────────┐ │ │ +│ │ │ ╱ React ╲ │ │ ▓ ▓ ▓ │ │ │ +│ │ │ │ Vue │ │ │ ▓ ▓ ▓ │ │ │ +│ │ │ ╲Svelte╱ │ │ ▓ ▓ ▓ │ │ │ +│ │ └─────────────┘ └──────────────┘ │ │ +│ │ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ┌── Table Tab ───────────────────────────────┐ │ +│ │ │ React │ Vue │ Svelte │ │ │ +│ │ Performance│ 8 │ 7 │ 9 │ │ │ +│ │ DX │ 9 │ 8 │ 8 │ │ │ +│ │ Ecosystem │ 10 │ 7 │ 6 │ │ │ +│ │ Price │ 9 │ 9 │ 10 │ │ │ +│ └──────────────────────────────────────────────┘ │ +│ │ +│ ┌── Details Tab ─────────────────────────────┐ │ +│ │ Per-item expandable deep dives │ │ +│ │ ▶ React - Performance (8/10) │ │ +│ │ Pros: Virtual DOM, concurrent mode... │ │ +│ │ Cons: Bundle size can grow... │ │ +│ │ ▶ Vue - Performance (7/10) │ │ +│ │ ... │ │ +│ └──────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────┘ +``` + +**Interactions:** +- Tab switching between Overview/Charts/Table/Details +- Hover tooltips on all charts +- Click legend items to toggle visibility on radar/bar charts +- Expandable rows in table for detailed breakdowns +- Share button copies URL to clipboard +- Trophy icon highlights the winner + +### 6. Profile Page (`/profile`) +**Purpose:** User's personal comparison library + +**Layout:** +``` +┌─────────────────────────────────────────────┐ +│ [Avatar] Alex Johnson │ +│ alex@example.com │ +│ │ +│ ┌─ Stats ─────────┐ ┌─ Stats ──────────┐ │ +│ │ 12 │ │ 8.2K │ │ +│ │ Total Comparisons│ │ Total Views │ │ +│ └──────────────────┘ └───────────────────┘ │ +│ │ +│ My Comparisons │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ React vs Vue │ │ GPT-4 vs │ │ +│ │ vs Svelte │ │ Claude │ │ +│ │ ⭐ 8.5 | 👁 1.2K│ │ ⭐ 8.8 | 👁 3.9K│ │ +│ │ Jan 15, 2024 │ │ Jan 10, 2024 │ │ +│ └──────────────┘ └──────────────┘ │ +│ │ +│ [+ New Comparison] │ +└─────────────────────────────────────────────┘ +``` + +### 7. Explore Page (`/explore`) +**Purpose:** Browse public comparisons from all users + +**Layout:** +``` +┌─────────────────────────────────────────────────┐ +│ Explore Comparisons │ +│ [🔍 Search comparisons...] │ +│ │ +│ [All] [Tech] [Products] [AI] [Cloud] [Prod.] │ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │React vs │ │GPT-4 vs │ │iPhone vs│ │ +│ │Vue vs │ │Claude vs │ │Samsung │ │ +│ │Svelte │ │Gemini │ │S24 Ultra│ │ +│ │⭐8.5 👁1.2K│ │⭐8.8 👁3.9K│ │⭐8.2 👁3.4K│ │ +│ │by Alex │ │by Sarah │ │by James │ │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │AWS vs │ │Python vs│ │Notion vs│ │ +│ │GCP vs │ │Rust vs │ │Obsidian │ │ +│ │Azure │ │Go │ │vs Roam │ │ +│ │⭐9.0 👁2.2K│ │⭐8.4 👁1.9K│ │⭐7.5 👁892 │ │ +│ │by Emma │ │by Anna │ │by Mike │ │ +│ └─────────┘ └─────────┘ └─────────┘ │ +│ │ +│ [Load More] │ +└─────────────────────────────────────────────────┘ +``` + +--- + +## Responsive Design + +### Desktop (≥768px) +- Sidebar navigation on the left +- Full-width comparison tables +- Side-by-side charts on Charts tab +- 3-column grid on Explore page + +### Mobile (<768px) +- Bottom navigation bar (fixed) +- Stacked charts (full width each) +- Single column cards on Explore +- Collapsible navigation menu + +--- + +## Loading & Error States + +### Research Progress +``` +┌─ Research in Progress ──────────────┐ +│ [████████████░░░░░░░░░] 60% │ +│ 🔍 Researching Svelte... │ +│ │ +│ Items: React ✓ Vue ✓ Svelte ⟳ │ +│ │ +│ [Cancel] │ +└──────────────────────────────────────┘ +``` + +### Skeleton Loaders +- Used on results page while data loads +- Shimmer effect on card placeholders +- Chart skeleton rectangles + +### Error States +- **API error:** Red banner with error message + "Try Again" button +- **Auth required:** Redirect to sign-in with callback +- **Not found:** 404 page with "Browse comparisons" link +- **Network error:** Toast notification + retry prompt