# 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.*