commit 5078dd2b22d4cf1f04eb306198697a5ee6ec1e47 Author: mikkel Date: Sun Jan 25 01:31:57 2026 +0000 Upload files to "docs" diff --git a/docs/BRD.md b/docs/BRD.md new file mode 100644 index 0000000..beb9e1a --- /dev/null +++ b/docs/BRD.md @@ -0,0 +1,380 @@ +# Business Requirements Document (BRD) +# Project Debate - Linux Distribution Builder Platform + +## 1. Executive Summary + +### 1.1 Purpose + +This document defines the business requirements for Debate, a web-based platform enabling users to visually customize and generate Linux distribution ISOs. The platform addresses the growing demand for accessible Linux customization as users migrate from Windows and macOS. + +### 1.2 Opportunity + +The Linux desktop market is experiencing unprecedented growth driven by: + +- **Windows dissatisfaction:** Telemetry concerns, forced updates, Recall controversy, increasing hardware requirements +- **Steam Deck success:** Millions of users experiencing Linux gaming via SteamOS +- **Creator influence:** High-profile Linux adoptions (DHH, PewDiePie, Linus Tech Tips coverage) +- **Mac limitations:** Walled garden restrictions, repairability issues, software compatibility + +However, a critical gap exists: users want Linux but are overwhelmed by choice and intimidated by customization. Debate fills this gap by making Linux configuration visual, approachable, and shareable. + +### 1.3 Value Proposition + +**For Users:** Build your perfect Linux without becoming a Linux expert. + +**For the Community:** Share your configurations and compete for the best setups. + +**For Linux Adoption:** Lower the barrier to entry for millions of potential switchers. + +--- + +## 2. Business Objectives + +### 2.1 Primary Objectives + +| Objective | Metric | Target (Year 1) | +|-----------|--------|-----------------| +| User acquisition | Registered users | 50,000 | +| Engagement | Monthly active users | 10,000 | +| Content generation | Published speeches | 2,000 | +| Platform expansion | Supported base distributions | 5+ | +| Community growth | Active contributors | 100+ | + +### 2.2 Secondary Objectives + +| Objective | Metric | Target (Year 1) | +|-----------|--------|-----------------| +| Brand awareness | YouTube videos featuring Debate | 50+ | +| Ecosystem growth | Third-party overlays submitted | 500+ | +| Virality | Speeches shared externally | 10,000+ | + +### 2.3 Long-term Vision (3-5 Years) + +- Become the default way people discover and adopt Linux distributions +- Host the largest repository of community Linux configurations +- Partner with hardware vendors for optimized device-specific speeches +- Expand to adjacent markets (homelab configurations, development environments) + +--- + +## 3. Stakeholders + +### 3.1 Primary Stakeholders + +| Stakeholder | Interest | Influence | +|-------------|----------|-----------| +| Project Owner (Mikkel) | Product vision, strategic direction | High | +| End Users | Usability, features, reliability | High | +| Linux Community | Quality, openness, compatibility | Medium | +| Content Creators | Visual appeal, shareability | Medium | + +### 3.2 Secondary Stakeholders + +| Stakeholder | Interest | Influence | +|-------------|----------|-----------| +| Distribution Maintainers | Compatibility, upstream relations | Medium | +| Overlay Contributors | Submission process, recognition | Medium | +| Infrastructure Providers | Resource usage, costs | Low | + +--- + +## 4. Market Analysis + +### 4.1 Target Market Segments + +#### Segment 1: Windows Refugees (Primary) +- **Size:** Millions globally, growing +- **Characteristics:** Non-technical, value privacy and control, frustrated with Windows direction +- **Needs:** Easy transition, familiar workflow, "just works" experience +- **Willingness to pay:** Low initially, potential for premium features + +#### Segment 2: Enthusiast Customizers (Secondary) +- **Size:** Hundreds of thousands +- **Characteristics:** Already on Linux, enjoy ricing/customization, active in communities +- **Needs:** Time savings, sharing platform, inspiration +- **Willingness to pay:** Moderate for convenience features + +#### Segment 3: Content Creators (Tertiary) +- **Size:** Thousands +- **Characteristics:** YouTube/Twitch presence, need engaging content +- **Needs:** Visual tools, dramatic UI, shareable moments +- **Willingness to pay:** Moderate for features that improve content + +### 4.2 Competitive Landscape + +| Competitor | Strengths | Weaknesses | Debate Advantage | +|------------|-----------|------------|------------------| +| Vanilla distro installers | Official, supported | Limited customization | Full customization | +| archinstall | Flexible | CLI-only, intimidating | Visual interface | +| NixOS | Declarative, reproducible | Steep learning curve | Approachable | +| Linux Mint / Ubuntu | User-friendly | Opinionated, not customizable | User controls opinions | +| r/unixporn | Community, inspiration | No tooling, manual work | Automated generation | + +### 4.3 Differentiation + +Debate is unique in combining: +1. **Visual configuration** - No other tool offers 3D visualization of Linux builds +2. **Opinion-as-a-feature** - Explicitly surfacing and enabling override of distribution opinions +3. **Community sharing** - Speeches as a social/viral mechanism +4. **Memorable branding** - Debate terminology creates engagement and content potential + +--- + +## 5. Business Requirements + +### 5.1 Functional Requirements + +| ID | Requirement | Priority | Rationale | +|----|-------------|----------|-----------| +| BR-F01 | Users can visually build custom Linux configurations | Must Have | Core value proposition | +| BR-F02 | Users can generate bootable ISO from configuration | Must Have | Core value proposition | +| BR-F03 | Users can save configurations for later | Must Have | Return engagement | +| BR-F04 | Users can share configurations publicly | Must Have | Viral growth mechanism | +| BR-F05 | Users can browse and use community configurations | Must Have | Content discovery | +| BR-F06 | Users can tag configurations by topic | Must Have | Discoverability | +| BR-F07 | System detects and surfaces configuration conflicts | Must Have | User experience | +| BR-F08 | Community can contribute new overlays | Should Have | Platform scalability | +| BR-F09 | System caches popular configurations | Should Have | Cost efficiency | +| BR-F10 | Users can rate community configurations | Nice to Have | Quality signal | + +### 5.2 Non-Functional Requirements + +| ID | Requirement | Priority | Rationale | +|----|-------------|----------|-----------| +| BR-NF01 | Platform available 99.9% of time | Must Have | User trust | +| BR-NF02 | ISO generation completes within 15 minutes | Must Have | User experience | +| BR-NF03 | Interface performs smoothly on mid-range hardware | Must Have | Accessibility | +| BR-NF04 | Platform scales to 10,000 concurrent users | Should Have | Growth capacity | +| BR-NF05 | Generated ISOs boot successfully 99%+ of time | Must Have | User trust | +| BR-NF06 | User data protected and private | Must Have | Legal/trust | + +### 5.3 Compliance Requirements + +| ID | Requirement | Priority | Rationale | +|----|-------------|----------|-----------| +| BR-C01 | Respect open source licenses of included software | Must Have | Legal | +| BR-C02 | GDPR compliance for EU users | Must Have | Legal | +| BR-C03 | Clear attribution for upstream projects | Must Have | Community relations | +| BR-C04 | User content moderation capability | Should Have | Platform safety | + +--- + +## 6. Revenue Model + +### 6.1 Phase 1: Free (Launch - Year 1) + +All core features free to establish user base and community. + +**Cost coverage:** +- Personal infrastructure investment +- Community donations (optional) +- Potential sponsorships from Linux-adjacent companies + +### 6.2 Phase 2: Freemium (Year 2+) + +**Free Tier:** +- Unlimited configurations +- Standard build queue +- Public speeches only +- Community overlays + +**Premium Tier ($5-10/month):** +- Priority build queue +- Private speeches +- Advanced analytics on published speeches +- Custom branding removal +- Early access to new features + +**Supporter Tier ($20+/month):** +- All premium features +- Badge on profile +- Vote on feature roadmap +- Direct support channel + +### 6.3 Phase 3: Enterprise (Year 3+) + +**Enterprise Tier (Custom pricing):** +- Private overlay repositories +- Custom base distributions +- SLA guarantees +- Dedicated build infrastructure +- Hardware vendor optimizations + +### 6.4 Revenue Projections (Conservative) + +| Year | Users | Premium Conversion | MRR | +|------|-------|-------------------|-----| +| 1 | 50,000 | 0% (free) | $0 | +| 2 | 150,000 | 2% | $15,000-30,000 | +| 3 | 300,000 | 3% | $45,000-90,000 | + +--- + +## 7. Cost Structure + +### 7.1 Infrastructure Costs (Monthly) + +| Item | Cost | Notes | +|------|------|-------| +| Build server | $0 | Existing hardware (6 cores, 64GB RAM) | +| Web hosting | $50-100 | VPS for frontend + API | +| Database | $50-100 | Managed PostgreSQL | +| Object storage | $50-200 | ISO cache (scales with usage) | +| Bandwidth | Variable | Depends on ISO download volume | +| **Total** | **$150-400+** | | + +### 7.2 One-Time Costs + +| Item | Cost | Notes | +|------|------|-------| +| Domain registration | $20-50/year | debate.* or similar | +| Design assets | $0-500 | Logo, icons (optional) | +| Legal review | $0-1000 | License compliance (optional) | + +### 7.3 Opportunity Cost + +| Item | Hours/Week | Notes | +|------|------------|-------| +| Development | 10-20 | With AI assistance | +| Community management | 2-5 | Growing with user base | +| Maintenance | 2-5 | Ongoing | + +--- + +## 8. Risk Assessment + +### 8.1 Technical Risks + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| Upstream breaking changes | Medium | High | Automated testing, version pinning | +| Build system compromise | Low | Critical | Sandboxing, signing, audits | +| Scaling issues | Medium | Medium | Load testing, queue management | +| Browser compatibility | Low | Medium | Progressive enhancement | + +### 8.2 Business Risks + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| Low adoption | Medium | High | Strong launch marketing, YouTube focus | +| Community toxicity | Medium | Medium | Moderation tools, clear guidelines | +| Competitor emergence | Low | Medium | First-mover advantage, community moat | +| Maintainer burnout | Medium | High | Automation, community delegation | + +### 8.3 Legal Risks + +| Risk | Probability | Impact | Mitigation | +|------|-------------|--------|------------| +| License violation claims | Low | High | Legal review, clear attribution | +| Trademark issues | Low | Medium | Avoid trademarked names in branding | +| Liability for generated ISOs | Low | Medium | Terms of service, disclaimers | + +--- + +## 9. Success Criteria + +### 9.1 Launch Success (Month 1) + +- [ ] Platform publicly accessible +- [ ] 1,000+ users registered +- [ ] 100+ speeches published +- [ ] 1,000+ ISOs generated +- [ ] At least 3 YouTube videos covering Debate +- [ ] No critical bugs in production + +### 9.2 Short-term Success (Month 6) + +- [ ] 10,000+ users registered +- [ ] 5,000+ monthly active users +- [ ] 500+ speeches published +- [ ] 3+ base distributions supported +- [ ] 10+ community-contributed overlays +- [ ] Positive community sentiment + +### 9.3 Medium-term Success (Year 1) + +- [ ] 50,000+ users registered +- [ ] 10,000+ monthly active users +- [ ] 2,000+ speeches published +- [ ] 5+ base distributions supported +- [ ] 100+ community-contributed overlays +- [ ] Sustainable cost coverage +- [ ] Featured in major Linux publications + +--- + +## 10. Go-to-Market Strategy + +### 10.1 Pre-Launch (4 weeks before) + +- [ ] Teaser landing page with email signup +- [ ] Teaser video showing 3D interface +- [ ] Reach out to Linux YouTubers for early access +- [ ] Seed posts in r/linux, r/unixporn, Hacker News + +### 10.2 Launch Week + +- [ ] Public release announcement +- [ ] Launch post on Hacker News (time for peak visibility) +- [ ] Posts on Reddit (r/linux, r/archlinux, r/unixporn) +- [ ] Mastodon/X announcements +- [ ] Coordinate with early access YouTubers for launch day videos + +### 10.3 Post-Launch (Ongoing) + +- [ ] Weekly "Featured Speech" highlights +- [ ] Monthly "State of Debate" updates +- [ ] Community challenges ("Best gaming speech", etc.) +- [ ] Respond to all YouTube coverage +- [ ] Engage with community feedback actively + +### 10.4 Content Strategy + +**Owned content:** +- Blog posts on interesting speeches +- Tutorials for creating overlays +- Behind-the-scenes technical posts + +**Earned content:** +- YouTuber reviews and tutorials +- Reddit discussions +- Hacker News threads +- Linux publication features + +**Community content:** +- User-created speeches (inherently shareable) +- "Rate my speech" posts +- Overlay contributions + +--- + +## 11. Timeline Summary + +| Phase | Duration | Key Deliverables | +|-------|----------|------------------| +| Development | 20 weeks | Core platform, builder, ISO generation | +| Beta | 4 weeks | Private testing, bug fixes, polish | +| Launch | 1 week | Public release, marketing push | +| Growth | Ongoing | Features, community, expansion | + +--- + +## 12. Approval + +This document requires approval from the Project Owner before development begins. + +| Role | Name | Signature | Date | +|------|------|-----------|------| +| Project Owner | Mikkel | ____________ | ____________ | + +--- + +## 13. Document History + +| Version | Date | Author | Changes | +|---------|------|--------|---------| +| 1.0 | January 2026 | Claude (AI) | Initial draft | + +--- + +*This BRD is a living document and will be updated as business requirements evolve.* diff --git a/docs/INITIAL_PROMPT.md b/docs/INITIAL_PROMPT.md new file mode 100644 index 0000000..6a9063b --- /dev/null +++ b/docs/INITIAL_PROMPT.md @@ -0,0 +1,206 @@ +# Project Debate - Initial Development Prompt + +## Context + +You are helping build **Debate**, a web-based platform for visually customizing Linux distributions and generating ISOs. This is a greenfield project starting from scratch. + +Before writing any code, familiarize yourself with these documents: +- `SOW.md` - Statement of Work: scope, timeline, deliverables, technical architecture +- `PRD.md` - Product Requirements: features, user journeys, UI/UX specifications, terminology +- `BRD.md` - Business Requirements: objectives, market context, success criteria + +## Project Terminology + +This project uses debate/speech terminology throughout. Use these terms consistently in code, UI, comments, and documentation: + +| Concept | Term | Code Convention | +|---------|------|-----------------| +| Select an option | Take a stance | `takeStance()`, `stance` | +| Remove conflicting item | Concede | `concede()`, `concession` | +| Swap one for another | Rebut | `rebut()`, `rebuttal` | +| Base distribution layer | Opening statement | `openingStatement`, `OpeningStatement` | +| Window manager layer | Platform | `platform`, `Platform` | +| Theming/ricing layer | Rhetoric | `rhetoric`, `Rhetoric` | +| Application bundle | Talking points | `talkingPoints`, `TalkingPoint` | +| System configuration | Closing argument | `closingArgument`, `ClosingArgument` | +| Generate ISO | Deliver | `deliver()`, `delivery` | +| Saved configuration | Speech | `speech`, `Speech` | +| Published preset | Published speech | `publishedSpeech` | +| Tags/categories | Topics | `topics`, `Topic` | +| Conflict detected | Objection | `objection`, `Objection` | +| Dependency satisfied | Sustained | `sustained`, `isSustained()` | +| Download ISO | Take the floor | `takeTheFloor()` | + +## Tech Stack + +Based on SOW.md section 4.1: + +**Backend:** +- Python 3.11+ +- FastAPI for API +- PostgreSQL for database +- SQLAlchemy or similar ORM +- Celery or similar for build queue + +**Frontend:** +- React 18+ +- TypeScript +- Three.js or React Three Fiber for 3D visualization +- TailwindCSS for styling + +**Infrastructure:** +- Docker for containerization +- Dedicated build server (6 cores, 64GB RAM, NVMe) +- S3-compatible object storage for ISO cache + +## Project Structure + +``` +debate/ +├── backend/ +│ ├── app/ +│ │ ├── api/ # FastAPI routes +│ │ ├── core/ # Config, security, dependencies +│ │ ├── models/ # SQLAlchemy models +│ │ ├── schemas/ # Pydantic schemas +│ │ ├── services/ # Business logic +│ │ │ ├── overlay/ # Overlay engine +│ │ │ ├── resolver/ # Dependency resolver +│ │ │ └── builder/ # ISO build orchestration +│ │ └── workers/ # Background tasks +│ ├── tests/ +│ ├── alembic/ # Migrations +│ └── requirements.txt +├── frontend/ +│ ├── src/ +│ │ ├── components/ +│ │ │ ├── builder/ # 3D stack visualization +│ │ │ ├── panels/ # Side panels +│ │ │ ├── modals/ # Objection resolution, etc. +│ │ │ └── common/ # Shared components +│ │ ├── hooks/ +│ │ ├── services/ # API client +│ │ ├── store/ # State management +│ │ ├── types/ +│ │ └── utils/ +│ ├── public/ +│ └── package.json +├── overlays/ # Overlay packages +│ ├── opening-statements/ +│ │ └── cachyos/ +│ ├── platforms/ +│ │ ├── hyprland/ +│ │ └── sway/ +│ ├── rhetoric/ +│ │ └── omarchy-aesthetic/ +│ └── talking-points/ +│ └── dhh-bundle/ +├── builder/ # ISO build scripts +│ ├── scripts/ +│ └── templates/ +├── docs/ +│ ├── SOW.md +│ ├── PRD.md +│ └── BRD.md +└── docker-compose.yml +``` + +## Phase 1 Priorities + +Start with these components in order (see SOW.md section 5, weeks 1-8): + +### 1. Data Model & Database + +Define SQLAlchemy models for: +- `Overlay` - overlay metadata, manifest storage +- `Speech` - saved configurations +- `User` - user accounts (can stub initially) +- `Build` - ISO build jobs and status +- `Topic` - tags for speeches + +Key relationships: +- Speech has many Overlays (ordered) +- Speech has many Topics +- Speech belongs to User +- Build belongs to Speech + +### 2. Overlay Schema & Parser + +Create the overlay manifest schema (see PRD.md section 4.6.1): +- YAML-based manifest format +- Parser/validator for manifests +- Loader for overlay packages from filesystem + +### 3. Dependency Resolver + +Implement the resolver (see PRD.md section 4.6.3): +- Build dependency graph from selected overlays +- Detect conflicts (objections) +- Detect missing requirements +- Suggest alternatives for conflicts +- Topological sort for application order + +### 4. Omarchy Opinion Mapping + +Analyze the Omarchy repository and create initial overlays: +- Map each "opinion" to an overlay or option +- Create opening-statement overlay for CachyOS base +- Create platform overlay for Hyprland +- Create rhetoric overlay for Omarchy theming +- Create talking-points overlay for DHH's app bundle +- Create closing-argument overlays for system configs + +Repository to analyze: https://github.com/basecamp/omarchy + +### 5. Basic API + +FastAPI endpoints for: +- `GET /overlays` - list available overlays +- `GET /overlays/{id}` - get overlay details +- `POST /speeches` - save a speech +- `GET /speeches/{id}` - load a speech +- `POST /builds` - queue an ISO build +- `GET /builds/{id}` - check build status + +## Coding Standards + +1. **Type everything** - Full type hints in Python, strict TypeScript +2. **Test critical paths** - Resolver logic, build orchestration +3. **Document public APIs** - Docstrings, OpenAPI schemas +4. **Use the terminology** - Consistently use debate terms in code +5. **Keep overlays declarative** - Minimize imperative logic in overlay packages +6. **Fail gracefully** - Clear error messages for users + +## First Task + +Start by setting up the project structure and implementing the data model. Create: + +1. Project directory structure as outlined above +2. Docker Compose for local development (PostgreSQL, Redis for queue) +3. FastAPI app skeleton with health check endpoint +4. SQLAlchemy models for core entities +5. Alembic migration for initial schema +6. Basic pytest setup + +After the foundation is in place, move to the overlay schema and dependency resolver. + +## Questions to Resolve During Development + +- Exact Omarchy repository structure and how opinions are encoded +- CachyOS package repository integration method +- ISO build toolchain (archiso, custom scripts, etc.) +- Frontend 3D library choice (Three.js vs R3F vs alternatives) +- State management approach (Zustand, Redux, Jotai, etc.) + +## Reference + +Always refer back to: +- **SOW.md** for scope, timeline, and technical decisions +- **PRD.md** for feature requirements and UX specifications +- **BRD.md** for business context and success metrics + +When in doubt about a feature or approach, check these documents first. If something isn't covered, ask for clarification before making assumptions. + +--- + +Let's build something great. Start with the project foundation. diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..913255d --- /dev/null +++ b/docs/PRD.md @@ -0,0 +1,512 @@ +# 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.* diff --git a/docs/SOW.md b/docs/SOW.md new file mode 100644 index 0000000..a449bb3 --- /dev/null +++ b/docs/SOW.md @@ -0,0 +1,255 @@ +# Statement of Work (SOW) +# Project Debate - Linux Distribution Builder Platform + +## 1. Project Overview + +**Project Name:** Debate +**Project Type:** Web-based Linux distribution customization and ISO generation platform +**Version:** 1.0 +**Date:** January 2026 + +### 1.1 Executive Summary + +Debate is a visual, web-based platform that enables users to customize Linux distributions by selecting, combining, and overriding "opinions" - preconfigured choices about packages, configurations, window managers, themes, and system behaviors. The platform generates custom ISO images based on user selections and supports community-contributed configurations ("speeches"). + +The initial implementation will use Omarchy (DHH's opinionated Arch Linux distribution) as the foundational opening statement, with CachyOS repositories providing optimized packages. The architecture is designed to support additional base distributions contributed by the community. + +### 1.2 Problem Statement + +Current barriers to Linux adoption include: +- Overwhelming number of distribution choices +- Difficulty customizing distributions without deep technical knowledge +- "Take it or leave it" approach to distribution opinions +- No visual, accessible way to understand what a distribution includes +- Fragmented community knowledge about configuration options + +### 1.3 Solution + +Debate provides: +- A visual 3D interface for building custom Linux configurations +- Modular overlay system where each "opinion" can be toggled or swapped +- Dependency resolution with visual conflict feedback +- Community-driven speech (preset) sharing +- Automated ISO generation with caching for popular configurations + +--- + +## 2. Scope of Work + +### 2.1 In Scope + +#### Phase 1: Core Platform +- [ ] Overlay system architecture and data model +- [ ] Dependency resolver with conflict detection +- [ ] Base layer support for CachyOS + Omarchy opinions +- [ ] Web application frontend with 3D stack visualization +- [ ] Speech (configuration) save/load functionality +- [ ] ISO generation pipeline +- [ ] ISO caching system + +#### Phase 2: Community Features +- [ ] User accounts and authentication +- [ ] Speech publishing and sharing +- [ ] Tagging system for speeches +- [ ] Speech browsing and filtering +- [ ] Rating/voting system +- [ ] Community submission workflow for new overlays + +#### Phase 3: Expansion +- [ ] Additional window manager support (Sway, i3, KDE, COSMIC, GNOME) +- [ ] Additional base distribution support (Fedora, Ubuntu, etc.) +- [ ] Package mapping layer for cross-distro compatibility +- [ ] API for third-party integrations + +### 2.2 Out of Scope (v1.0) +- Mobile application +- Direct installation (users download ISO and install themselves) +- Paid/premium tiers +- Enterprise features +- Hardware vendor partnerships + +--- + +## 3. Deliverables + +| ID | Deliverable | Description | Format | +|----|-------------|-------------|--------| +| D1 | Overlay System | Core engine for managing layered configurations | Python/Backend | +| D2 | Dependency Resolver | Conflict detection and resolution logic | Python/Backend | +| D3 | Web Frontend | 3D visual builder interface | React + Three.js | +| D4 | ISO Generator | Build pipeline for creating custom ISOs | Shell/Python | +| D5 | Caching System | ISO storage and cache invalidation | Backend + Storage | +| D6 | API | REST/GraphQL API for all operations | Python/FastAPI | +| D7 | Database | Schema and migrations | PostgreSQL | +| D8 | Omarchy Mapping | Complete mapping of Omarchy opinions | Data/YAML | +| D9 | Documentation | User docs, API docs, contributor guides | Markdown | + +--- + +## 4. Technical Architecture + +### 4.1 Stack Overview + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Frontend (React) │ +│ Three.js / React Three Fiber │ +├─────────────────────────────────────────────────────────────┤ +│ API Layer (FastAPI) │ +├──────────────────┬──────────────────┬───────────────────────┤ +│ Overlay Engine │ Dependency │ ISO Build Queue │ +│ │ Resolver │ │ +├──────────────────┴──────────────────┴───────────────────────┤ +│ PostgreSQL Database │ +├─────────────────────────────────────────────────────────────┤ +│ ISO Build Server │ +│ (Dedicated: 6 cores, 64GB RAM, NVMe) │ +├─────────────────────────────────────────────────────────────┤ +│ ISO Cache Storage │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 4.2 Overlay Package Structure + +``` +overlay/ +├── manifest.yaml # Metadata, dependencies, conflicts, provides +├── packages.yaml # Package list (distro-agnostic names) +├── configs/ # Configuration files to install +│ ├── hyprland/ +│ ├── waybar/ +│ └── ... +├── scripts/ +│ ├── pre-install.sh +│ ├── install.sh +│ └── post-install.sh +└── README.md +``` + +### 4.3 Layer Hierarchy + +``` +Opening Statement (Base) : Arch | CachyOS | Fedora | Ubuntu + ↓ +Platform (Window Manager) : Hyprland | Sway | i3 | KDE | COSMIC + ↓ +Rhetoric (Theming/Ricing) : Omarchy-style | Catppuccin | Nord | Custom + ↓ +Talking Points (Apps) : DHH bundle | Minimal | Gaming | Productivity + ↓ +Closing Argument (System) : Partitioning | Security | Boot | Services +``` + +--- + +## 5. Timeline + +### Phase 1: Core Platform (Weeks 1-8) + +| Week | Milestone | +|------|-----------| +| 1-2 | Data model design, overlay schema, database setup | +| 3-4 | Dependency resolver, conflict detection logic | +| 5-6 | Omarchy opinion mapping, initial overlays created | +| 7-8 | ISO generation pipeline, basic build queue | + +### Phase 2: Frontend (Weeks 9-14) + +| Week | Milestone | +|------|-----------| +| 9-10 | React app scaffolding, API integration | +| 11-12 | 3D stack visualization with Three.js | +| 13-14 | Builder UI, layer selection, conflict display | + +### Phase 3: Community & Polish (Weeks 15-20) + +| Week | Milestone | +|------|-----------| +| 15-16 | User auth, speech save/load/publish | +| 17-18 | Speech browser, tagging, filtering | +| 19-20 | ISO caching, performance optimization, testing | + +### Phase 4: Launch (Weeks 21-24) + +| Week | Milestone | +|------|-----------| +| 21-22 | Beta testing, community feedback | +| 23-24 | Public launch, documentation, marketing | + +--- + +## 6. Resources + +### 6.1 Infrastructure + +| Resource | Specification | Purpose | +|----------|---------------|---------| +| Build Server | 6 cores, 64GB RAM, NVMe | ISO generation | +| Web Server | Standard VPS | Frontend + API hosting | +| Database | PostgreSQL managed instance | Data storage | +| Object Storage | S3-compatible | ISO cache storage | + +### 6.2 Personnel + +| Role | Responsibility | +|------|----------------| +| Project Owner | Vision, decisions, community management | +| AI Assistant (Claude) | Development, code review, opinion mapping | + +--- + +## 7. Acceptance Criteria + +### 7.1 Core Functionality +- [ ] User can select a base layer (CachyOS) +- [ ] User can add/remove/swap overlays +- [ ] Conflicts are detected and displayed visually +- [ ] Valid configurations generate downloadable ISOs +- [ ] ISOs boot and function correctly + +### 7.2 Performance +- [ ] Builder UI loads in < 3 seconds +- [ ] 3D visualization runs at 60fps on mid-range hardware +- [ ] ISO generation completes in < 15 minutes +- [ ] Cached ISOs serve immediately + +### 7.3 Community +- [ ] Users can save and name speeches +- [ ] Users can publish speeches with tags +- [ ] Users can browse and filter community speeches +- [ ] Users can load a speech into the builder + +--- + +## 8. Risks and Mitigations + +| Risk | Impact | Likelihood | Mitigation | +|------|--------|------------|------------| +| Omarchy upstream changes break overlays | High | Medium | Automated testing on upstream updates, version pinning | +| ISO build queue overwhelmed | Medium | Medium | Aggressive caching, queue prioritization | +| 3D UI too heavy for low-end devices | Medium | Low | Fallback 2D interface option | +| Community submits malicious overlays | High | Low | Review process, sandboxed builds, signing | + +--- + +## 9. Success Metrics + +| Metric | Target (6 months post-launch) | +|--------|-------------------------------| +| Registered users | 10,000 | +| ISOs generated | 50,000 | +| Community speeches published | 500 | +| Additional base distributions | 3+ | +| YouTube videos featuring Debate | 20+ | + +--- + +## 10. Signatures + +| Role | Name | Date | +|------|------|------| +| Project Owner | Mikkel | ____________ | + +--- + +*This SOW is a living document and may be updated as the project evolves.*