TopherMayor/comparaison
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Christopher Mayor
2026-04-24 15:02:40 -07:00
parent 5bde4e3aa6
commit aac0e2f5b1
6 changed files with 1057 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

204
docs/api-reference.md Normal file
View File

@@ -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<string, DimensionResult>;
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<string, DimensionResult>;
pros: string[];
cons: string[];
}[];
dimensions: string[];
tags: string[];
isPublic: boolean;
viewCount: number;
createdAt: string;
updatedAt: string;
}
```

129
docs/architecture.md Normal file
View File

@@ -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 |

86
docs/development.md Normal file
View File

@@ -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

163
docs/specs.md Normal file
View File

@@ -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

343
docs/ui-ux-flow.md Normal file
View File

@@ -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