512 lines
14 KiB
Markdown
512 lines
14 KiB
Markdown
# 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.*
|