mikkel/debate
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
debate/docs/SOW.md
mikkel 5078dd2b22 Upload files to "docs"
2026-01-25 01:31:57 +00:00

9.5 KiB
Raw Blame History

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.