debate/docs/INITIAL_PROMPT.md

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.