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

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