debate/.planning/ROADMAP.md

Roadmap: Debate

Overview

Debate transforms Linux distribution customization from command-line complexity into visual creativity. The roadmap follows a dependency-driven path: secure infrastructure first, then overlay and build systems, then user-facing features (accounts, 2D interface, speeches), and finally polish (3D visualization, advanced dependency resolution, multi-distribution content). Each phase delivers verifiable user value, building toward a platform where non-experts can visually customize Linux distributions with confidence.

Phases

Phase Numbering:

• Integer phases (1, 2, 3): Planned milestone work
• Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

Decimal phases appear between their surrounding integers in numeric order.

• Phase 1: Core Infrastructure & Security - Foundation with sandboxed build environment
• Phase 2: Overlay System Foundation - Layer management and composition engine
• Phase 3: Build Queue & Workers - ISO generation with archiso
• Phase 4: User Accounts - Authentication and user profiles
• Phase 5: Builder Interface (2D) - Functional UI without 3D visualization
• Phase 6: Speeches & Community - Save, share, and discover configurations
• Phase 7: 3D Visualization - Interactive stack visualization (core differentiator)
• Phase 8: Advanced Dependency Resolution - SAT solver with visual conflict resolution
• Phase 9: Distribution Content - Multiple platforms and opening statements

Phase Details

Phase 1: Core Infrastructure & Security

Goal: Production-ready backend infrastructure with security-hardened build environment Depends on: Nothing (first phase) Requirements: INFR-01, INFR-02, INFR-03, INFR-04, INFR-05, INFR-06, INFR-07, ISO-04 Success Criteria (what must be TRUE):

1. FastAPI backend serves requests with <200ms p95 latency
2. PostgreSQL database accepts connections with daily backups configured
3. All traffic flows over HTTPS with valid certificates
4. API endpoints enforce rate limiting and CSRF protection
5. ISO builds execute in sandboxed containers (systemd-nspawn) with no host access
6. Build environment produces deterministic ISOs (identical input = identical hash) Plans: 5 plans

Plans:

• 01-01-PLAN.md — FastAPI project setup with health endpoints
• 01-02-PLAN.md — PostgreSQL database with async SQLAlchemy and Alembic
• 01-03-PLAN.md — Security middleware (rate limiting, CSRF, headers)
• 01-04-PLAN.md — Caddy HTTPS and database backup automation
• 01-05-PLAN.md — systemd-nspawn sandbox with deterministic builds

Phase 2: Overlay System Foundation

Goal: Layer-based configuration system with dependency tracking and composition Depends on: Phase 1 Requirements: OVLY-01, OVLY-02, OVLY-03, OVLY-04, OVLY-05, OVLY-06, OVLY-07, OVLY-10 Success Criteria (what must be TRUE):

1. System can store overlay manifests with metadata (name, version, type, description, author, license)
2. Manifests define relationships (requires, conflicts, provides, replaces) via YAML schema
3. Manifests support user-configurable options (toggle, select, text, number)
4. System detects direct conflicts between selected overlays before build
5. System enforces layer hierarchy: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument
6. System builds dependency graph from selected overlays
7. Overlay engine merges layers with correct precedence (higher layers override lower) Plans: TBD

Plans:

• 02-01: TBD (during phase planning)

Phase 3: Build Queue & Workers

Goal: Asynchronous ISO generation with queue management and caching Depends on: Phase 2 Requirements: ISO-01, ISO-02, ISO-03, ISO-05, ISO-06, ISO-07 Success Criteria (what must be TRUE):

1. User can initiate ISO build when configuration is valid
2. User sees queue position and estimated wait time
3. User sees build progress with stage updates (package install, customization, ISO creation)
4. ISO builds complete within 15 minutes
5. Identical configurations serve cached ISO immediately (no rebuild)
6. User can download completed ISO
7. Build failures show clear error messages explaining what went wrong Plans: TBD

Plans:

• 03-01: TBD (during phase planning)

Phase 4: User Accounts

Goal: User authentication, profiles, and personal dashboard Depends on: Phase 1 Requirements: USER-01, USER-02, USER-03, USER-04, USER-05, USER-06, USER-07, USER-08, USER-09, USER-10, USER-11, USER-12, USER-13, USER-14, USER-15 Success Criteria (what must be TRUE):

1. User can register with email/password or via GitHub/Google OAuth
2. User receives email verification after registration
3. User can log in and session persists across browser refresh
4. User can reset forgotten password via email link
5. User can set unique username, upload avatar, and write bio
6. User can view dashboard showing saved speeches, published speeches, and build history
7. Other users can view public profiles (username, avatar, bio, published speeches) Plans: TBD

Plans:

• 04-01: TBD (during phase planning)

Phase 5: Builder Interface (2D)

Goal: Functional configuration UI with layer management (no 3D yet) Depends on: Phase 2, Phase 3 Requirements: BUILD-04, BUILD-05, BUILD-06, BUILD-09, BUILD-10, BUILD-11 Success Criteria (what must be TRUE):

1. User can browse and search available overlays in layer panel with filtering
2. User can add layers to configuration from panel
3. User can remove layers from configuration
4. When conflicts arise, user sees "Objection!" modal with conflict details
5. User can resolve conflicts via Concede (remove layer), Rebut (swap layer), or Withdraw (undo)
6. User can access 2D fallback interface on low-end devices
7. User can build valid configuration and initiate ISO generation from UI Plans: TBD

Plans:

• 05-01: TBD (during phase planning)

Phase 6: Speeches & Community

Goal: Save, publish, browse, and discover community configurations Depends on: Phase 4, Phase 5 Requirements: SPCH-01, SPCH-02, SPCH-03, SPCH-04, SPCH-05, SPCH-06, SPCH-07, SPCH-08, SPCH-09, SPCH-10, SPCH-11, SPCH-12, OVLY-11, OVLY-12, OVLY-13, OVLY-14 Success Criteria (what must be TRUE):

1. User can save current configuration as named speech with description and topics (tags)
2. Non-authenticated users can save speeches locally in browser storage
3. Authenticated users can publish speeches publicly
4. User can browse community speeches in grid view with mini previews
5. User can filter speeches by topics, base distribution, window manager, author
6. User can sort speeches by popularity, rating, recent, trending
7. User can load community speech into builder
8. User can rate community speeches
9. Users can submit new overlays via GitHub PR workflow
10. Submitted overlays undergo automated schema validation and security scanning
11. Approved overlays appear in builder Plans: TBD

Plans:

• 06-01: TBD (during phase planning)

Phase 7: 3D Visualization

Goal: Interactive 3D stack visualization making configuration tangible Depends on: Phase 5 Requirements: BUILD-01, BUILD-02, BUILD-03, BUILD-07, BUILD-08 Success Criteria (what must be TRUE):

1. User sees configuration as interactive 3D stack of layers
2. User can rotate and zoom the 3D visualization with mouse/touch
3. User can click a layer in 3D space to select it and see details
4. 3D visualization runs at 60fps on mid-range hardware (Intel UHD Graphics)
5. Conflicting layers visually pulse red and lift off the stack
6. Animations are smooth and responsive to user interaction Plans: TBD

Plans:

• 07-01: TBD (during phase planning)

Phase 8: Advanced Dependency Resolution

Goal: SAT solver-based dependency resolution with intelligent conflict suggestions Depends on: Phase 2, Phase 5 Requirements: OVLY-08, OVLY-09 Success Criteria (what must be TRUE):

1. System detects missing requirements and shows clear warnings
2. System suggests compatible alternative overlays when conflicts arise
3. System topologically sorts overlays for correct application order
4. Dependency resolution completes in <1 second for typical configurations (50-100 overlays)
5. Conflict explanations help users understand why overlays are incompatible
6. Alternative suggestions are contextually relevant (same type, similar features) Plans: TBD

Plans:

• 08-01: TBD (during phase planning)

Phase 9: Distribution Content

Goal: Multiple window managers and base distributions available Depends on: Phase 2 Requirements: DIST-01, DIST-02, DIST-03, DIST-04, DIST-05, DIST-06, DIST-07, DIST-08, DIST-09, DIST-10 Success Criteria (what must be TRUE):

1. CachyOS available as Opening Statement
2. Pure Arch and EndeavourOS available as Opening Statements
3. Omarchy opinions (theming, apps, configs) mapped to overlays
4. Hyprland, Sway, and i3 available as Platform overlays
5. KDE Plasma, COSMIC, and GNOME available as Platform overlays
6. User can select any base distribution and combine with any compatible platform
7. Each platform includes working configuration that boots successfully Plans: TBD

Plans:

• 09-01: TBD (during phase planning)

Progress

Execution Order: Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9

Phase	Plans Complete	Status	Completed
1. Core Infrastructure & Security	0/5	Planned	-
2. Overlay System Foundation	0/TBD	Not started	-
3. Build Queue & Workers	0/TBD	Not started	-
4. User Accounts	0/TBD	Not started	-
5. Builder Interface (2D)	0/TBD	Not started	-
6. Speeches & Community	0/TBD	Not started	-
7. 3D Visualization	0/TBD	Not started	-
8. Advanced Dependency Resolution	0/TBD	Not started	-
9. Distribution Content	0/TBD	Not started	-