mikkel/debate
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
debate/.planning/REQUIREMENTS.md
Mikkel Georgsen fd1d931fac docs(01): complete Core Infrastructure & Security phase 
Phase 1 verified with:
- FastAPI latency: 27ms avg (well under 200ms p95)
- PostgreSQL: Running with daily backups configured
- HTTPS: Caddy TLS termination working
- Security: Rate limiting (100/min) and CSRF configured
- Sandbox: Code complete (runtime requires Arch environment)
- Deterministic builds: Unit tests pass

8 requirements satisfied: ISO-04, INFR-01 through INFR-07

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-25 20:34:55 +00:00

257 lines
10 KiB
Markdown
Raw Blame History

# Requirements: Debate
**Defined:** 2026-01-25
**Core Value:** Make Linux customization visual and accessible to non-experts
## v1 Requirements
Requirements for initial release. Each maps to roadmap phases.
### Builder Interface
- [ ] **BUILD-01**: User can view configuration as interactive 3D stack of layers
- [ ] **BUILD-02**: User can rotate and zoom the 3D visualization
- [ ] **BUILD-03**: User can click a layer to select it and see details
- [ ] **BUILD-04**: User can add layers from the layer panel
- [ ] **BUILD-05**: User can remove layers by dragging off stack
- [ ] **BUILD-06**: User can search and filter available overlays in the panel
- [ ] **BUILD-07**: User sees smooth 60fps animations on mid-range hardware
- [ ] **BUILD-08**: Conflicting layers pulse red and lift off stack
- [ ] **BUILD-09**: User sees "Objection!" modal when conflicts arise
- [ ] **BUILD-10**: User can resolve conflicts via Concede (remove), Rebut (swap), or Withdraw (undo)
- [ ] **BUILD-11**: User can access 2D fallback interface on low-end devices
### ISO Generation
- [ ] **ISO-01**: User can initiate ISO build ("Deliver") when configuration is valid
- [ ] **ISO-02**: User sees queue position and estimated wait time
- [ ] **ISO-03**: User sees build progress with stages
- [x] **ISO-04**: ISO builds run in sandboxed environment (systemd-nspawn)
- [ ] **ISO-05**: Identical configurations serve cached ISO immediately
- [ ] **ISO-06**: User can download completed ISO ("Take the Floor")
- [ ] **ISO-07**: Build failures report clear error messages to user
### Speeches (Saved Configurations)
- [ ] **SPCH-01**: User can save current configuration as named speech
- [ ] **SPCH-02**: User can add description and topics (tags) to speech
- [ ] **SPCH-03**: User can load saved speech into builder
- [ ] **SPCH-04**: Non-authenticated users can save locally (browser storage)
- [ ] **SPCH-05**: User can publish speech publicly
- [ ] **SPCH-06**: Published speeches are searchable by title/description
- [ ] **SPCH-07**: User can browse community speeches in grid view
- [ ] **SPCH-08**: User can filter speeches by topics, base distribution, window manager, author
- [ ] **SPCH-09**: User can sort speeches by popularity, rating, recent, trending
- [ ] **SPCH-10**: Speech cards show mini preview, title, author, topics, stats
- [ ] **SPCH-11**: User can load community speech into builder
- [ ] **SPCH-12**: User can rate community speeches
### User Accounts
- [ ] **USER-01**: User can register with email and password
- [ ] **USER-02**: User can log in with email and password
- [ ] **USER-03**: User session persists across browser refresh
- [ ] **USER-04**: User can log out
- [ ] **USER-05**: User can register/login via GitHub OAuth
- [ ] **USER-06**: User can register/login via Google OAuth
- [ ] **USER-07**: User receives email verification after registration
- [ ] **USER-08**: User can reset password via email link
- [ ] **USER-09**: User can set unique username
- [ ] **USER-10**: User can upload avatar image
- [ ] **USER-11**: User can write bio
- [ ] **USER-12**: User can view their saved speeches in dashboard
- [ ] **USER-13**: User can view their published speeches in dashboard
- [ ] **USER-14**: User can view build history in dashboard
- [ ] **USER-15**: Other users can view public profile (username, avatar, bio, published speeches)
### Overlay System
- [ ] **OVLY-01**: Overlays defined via YAML manifest schema
- [ ] **OVLY-02**: Manifests specify name, version, type, description, author, license
- [ ] **OVLY-03**: Manifests specify requires (dependencies), conflicts, provides, replaces
- [ ] **OVLY-04**: Manifests can define user-configurable options (toggle, select, text, number)
- [ ] **OVLY-05**: System builds dependency graph from selected overlays
- [ ] **OVLY-06**: System detects conflicts (objections) before build
- [ ] **OVLY-07**: System detects missing requirements and shows warnings
- [ ] **OVLY-08**: System suggests compatible alternatives when conflicts arise
- [ ] **OVLY-09**: System topologically sorts overlays for correct application order
- [ ] **OVLY-10**: Layer hierarchy enforced: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument
- [ ] **OVLY-11**: Users can submit new overlays via GitHub PR workflow
- [ ] **OVLY-12**: Submitted overlays undergo automated schema validation
- [ ] **OVLY-13**: Submitted overlays undergo security scan
- [ ] **OVLY-14**: Approved overlays appear in builder
### Distribution Support
- [ ] **DIST-01**: CachyOS available as Opening Statement
- [ ] **DIST-02**: Omarchy opinions mapped to overlays (theming, apps, configs)
- [ ] **DIST-03**: Hyprland available as Platform
- [ ] **DIST-04**: Sway available as Platform
- [ ] **DIST-05**: i3 available as Platform
- [ ] **DIST-06**: KDE Plasma available as Platform
- [ ] **DIST-07**: COSMIC available as Platform
- [ ] **DIST-08**: GNOME available as Platform
- [ ] **DIST-09**: Pure Arch available as Opening Statement
- [ ] **DIST-10**: EndeavourOS available as Opening Statement
### Infrastructure
- [x] **INFR-01**: API response time < 200ms (p95)
- [x] **INFR-02**: ISO build completes within 15 minutes
- [x] **INFR-03**: Platform available 99.9% uptime
- [x] **INFR-04**: User data protected and backed up daily
- [x] **INFR-05**: All traffic over HTTPS
- [x] **INFR-06**: Rate limiting on API endpoints
- [x] **INFR-07**: CSRF protection enabled
## v2 Requirements
Deferred to future release. Tracked but not in current roadmap.
### Enhanced Build Features
- **ISO-V2-01**: Build size calculator shows real-time estimate
- **ISO-V2-02**: Live log output visible during build (collapsible)
- **ISO-V2-03**: Multi-format export (ISO, USB image, Ventoy-compatible)
### Live Preview
- **PREV-01**: User can boot generated ISO in browser via WebVM
- **PREV-02**: Preview runs without downloading full ISO
### Additional Distributions
- **DIST-V2-01**: Fedora available as Opening Statement
- **DIST-V2-02**: Ubuntu available as Opening Statement
- **DIST-V2-03**: Cross-distro package mapping layer
### Collaboration
- **COLLAB-01**: Multiple users can edit same speech simultaneously
- **COLLAB-02**: Speech version history with diff view
### Moderation
- **MOD-01**: Users can flag inappropriate speeches
- **MOD-02**: Admin can review flagged content
- **MOD-03**: Admin can remove/hide violating speeches
- **MOD-04**: Admin can warn/ban users
## Out of Scope
Explicitly excluded. Documented to prevent scope creep.
| Feature | Reason |
|---------|--------|
| Mobile application | Web-first, desktop browser target; mobile can come later |
| Direct installation to hardware | Users download ISO and install themselves |
| Paid/premium tiers | v1 is free to establish user base |
| Enterprise features | Focus on individual users and community |
| Cross-distribution support (Fedora/Ubuntu) | Deep > wide; get Arch family working perfectly first |
| Full NixOS-style declarative config | Too complex for target audience |
| Custom package repository hosting | Infrastructure burden, security liability |
| Post-install configuration management | Scope creep; link to Ansible/dotfiles instead |
| Secure Boot signing | Nice to have but not critical for target audience |
## Traceability
Which phases cover which requirements. Updated during roadmap creation.
| Requirement | Phase | Status |
|-------------|-------|--------|
| BUILD-01 | Phase 7 | Pending |
| BUILD-02 | Phase 7 | Pending |
| BUILD-03 | Phase 7 | Pending |
| BUILD-04 | Phase 5 | Pending |
| BUILD-05 | Phase 5 | Pending |
| BUILD-06 | Phase 5 | Pending |
| BUILD-07 | Phase 7 | Pending |
| BUILD-08 | Phase 7 | Pending |
| BUILD-09 | Phase 5 | Pending |
| BUILD-10 | Phase 5 | Pending |
| BUILD-11 | Phase 5 | Pending |
| ISO-01 | Phase 3 | Pending |
| ISO-02 | Phase 3 | Pending |
| ISO-03 | Phase 3 | Pending |
| ISO-04 | Phase 1 | Complete |
| ISO-05 | Phase 3 | Pending |
| ISO-06 | Phase 3 | Pending |
| ISO-07 | Phase 3 | Pending |
| SPCH-01 | Phase 6 | Pending |
| SPCH-02 | Phase 6 | Pending |
| SPCH-03 | Phase 6 | Pending |
| SPCH-04 | Phase 6 | Pending |
| SPCH-05 | Phase 6 | Pending |
| SPCH-06 | Phase 6 | Pending |
| SPCH-07 | Phase 6 | Pending |
| SPCH-08 | Phase 6 | Pending |
| SPCH-09 | Phase 6 | Pending |
| SPCH-10 | Phase 6 | Pending |
| SPCH-11 | Phase 6 | Pending |
| SPCH-12 | Phase 6 | Pending |
| USER-01 | Phase 4 | Pending |
| USER-02 | Phase 4 | Pending |
| USER-03 | Phase 4 | Pending |
| USER-04 | Phase 4 | Pending |
| USER-05 | Phase 4 | Pending |
| USER-06 | Phase 4 | Pending |
| USER-07 | Phase 4 | Pending |
| USER-08 | Phase 4 | Pending |
| USER-09 | Phase 4 | Pending |
| USER-10 | Phase 4 | Pending |
| USER-11 | Phase 4 | Pending |
| USER-12 | Phase 4 | Pending |
| USER-13 | Phase 4 | Pending |
| USER-14 | Phase 4 | Pending |
| USER-15 | Phase 4 | Pending |
| OVLY-01 | Phase 2 | Pending |
| OVLY-02 | Phase 2 | Pending |
| OVLY-03 | Phase 2 | Pending |
| OVLY-04 | Phase 2 | Pending |
| OVLY-05 | Phase 2 | Pending |
| OVLY-06 | Phase 2 | Pending |
| OVLY-07 | Phase 2 | Pending |
| OVLY-08 | Phase 8 | Pending |
| OVLY-09 | Phase 8 | Pending |
| OVLY-10 | Phase 2 | Pending |
| OVLY-11 | Phase 6 | Pending |
| OVLY-12 | Phase 6 | Pending |
| OVLY-13 | Phase 6 | Pending |
| OVLY-14 | Phase 6 | Pending |
| DIST-01 | Phase 9 | Pending |
| DIST-02 | Phase 9 | Pending |
| DIST-03 | Phase 9 | Pending |
| DIST-04 | Phase 9 | Pending |
| DIST-05 | Phase 9 | Pending |
| DIST-06 | Phase 9 | Pending |
| DIST-07 | Phase 9 | Pending |
| DIST-08 | Phase 9 | Pending |
| DIST-09 | Phase 9 | Pending |
| DIST-10 | Phase 9 | Pending |
| INFR-01 | Phase 1 | Complete |
| INFR-02 | Phase 1 | Complete |
| INFR-03 | Phase 1 | Complete |
| INFR-04 | Phase 1 | Complete |
| INFR-05 | Phase 1 | Complete |
| INFR-06 | Phase 1 | Complete |
| INFR-07 | Phase 1 | Complete |
**Coverage:**
- v1 requirements: 70 total
- Mapped to phases: 70
- Unmapped: 0
**Phase Distribution:**
- Phase 1 (Infrastructure & Security): 8 requirements
- Phase 2 (Overlay System Foundation): 8 requirements
- Phase 3 (Build Queue & Workers): 6 requirements
- Phase 4 (User Accounts): 15 requirements
- Phase 5 (Builder Interface 2D): 7 requirements
- Phase 6 (Speeches & Community): 16 requirements
- Phase 7 (3D Visualization): 5 requirements
- Phase 8 (Advanced Dependency Resolution): 2 requirements
- Phase 9 (Distribution Content): 10 requirements
---
*Requirements defined: 2026-01-25*
*Last updated: 2026-01-25 after roadmap creation*
Reference in a new issue View git blame Copy permalink