# Product Requirements Document (PRD)
# Project Debate - Linux Distribution Builder Platform

## 1. Product Vision

### 1.1 Vision Statement

Debate is the platform where Linux opinions compete. It empowers anyone to build their perfect Linux distribution by visually selecting, combining, and customizing preconfigured "opinions" - then generating a ready-to-install ISO.

### 1.2 Target Users

**Primary: Linux-Curious Switchers**
- Coming from Windows or macOS
- Heard about Linux through Steam Deck, YouTube, or word of mouth
- Want customization without command-line expertise
- Value aesthetics and user experience

**Secondary: Linux Enthusiasts**
- Already use Linux but want easier ricing/customization
- Want to share their configurations with others
- Interested in trying new setups without manual work

**Tertiary: Content Creators**
- YouTubers, streamers covering Linux
- Want visually interesting content
- Appreciate the "debate" terminology and UI for engagement

---

## 2. Terminology

The product uses debate/speech terminology throughout for personality and memorability:

| Concept | Term | Description |
|---------|------|-------------|
| Select an option | Take a stance | Choosing a specific configuration |
| Remove conflicting item | Concede | Giving up one option for another |
| Swap one thing for another | Rebut | Replacing an opinion with alternative |
| Base distribution layer | Opening statement | Foundation (Arch, CachyOS, Fedora, etc.) |
| Window manager layer | Platform | Where you stand (Hyprland, Sway, KDE, etc.) |
| Theming/ricing layer | Rhetoric | How it looks and feels |
| Application bundle layer | Talking points | What software is included |
| System configuration layer | Closing argument | Final system settings |
| Generate ISO | Deliver | Build and produce the final ISO |
| Saved configuration | Speech | A complete saved build |
| Community preset | Published speech | Shared configuration with tags |
| Tags/categories | Topics | How speeches are categorized |
| Conflict detected | Objection | Incompatible selections |
| Dependency satisfied | Sustained | Valid combination |
| Download ISO | Take the floor | Get your finished product |

---

## 3. User Journeys

### 3.1 New User - Quick Start

```
1. Land on homepage
2. See rotating 3D stack demo
3. Click "Start Fresh"
4. Presented with Opening Statement selection (CachyOS recommended)
5. Select Platform (Hyprland default, options shown)
6. See pre-selected Rhetoric and Talking Points (Omarchy defaults)
7. Review Closing Arguments (dual-boot toggle visible)
8. Click "Deliver"
9. Watch build animation
10. Download ISO
```

### 3.2 Existing User - Load and Modify Speech

```
1. Log in
2. Go to "My Speeches"
3. Load previous speech into builder
4. Modify one layer (e.g., swap theme)
5. Resolve any objections
6. Save as new speech or overwrite
7. Optionally publish
8. Deliver new ISO
```

### 3.3 Community Browser - Find a Speech

```
1. Click "Browse Speeches"
2. Filter by topics: gaming + hyprland
3. Sort by popularity
4. Preview speech (3D stack thumbnail + description)
5. Click "Load into Builder"
6. Optionally modify
7. Deliver
```

### 3.4 Contributor - Submit New Overlay

```
1. Fork overlay template from GitHub
2. Create manifest, configs, scripts
3. Test locally
4. Submit PR
5. Automated tests run
6. Community review
7. Merge → overlay appears in builder
```

---

## 4. Feature Requirements

### 4.1 Builder Interface (P0 - Must Have)

#### 4.1.1 3D Stack Visualization

**Description:** Interactive 3D representation of the configuration layers.

**Requirements:**
- Layers float in 3D space, stacked vertically
- User can rotate view (drag), zoom (scroll)
- Each layer has distinct color/glow based on type
- Selected layer highlights and expands slightly
- Smooth animations for all state changes (60fps target)
- Layers visually "snap" together when compatible

**Interactions:**
- Click layer → select it, show details in side panel
- Double-click layer → open layer detail modal
- Drag from panel → add new layer to stack
- Drag layer off stack → remove it

#### 4.1.2 Layer Panel (Right Side)

**Description:** Context-sensitive panel showing available options.

**States:**
- **No selection:** Shows available layers to add, organized by type
- **Layer selected:** Shows options within that layer (toggles, dropdowns, swaps)
- **Conflict active:** Shows resolution options

**Requirements:**
- Smooth transitions between states
- Search/filter within panel
- Clear visual hierarchy
- Conflict indicators (red) and compatibility indicators (green)

#### 4.1.3 Conflict Resolution

**Description:** Visual and interactive handling of incompatible selections.

**Requirements:**
- Conflicting layers pulse red
- Conflicting layers lift off stack slightly
- "Objection!" modal appears with options:
  - Concede (remove the conflicting overlay)
  - Rebut (swap for compatible alternative)
  - Withdraw (undo the action that caused conflict)
- Cannot proceed to Deliver with unresolved objections

#### 4.1.4 Deliver Flow

**Description:** ISO generation initiation and progress.

**Requirements:**
- "Deliver" button disabled until stack is valid
- "Deliver" button glows/pulses when ready
- Click triggers build queue submission
- Progress view shows:
  - Queue position (if applicable)
  - Build progress with stages
  - Estimated time remaining
  - Live log output (collapsible, for advanced users)
- Completion shows download button "Take the Floor"
- Option to save speech before/after delivery

---

### 4.2 Speeches (P0 - Must Have)

#### 4.2.1 Save Speech

**Requirements:**
- Save current stack as named speech
- Attach description (optional)
- Select topics (tags) from predefined + custom
- Save to user account (requires auth)
- Local save option for non-authenticated users (browser storage)

#### 4.2.2 Load Speech

**Requirements:**
- Load from user's saved speeches
- Load from community (published speeches)
- Load from URL/share link
- Loading replaces current stack (with confirmation if unsaved changes)

#### 4.2.3 Publish Speech

**Requirements:**
- Must be logged in
- Must have valid (deliverable) configuration
- Add title, description, topics
- Preview how it will appear in browser
- Agree to community guidelines
- Published speeches are public and searchable

#### 4.2.4 Speech Browser

**Requirements:**
- Grid view of speech cards
- Each card shows:
  - Mini 3D stack preview (or static image)
  - Title
  - Author
  - Topics (tags)
  - Rating/popularity indicator
  - Download count
- Filter by:
  - Topics (multi-select, AND logic)
  - Base distribution
  - Window manager
  - Author
- Sort by:
  - Popularity (downloads)
  - Rating
  - Recent
  - Trending
- Search by title/description
- Pagination or infinite scroll

---

### 4.3 Topics (Tags) (P0 - Must Have)

#### 4.3.1 Predefined Topics

**Use case:** `gaming` `dev` `productivity` `creative` `server` `htpc` `daily-driver` `minimal` `normie-friendly`

**Aesthetic:** `waifu` `cyberpunk` `retro` `nord` `dracula` `catppuccin` `gruvbox` `kanagawa` `minimal` `riced`

**Base:** `arch` `cachyos` `endeavour` `fedora` `ubuntu` (dynamic based on available opening statements)

**Platform:** `hyprland` `sway` `i3` `kde` `cosmic` `gnome` (dynamic based on available platforms)

**Other:** `privacy` `hardened` `lightweight` `bloated` `beginner-friendly`

#### 4.3.2 Custom Topics

**Requirements:**
- Users can add custom topics when publishing
- Custom topics require moderator approval to become searchable
- Frequently used custom topics promoted to predefined

---

### 4.4 User Accounts (P1 - Should Have)

#### 4.4.1 Authentication

**Requirements:**
- Email/password registration
- OAuth options (GitHub, Google)
- Email verification
- Password reset flow

#### 4.4.2 User Profile

**Requirements:**
- Username (unique)
- Avatar
- Bio (optional)
- List of published speeches
- Join date
- Stats (speeches published, total downloads)

#### 4.4.3 User Dashboard

**Requirements:**
- My Speeches (saved, published)
- Build history
- Account settings

---

### 4.5 ISO Generation (P0 - Must Have)

#### 4.5.1 Build Queue

**Requirements:**
- Builds queued and processed in order
- Priority for cached/popular configurations
- User sees queue position and estimated wait
- Builds timeout after 30 minutes
- Failed builds report error to user

#### 4.5.2 Build Process

**Requirements:**
- Start from base layer (CachyOS ISO or bootstrap)
- Apply overlays in order
- Run pre-install, install, post-install scripts
- Package into bootable ISO
- Generate checksum
- Store in cache

#### 4.5.3 Caching

**Requirements:**
- Cache key = hash of full configuration
- Identical configurations serve cached ISO immediately
- Cache expiry based on:
  - Time since last download (e.g., 30 days unused)
  - Upstream changes (base or overlay updates invalidate)
- Storage limit with LRU eviction

---

### 4.6 Overlay System (P0 - Must Have)

#### 4.6.1 Overlay Manifest Schema

```yaml
name: string                    # Unique identifier
display_name: string            # Human-readable name
version: string                 # Semver
type: enum                      # opening_statement | platform | rhetoric | talking_points | closing_argument
description: string             # Short description
author: string                  # Creator
license: string                 # License identifier

requires: list[string]          # Overlay names that must be present
conflicts: list[string]         # Overlay names that cannot coexist  
provides: list[string]          # Abstract capabilities this fulfills
replaces: list[string]          # Overlays this can substitute for

options: list[Option]           # User-configurable options within overlay
```

#### 4.6.2 Option Schema

```yaml
name: string                    # Identifier
display_name: string            # Human-readable
type: enum                      # toggle | select | text | number
default: any                    # Default value
choices: list[any]              # For select type
description: string             # Help text
```

#### 4.6.3 Dependency Resolution

**Requirements:**
- Build dependency graph from all selected overlays
- Detect cycles (error)
- Detect conflicts (show objection)
- Detect missing requirements (show warning with suggestions)
- Auto-suggest compatible alternatives when conflict arises
- Topologically sort overlays for correct application order

---

### 4.7 Admin/Moderation (P2 - Nice to Have)

#### 4.7.1 Overlay Submission Review

**Requirements:**
- Queue of submitted overlays pending review
- Automated checks (schema validation, security scan)
- Manual review interface
- Approve/reject with feedback
- Approved overlays auto-deploy to production

#### 4.7.2 Speech Moderation

**Requirements:**
- Flag inappropriate speeches
- Review queue for flagged content
- Remove/hide violating speeches
- User warnings/bans for repeat offenders

---

## 5. Non-Functional Requirements

### 5.1 Performance

| Metric | Target |
|--------|--------|
| Initial page load | < 3s |
| 3D visualization FPS | 60fps on mid-range hardware |
| API response time | < 200ms (p95) |
| ISO build time | < 15 minutes |
| Cached ISO retrieval | < 10 seconds |

### 5.2 Scalability

- Support 1000 concurrent builder sessions
- Support 100 concurrent ISO builds (queued)
- Support 100,000 published speeches
- Support 10,000 overlays

### 5.3 Reliability

- 99.9% uptime for web interface
- Build failures retry once automatically
- Data backed up daily
- ISO cache replicated

### 5.4 Security

- All traffic over HTTPS
- User passwords hashed (bcrypt/argon2)
- Overlay scripts run in sandboxed build environment
- No user data in ISO (built from clean state)
- Rate limiting on API endpoints
- CSRF protection

### 5.5 Accessibility

- Keyboard navigation for all builder functions
- Screen reader compatibility for core flows
- 2D fallback interface for low-end devices
- Color blind friendly conflict indicators (not just red/green)

---

## 6. UI/UX Specifications

### 6.1 Visual Style

**Aesthetic:** Sci-fi holographic interface, inspired by:
- TRON
- Iron Man's JARVIS UI
- Cyberpunk 2077 interfaces
- Modern "glassmorphism" trends

**Color Palette:**
- Dark background (#0a0a0f or similar)
- Accent glow colors for layers (cyan, magenta, orange)
- Red for conflicts/objections
- Green for sustained/compatible
- White/light gray for text

**Typography:**
- Monospace or tech-style font for headings
- Clean sans-serif for body text
- Code-style for technical details

### 6.2 Animations

- Layer hover: subtle lift + glow increase
- Layer select: expand + brighten
- Conflict: pulse red + shake
- Resolution: smooth transition to new state
- Build progress: layers merge downward with particles
- Success: celebratory glow/particles

### 6.3 Responsive Design

| Breakpoint | Layout |
|------------|--------|
| Desktop (1200px+) | Full 3D builder, side panel |
| Tablet (768-1199px) | 3D builder, panel as drawer |
| Mobile (< 768px) | 2D fallback, stacked layout |

---

## 7. Future Considerations (Post-v1)

- **Live preview:** Boot generated ISO in browser via WebVM
- **Collaboration:** Multiple users edit same speech
- **Versioning:** Speech version history with diff
- **Subscription:** Premium features (priority builds, private speeches)
- **Hardware profiles:** Optimize builds for specific hardware
- **Plugin system:** Third-party overlay sources
- **Desktop app:** Electron/Tauri app for offline speech editing
- **Direct install:** Network boot or USB writer integration

---

## 8. Open Questions

1. **Naming:** Is "Debate" the final name? Domain availability?
2. **Monetization:** How to sustain infrastructure costs long-term?
3. **Legal:** Licensing implications of generating ISOs from various sources?
4. **Moderation:** How much manual review is sustainable?
5. **Upstream relations:** Coordinate with Omarchy/CachyOS maintainers?

---

## 9. Appendix

### 9.1 Competitive Analysis

| Product | Approach | Limitation |
|---------|----------|------------|
| Omarchy | Pre-built opinionated ISO | No customization |
| archinstall | CLI installer with options | Not visual, limited scope |
| CachyOS installer | GUI with DE selection | Only affects initial install |
| NixOS | Declarative configuration | Steep learning curve |
| Fedora Spins | Pre-built variants | Fixed options, no mixing |

### 9.2 Reference Interfaces

- https://neocities.org (community vibes)
- https://pling.com (Linux customization sharing)
- https://unixporn.reddit.com (inspiration for aesthetics)
- PC part picker (configurator UX reference)

---

*This PRD is a living document and will be updated as requirements evolve.*