debate/.planning/research/SUMMARY.md

Project Research Summary

Project: Debate - Visual Linux Distribution Builder Domain: Web-based Linux distribution customization and ISO generation platform Researched: 2026-01-25 Confidence: MEDIUM-HIGH

Executive Summary

Debate is a web-based Linux distribution builder that uses a 3D visual interface to help users customize and build bootable ISOs. Expert research shows that successful distribution builders follow a layered web-queue-worker architecture: React frontend with 3D visualization (Three.js/React Three Fiber) communicating with a FastAPI backend that delegates long-running ISO builds to Celery workers using archiso. The recommended approach is to start with Arch Linux support (Omarchy use case), implement robust dependency resolution with SAT solvers, and build sandboxing into the infrastructure from day one.

The platform's core differentiator is visual conflict resolution - making dependency hell visible and solvable for non-experts through the "Objection" system in the debate metaphor. This positions Debate as "what Canva did for design, but for Linux customization." The recommended stack is modern 2026 technology: Python 3.12+ with FastAPI/Uvicorn/Celery, React 19+ with Vite/Zustand/React Three Fiber, PostgreSQL 18+, and Redis for task queuing.

Critical risks: (1) Unsandboxed build execution allowing malicious code in user overlays - archiso and PKGBUILD files execute arbitrary code, requiring systemd-nspawn/microVM isolation from day one. (2) Non-deterministic builds preventing reliable caching - timestamps and environment variables must be normalized for reproducible builds. (3) Upstream breaking changes from rolling release repos (Arch/CachyOS) - pin repository snapshots and test in staging. (4) Performance degradation of 3D visualization on mid-range hardware - enforce 60fps target on Intel UHD Graphics from the start. These risks are mitigated through early architectural decisions in Phase 1 infrastructure.

Key Findings

Recommended Stack

Research shows the 2026 industry standard for high-performance Python APIs with React 3D frontends combines async frameworks (FastAPI), modern build tools (Vite), and distributed task queues (Celery). The stack avoids deprecated technologies (Formik, Pydantic v1) and unproven bleeding-edge options (TypeScript 7.0).

Core technologies:

• FastAPI 0.128+ + Uvicorn 0.30+: Async Python framework with auto-docs and type safety. 300% better performance than sync frameworks for I/O-bound operations. Industry standard for API-first apps.
• React 19+ + Vite 6+: Modern frontend with instant HMR (16.1s build vs 28.4s CRA). Vite chosen over Next.js because no SSR needed (no SEO benefit for logged-in tool), faster dev speed critical, architectural freedom for 3D integration.
• React Three Fiber 8+ + Three.js: 3D visualization framework that integrates Three.js with React paradigms. Outperforms vanilla Three.js at scale due to React scheduling. WebGPU support since Safari 26 makes this future-proof.
• Celery 5.6.2+ + Redis 6.2+: Distributed task queue for long-running ISO builds requiring progress tracking, cancellation, resource limiting, and retry logic. RQ too simple, Dramatiq lacks ecosystem maturity.
• PostgreSQL 18.1 + SQLAlchemy 2.0+: Latest stable database (Nov 2025) with async ORM. Better type hints and performance than Tortoise ORM.
• archiso (latest): Official Arch Linux ISO builder using "releng" profile. Well-documented, active maintenance, proven approach.
• Zustand 5+: State management sweet spot between Redux complexity and Context limitations. Single store model fits stack-builder state, minimal boilerplate.
• Caddy 2+: Reverse proxy with REST API for programmatic route management (critical for dynamic ISO download endpoints). Simpler than Nginx for this use case.

Critical version notes: Python 3.12+ required (3.13 ecosystem immature), PostgreSQL 18.1 current stable (13 is EOL), Pydantic 2.12+ only (v1 deprecated, v3 doesn't exist), Celery 5.6.2+ for Redis Sentinel ACL auth fixes.

Expected Features

Research into existing distribution builders (archiso, Cubic, live-build, NixOS) reveals clear table stakes vs. competitive differentiators.

Must have (table stakes):

• Package Selection - Core functionality with search/categorization (Debate's "Talking Points")
• Base Distribution Selection - Foundation to build from, start with Arch only (Debate's "Opening Statement")
• ISO Generation - Bootable installation media as end product
• Configuration Persistence - Save and reload work (Debate's "Speech")
• Bootloader Configuration - UEFI + BIOS support via archiso (syslinux, GRUB, systemd-boot)
• Kernel/Locale/User Setup - Expected in all distribution builders

Should have (competitive differentiators):

• Visual Conflict Resolution - UNIQUE to Debate. Makes dependency hell visible through "Objection" system. Current tools show cryptic errors.
• Curated Starting Templates - Pre-configured setups (Omarchy) as gallery of "Opening Statements"
• Build Size Calculator - Real-time feedback prevents mistakes
• Visual Theme Customization - GUI for WM/themes/icons BEFORE install (tools like HyprRice only work post-install)
• Community Template Gallery - Browse/fork/share configs (social feature drives engagement)
• Conflict Explanation System - AI-assisted or rule-based explanations turning errors into learning moments

Defer (v2+):

• Live Preview in Browser - Very high complexity, requires VM infrastructure. Get manual testing feedback first.
• Multi-distro Support - Ubuntu/Fedora after Arch works perfectly. Deep > wide.
• Secure Boot - Nice to have but not critical for target audience (Linux-curious users likely disabling secure boot)
• Post-Install Configuration - Scope creep. Link to Ansible/dotfiles managers instead.

Anti-features (explicitly avoid):

• Full NixOS-style declarative config (too complex for target audience)
• Build everything locally (slow, blocks UX - use cloud workers)
• Custom package repository hosting (infrastructure burden, security liability)
• Native desktop app (limits accessibility - web-first, Electron wrapper later if needed)

Architecture Approach

Research shows successful distribution builders use layered web-queue-worker architecture with separation between frontend configuration, backend validation, and isolated build execution. The Debate platform should follow OverlayFS-inspired layer precedence (5 layers: Opening Statement → Platform → Rhetoric → Talking Points → Closing Argument), SAT-solver dependency resolution, and cache-first build strategy.

Major components:

1. React Frontend + Three.js Renderer - 3D visualization of layers/packages with configuration UI. State in React (app data) drives scene rendering. Performance target: 60fps on Intel UHD Graphics.
2. FastAPI Gateway - Stateless async API with Pydantic validation, request routing, WebSocket/SSE for real-time build progress. Separate routers by domain (configs, packages, builds).
3. Dependency Resolver - SAT solver (libsolv approach) translating package dependencies to logic clauses. Detects conflicts BEFORE build, suggests alternatives. Called during configuration save.
4. Overlay Engine - Layer composition with merge strategies (replace/append/deep-merge). Generates archiso profiles from layered configurations. Precedence: higher layers override lower.
5. Build Queue Manager (Celery) - Distributed task queue with priority scheduling. Job types: quick validation (seconds), full build (minutes), cache warming (low priority). One build per worker (CPU-intensive).
6. Build Execution Workers - archiso runners in sandboxed containers (systemd-nspawn/microVMs). Profile generation → package install → customization → ISO creation → object storage upload.
7. PostgreSQL + Object Storage - Configuration data, build metadata, user data in PostgreSQL. ISOs (1-4GB), logs, overlays in S3-compatible storage.

Critical patterns:

• Layered configuration precedence with OverlayFS-inspired merge strategies
• SAT-based dependency resolution using CDCL algorithm (NP-complete solved in milliseconds)
• Asynchronous build queue with progress tracking via WebSocket/SSE
• Cache-first strategy with config hash to reuse identical ISOs
• Reproducible builds with SOURCE_DATE_EPOCH, fixed locales, deterministic file ordering

Anti-patterns to avoid:

• Blocking API calls during build (use async queue)
• Duplicating state between React and Three.js (single source of truth)
• Storing large files in PostgreSQL (use object storage)
• Multiple builds per worker (resource contention)
• No dependency validation until build time (validate on save)

Critical Pitfalls

Research into archiso security incidents, rolling release challenges, and 3D web performance reveals systematic failure modes.

1. Unsandboxed User-Generated Package Execution - CHAOS RAT malware distributed through AUR packages in July 2025 using .install scripts. PKGBUILD files execute arbitrary code during build. Prevention: Never run user PKGBUILDs directly on build servers. Use systemd-nspawn/microVMs for isolation, static analysis on PKGBUILDs, network egress filtering, ephemeral containers discarded after each build. Phase 1 critical.

2. Non-Deterministic Build Reproducibility - Same configuration generates different ISO hashes, breaking cache invalidation and security verification. Prevention: Normalize timestamps (SOURCE_DATE_EPOCH), sort files deterministically, use fixed locales (LC_ALL=C), pin toolchain versions, disable ASLR during builds. Phase 1 critical.

3. Upstream Breaking Changes Without Version Pinning - CachyOS/Arch rolling repos update with breaking changes. All builds fail simultaneously. CachyOS had kernel stability issues in 2025. Prevention: Pin package repository snapshots by date (use archive.archlinux.org), staging environment testing, monitor upstream changelogs, gradual rollout (1% traffic). Phase 2 critical.

4. Dependency Hell Across Overlays - Multiple overlays declare conflicting package versions or file ownership. Build fails after 15 minutes or succeeds with broken ISO. Prevention: Pre-validate overlay compatibility during upload (extract file lists, check conflicts), SAT solver detects conflicts BEFORE build, curated overlay collections, priority system for file conflicts. Phase 3 critical.

5. 3D Visualization Performance Degradation - Works on RTX 4090 dev machines, runs at 5fps on target users' mid-range laptops. Prevention: Test on Intel UHD Graphics from day one, LOD (Level of Detail), instancing for repeated elements, Web Worker with OffscreenCanvas, 2D fallback UI, 60fps performance budget enforcement. Phase 4 critical.

Implications for Roadmap

Based on research findings, suggested 9-phase structure optimized for dependency ordering, risk mitigation, and value delivery:

Phase 1: Core Infrastructure & Security

Rationale: Foundation for all components. Build sandboxing and reproducibility MUST be architected from the start - retrofitting security is nearly impossible. No dependencies on complex logic. Delivers: Database schema, basic API scaffolding, object storage setup, sandboxed build environment, deterministic build configuration. Addresses: Basic architecture components, storage layer Avoids: Pitfall #1 (unsandboxed execution), Pitfall #2 (non-deterministic builds) Duration: 1-2 weeks Research needed: Standard patterns, skip /gsd:research-phase

Phase 2: Configuration Management

Rationale: Enables testing configuration storage before complex dependency resolution. Data models required for later phases. Delivers: Layer data models (5 debate layers), CRUD endpoints, basic validation, configuration save/load. Addresses: Configuration Persistence (table stakes), layered architecture foundation Uses: FastAPI, PostgreSQL, Pydantic Implements: Database persistence layer Duration: 1-2 weeks Research needed: Standard CRUD patterns, skip /gsd:research-phase

Phase 3: Dependency Resolver (Simplified)

Rationale: Provides early validation capability without full SAT solver complexity. Catches obvious conflicts before build. Delivers: Basic conflict detection (direct conflicts only, no SAT solver yet), immediate validation feedback. Addresses: Early error detection, improved UX Avoids: Pitfall #4 (dependency hell) - partial mitigation Duration: 1 week Research needed: Consider /gsd:research-phase for SAT solver integration patterns

Phase 4: Overlay Engine

Rationale: Requires configuration data models from Phase 2. Produces archiso profiles for Phase 5 builds. Core business logic. Delivers: Layer merging logic with precedence rules, profile generation for archiso, merge strategies (replace/append/deep-merge). Addresses: Core architecture component Uses: OverlayFS-inspired patterns Implements: Overlay Engine component Duration: 2 weeks Research needed: Standard patterns, skip /gsd:research-phase

Phase 5: Build Queue + Workers

Rationale: Depends on Overlay Engine for profile generation. Core value delivery - users can build ISOs. Implements web-queue-worker pattern. Delivers: Celery setup, basic build task, worker orchestration, sandboxed archiso execution, progress tracking. Addresses: ISO Generation (table stakes), asynchronous processing Uses: Celery, Redis, archiso, systemd-nspawn Avoids: Pitfall #3 (upstream breaking changes) via pinned repos Implements: Build Queue Manager, Build Execution Workers Duration: 2-3 weeks Research needed: Consider /gsd:research-phase for archiso integration specifics

Phase 6: Frontend (Basic)

Rationale: API must exist first (Phases 1-5). Provides usable interface for testing builds. No 3D yet - focus on functionality. Delivers: React UI for configuration (forms, lists), build submission, status polling. Addresses: User interface for table stakes features Uses: React 19, Vite, Zustand, shadcn/ui Duration: 2-3 weeks Research needed: Standard React patterns, skip /gsd:research-phase

Phase 7: Advanced Dependency Resolution

Rationale: Complex feature. System works with basic validation from Phase 3. Enables competitive differentiation. Delivers: Full SAT solver integration (libsolv approach), conflict explanations, alternative suggestions, visual conflict resolution UI. Addresses: Visual Conflict Resolution (core differentiator) Avoids: Pitfall #4 (dependency hell) - complete mitigation Implements: SAT-based Dependency Resolver Duration: 2-3 weeks Research needed: NEEDS /gsd:research-phase - SAT solver integration is complex, requires domain-specific research

Phase 8: 3D Visualization

Rationale: Polish/differentiator feature. Core functionality works without it. Requires mature configuration system to visualize. Delivers: Three.js integration, layer visualization in 3D space, visual debugging, performance optimization (LOD, instancing). Addresses: Visual Theme Customization (differentiator), unique UX Uses: React Three Fiber, Three.js, @react-three/drei Avoids: Pitfall #5 (performance degradation) via 60fps enforcement on mid-range hardware Implements: Three.js Renderer component Duration: 3-4 weeks Research needed: NEEDS /gsd:research-phase - 3D performance optimization patterns, LOD strategies, WebGPU considerations

Phase 9: Caching + Optimization

Rationale: Optimization after core features work. Requires usage data to tune effectively. Improves scalability. Delivers: Build cache with config hash, package cache, performance tuning, build deduplication, autoscaling. Addresses: Scalability, cost optimization Avoids: Pitfall #7 (queue starvation), improves cache invalidation from Pitfall #5 Duration: 1-2 weeks Research needed: Standard caching patterns, skip /gsd:research-phase

Phase Ordering Rationale

Why this order:

• Security first (Phase 1): Build sandboxing and reproducibility cannot be retrofitted - architectural from day one
• Data before logic (Phase 2 before 3-4): Configuration models required for dependency resolution and overlay engine
• Validation before build (Phase 3 before 5): Catch errors early, prevent wasted build resources
• Backend before frontend (Phases 1-5 before 6): API must exist for UI to consume
• Core features before polish (Phases 1-6 before 7-8): Prove value delivery before investing in differentiators
• Optimization last (Phase 9): Need usage patterns to optimize effectively

Dependency chain:

Phase 1 (Infrastructure)
  ↓
Phase 2 (Config Models) ──→ Phase 4 (Overlay Engine)
  ↓                              ↓
Phase 3 (Basic Validation)   Phase 5 (Build Queue)
  ↓                              ↓
Phase 6 (Frontend) ←──────────────┘
  ↓
Phase 7 (Advanced Dependency) & Phase 8 (3D Viz)
  ↓
Phase 9 (Optimization)

How this avoids pitfalls:

• Sandboxing in Phase 1 prevents Pitfall #1 (malicious code execution)
• Reproducible builds in Phase 1 enable Phase 9 caching
• Validation in Phase 3 reduces build failures from Pitfall #4
• Repository pinning in Phase 5 mitigates Pitfall #3
• Performance requirements in Phase 8 prevent Pitfall #5
• Build deduplication in Phase 9 addresses Pitfall #7

Research Flags

Phases needing deeper research during planning:

• Phase 7 (Advanced Dependency Resolution): SAT solver integration patterns are complex and domain-specific. Recommend /gsd:research-phase for libsolv/version-SAT integration approaches, CDCL algorithm implementation, conflict explanation strategies.
• Phase 8 (3D Visualization): Performance optimization for 60fps on mid-range hardware requires specialized knowledge. Recommend /gsd:research-phase for LOD strategies, instancing patterns, WebGPU migration paths, OffscreenCanvas integration.
• Phase 5 (Build Queue + Workers): Consider /gsd:research-phase for archiso integration specifics (profile generation, customization hooks, boot configuration).

Phases with standard patterns (skip research-phase):

• Phase 1 (Core Infrastructure): Standard FastAPI/PostgreSQL/Docker setup, well-documented
• Phase 2 (Configuration Management): CRUD patterns, standard database schema design
• Phase 3 (Basic Dependency Resolution): Simple conflict detection, no SAT solver complexity yet
• Phase 4 (Overlay Engine): File merging logic, well-understood patterns
• Phase 6 (Frontend Basic): Standard React/Vite setup, CRUD UI patterns
• Phase 9 (Caching + Optimization): Standard cache invalidation patterns, autoscaling approaches

Confidence Assessment

Area	Confidence	Notes
Stack	HIGH	All technologies verified via official docs, release notes, and Context7 library. Versions confirmed current and stable (Jan 2026).
Features	MEDIUM	Table stakes verified via archiso wiki and multiple distribution builder tools. Differentiators based on market gap analysis and community tools research. User journey mapping needs validation.
Architecture	MEDIUM-HIGH	Patterns based on established web-queue-worker architecture, archiso documentation, and multiple reference implementations. Component boundaries clear, but integration complexity requires validation.
Pitfalls	MEDIUM-HIGH	Security pitfalls verified via documented incidents (CHAOS RAT in AUR July 2025, CachyOS stability issues 2025). Performance pitfalls based on Three.js optimization guides. Dependency issues confirmed in Arch forums.

Overall confidence: MEDIUM-HIGH

Research is grounded in official documentation (FastAPI, archiso, React, PostgreSQL), verified incidents (AUR malware), and established architectural patterns (web-queue-worker, SAT solvers). Lower confidence areas are appropriately flagged for deeper research during planning (Phase 7 SAT solver, Phase 8 3D optimization).

Gaps to Address

Technical unknowns requiring validation during implementation:

• SAT solver integration complexity (Phase 7): How to integrate libsolv with Python/FastAPI? Performance characteristics for large dependency graphs? Conflict explanation generation strategies? → Recommend /gsd:research-phase before Phase 7 implementation.
• 3D performance on target hardware (Phase 8): Actual FPS achieved with layer visualization on Intel UHD Graphics? WebGPU adoption timeline? LOD effectiveness for package graphs? → Recommend /gsd:research-phase and early prototyping with performance testing.
• archiso customization limits (Phase 5): What can/can't be customized via profiles? Boot configuration edge cases? Multi-kernel support? → Validate via archiso ArchWiki and experimentation during Phase 5.
• Upstream repository stability (Phase 5): How frequently do CachyOS/Omarchy repos break compatibility? Optimal snapshot cadence? → Monitor during staging deployment, adjust pinning strategy based on data.

User experience unknowns requiring user testing:

• Target audience validation: Are "Windows refugees" actually the right target? Do they want 3D visualization or prefer simpler UI? → User testing during Phase 6 frontend development.
• Conflict explanation effectiveness: Can non-technical users understand dependency conflict explanations? What level of detail is helpful vs overwhelming? → User testing during Phase 7 development.
• Template gallery adoption: Will users share configurations? What incentives drive engagement? → Defer to post-MVP, validate demand first.

Business/operational unknowns:

• Build resource costs: What's the actual cost per build (CPU time, storage, bandwidth)? → Measure during beta deployment, implement quotas if needed.
• Support burden: What percentage of users need help debugging build failures? → Track during beta, inform UX improvements.

Sources

Primary (HIGH confidence)

Stack & Technology:

• FastAPI Release Notes - Version verification, features
• React 19.2 Release - Version confirmation, Activity API
• PostgreSQL 18.1 Release - Current stable version
• Celery Documentation - Redis - Official patterns
• TypeScript 5.8 Documentation - Features, compatibility
• archiso ArchWiki - Build process, configuration
• React Hook Form Documentation - Official API reference
• Sentry FastAPI Integration - Observability setup

Architecture:

• Libsolv SAT Solver - Official implementation
• OverlayFS Linux Kernel Docs - Layer merging concepts
• PostgreSQL Schema Design Best Practices - Official wiki
• Web-Queue-Worker Pattern - Azure - Microsoft official docs

Security Incidents:

• CHAOS RAT in AUR Packages - July 2025 malware incident
• Reproducible builds documentation - Official guides
• Linux Kernel reproducible builds - Official kernel docs

Secondary (MEDIUM confidence)

Comparative Analysis:

• React Three Fiber vs Three.js 2026 - Performance comparison
• Vite vs Next.js 2025 Comparison - Build tool decision
• State Management in 2025: Redux, Zustand, Jotai - Framework comparison
• FastAPI Architecture Patterns 2026 - Architecture guidance
• SQLAlchemy vs Tortoise ORM Comparison - ORM decision
• Python Package Management: uv vs Poetry - Tooling choice

Domain-Specific:

• Custom Archiso Tutorial 2024 - Implementation guide
• Package Conflict Resolution - Dependency issues
• CachyOS FAQ & Troubleshooting - Known issues
• CachyOS dependency errors - Upstream breakage example

Performance & Optimization:

• WebGL vs WebGPU performance - 3D optimization
• Building Efficient Three.js Scenes - Performance patterns
• OffscreenCanvas for WebGL - Threading optimization

Tertiary (LOW confidence)

User Experience:

• 10 Linux Mistakes Every Beginner Makes - User research, needs validation
• Choosing Linux Distro 2026 - Target audience insights
• UX Design Mistakes 2026 - General UX guidance

---

Research completed: 2026-01-25 Ready for roadmap: yes