206 lines
7.2 KiB
Markdown
206 lines
7.2 KiB
Markdown
# 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.
|