debate/.planning/research/STACK.md

Technology Stack

Project: Debate - Visual Linux Distribution Builder Researched: 2026-01-25 Overall Confidence: HIGH

Recommended Stack

Core Backend

Technology	Version	Purpose	Why	Confidence
Python	3.12+	Runtime environment	FastAPI requires 3.9+; 3.12 is stable and well-supported. Avoid 3.13 until ecosystem catches up.	HIGH
FastAPI	0.128.0+	Web framework	Industry standard for async Python APIs. Latest version adds Python 3.14 support, mixed Pydantic v1/v2 (though use v2), and ReDoc 2.x. Fast, type-safe, auto-docs.	HIGH
Pydantic	2.12.5+	Data validation	Required by FastAPI (>=2.7.0). V1 is deprecated and unsupported in Python 3.14+. V2 offers better build-time performance and type safety. No v3 exists.	HIGH
Uvicorn	0.30+	ASGI server	Production-grade ASGI server. Recent versions include built-in multi-process supervisor, eliminating need for Gunicorn in many cases. Use --workers N for multi-core.	HIGH

Database Layer

Technology	Version	Purpose	Why	Confidence
PostgreSQL	18.1+	Primary database	Latest major release (Nov 2025). PG 13 is EOL, PG 18 has latest security patches and performance improvements. Always run current minor release.	HIGH
SQLAlchemy	2.0+	ORM	Industry standard with recent type-hint improvements. Better raw performance than Tortoise ORM in most benchmarks. Async support via Core. Avoid 1.x (legacy).	HIGH
asyncpg	Latest	PostgreSQL driver	High-performance async Postgres driver. Used by SQLAlchemy async. Significantly faster than psycopg2.	MEDIUM
Alembic	Latest	Database migrations	Official SQLAlchemy migration tool. Standard choice, well-integrated ecosystem.	HIGH

Alternative considered: Tortoise ORM - simpler API, async-first, but SQLAlchemy 2.0's type hints and performance make it the safer long-term bet. Use SQLAlchemy unless team strongly prefers Django-style ORM.

Task Queue

Technology	Version	Purpose	Why	Confidence
Celery	5.6.2+	Distributed task queue	Latest stable (Jan 2026). Supports Python 3.9-3.13. Battle-tested for ISO builds. Redis transport is feature-complete. Overkill for simple tasks but essential for long-running ISO generation.	HIGH
Redis	6.2+	Message broker & cache	Celery backend. Version constraint updated in Kombu. Redis Sentinel ACL auth fixed in Celery 5.6.1. Also serves as cache layer for ISO metadata.	HIGH

Alternatives considered:

• RQ - Too simple for multi-hour ISO builds requiring progress tracking and cancellation
• Dramatiq - Good performance but smaller ecosystem; Celery's maturity wins for production workloads
• APScheduler - Not designed for distributed task execution

Decision: Celery despite complexity because ISO builds require:

• Progress tracking (partial results)
• Task cancellation (user aborts build)
• Resource limiting (only N builds concurrent)
• Retry logic (transient failures)

Core Frontend

Technology	Version	Purpose	Why	Confidence
React	19.2.3+	UI framework	Latest stable (Dec 2025). React 19.2 adds Activity API (hide/restore UI state), useEffectEvent, and Performance panel integration. Use 19.x for latest features.	HIGH
TypeScript	5.8+	Type system	Feb 2025 release. Adds --erasableSyntaxOnly for Node.js type-stripping, checked returns for conditional types, and performance optimizations. 5.9 expected 2026. Avoid bleeding edge 7.0 (Go rewrite).	HIGH
Vite	6.x+	Build tool	Instant HMR, ESM-native. Makimo reported 16.1s build vs 28.4s with CRA; 390ms startup vs 4.5s. Choose Vite over Next.js - no SSR needed (no SEO benefit for logged-in tool), microservice alignment, fast iteration.	HIGH

Why not Next.js: Project is SPA-first (no SEO requirement), needs architectural freedom for 3D integration, and benefits from Vite's dev speed. Next.js SSR optimization is wasted here.

3D Visualization

Technology	Version	Purpose	Why	Confidence
React Three Fiber	8.x+	React renderer for Three.js	Integrates Three.js with React paradigms. Outperforms vanilla Three.js at scale due to React scheduling. WebGPU support since Safari 26 (Sept 2025) makes this future-proof. Essential for project.	HIGH
Three.js	Latest r1xx	3D engine	Underlying 3D engine. R3F keeps up with Three.js releases. WebGPU renderer available, massive performance gains on modern browsers.	HIGH
@react-three/drei	Latest	Helper library	Essential helper abstractions (cameras, controls, loaders, HTML overlays). Industry standard R3F companion. Includes <Detailed /> for LOD (30-40% frame rate improvement).	HIGH
@react-three/postprocessing	Latest	Visual effects	Post-processing effects (bloom, SSAO, etc.) for visual polish. Based on pmndrs/postprocessing.	MEDIUM
leva	Latest	Debug controls	GUI controls for rapid 3D prototyping. Invaluable during development for tweaking camera angles, lighting, animation speeds.	MEDIUM

Critical 3D Performance Requirements (60fps mandate):

• Instancing and batching to keep <100 draw calls per frame (90% reduction possible)
• LOD using drei's <Detailed /> component
• Draco compression for geometry (90-95% file size reduction)
• KTX2 with Basis Universal for textures (10x memory reduction, GPU-compressed)
• Mutations in useFrame, NOT React state (avoid re-render overhead)

Why React Three Fiber over vanilla Three.js:

• Team is React-focused (TypeScript/React already chosen)
• Component reusability (layer cards, conflict modals)
• React scheduling prevents frame drops during state updates
• Ecosystem alignment (Vite, dev tools)

State Management

Technology	Version	Purpose	Why	Confidence
Zustand	5.x+	Global state	Sweet spot between Redux complexity and Context limitations. Zero dependencies, minimal boilerplate, excellent DevTools. Recommended for medium-large apps. Single store model fits this project.	HIGH

Alternatives considered:

• Redux Toolkit - Too heavyweight; boilerplate overhead not justified for this project's state complexity
• Jotai - Atom-based model is overkill; Zustand's single store simpler for stack-builder state
• Context API - Insufficient for complex 3D state synchronization and performance requirements

Decision: Zustand because:

• Configuration builder has central state (layers, conflicts, user selections)
• Need Redux DevTools support for debugging complex 3D interactions
• Performance matters (3D re-renders expensive)
• Team prefers minimal boilerplate

UI Components & Styling

Technology	Version	Purpose	Why	Confidence
Tailwind CSS	4.x+	Utility-first CSS	Industry standard. V4 released 2025 with @theme directive, OKLCH colors, improved performance. Essential for rapid UI development.	HIGH
shadcn/ui	Latest	Component library	Copy-paste React components (Radix UI + Tailwind). Full code ownership, no dependency bloat. Updated for Tailwind v4 and React 19 (forwardRefs removed). Default "new-york" style.	HIGH
Radix UI	Via shadcn/ui	Headless components	Accessibility primitives. Integrated via shadcn/ui; don't install separately unless custom components needed.	HIGH

Why shadcn/ui: Own the code, customize freely, no black-box dependencies. Perfect for design system that needs 3D integration (custom layer card components).

Form Management

Technology	Version	Purpose	Why	Confidence
React Hook Form	7.x+	Form library	Zero dependencies, minimal re-renders, smaller bundle than Formik. Active maintenance (Formik hasn't had commits in 1+ year). Native HTML5 validation + Yup integration.	HIGH
Zod	Latest	Schema validation	TypeScript-first validation. Pairs well with React Hook Form. Prefer over Yup for better TypeScript inference.	MEDIUM

Why not Formik: Inactive maintenance, heavier bundle, more re-renders due to controlled components. React Hook Form is 2026 standard.

Testing

Technology	Version	Purpose	Why	Confidence
Vitest	Latest	Unit/component tests	10-20x faster than Jest on large codebases. Jest-compatible API, native Vite integration. Browser Mode for real browser component testing.	HIGH
React Testing Library	Latest	Component testing	User-focused testing paradigm. Industry standard. Integrates with Vitest via @testing-library/react.	HIGH
Playwright	Latest	E2E testing	Browser automation for critical flows (signup, build ISO, resolve conflict). Keep E2E suite small (3-5 flows), rely on Vitest for coverage.	HIGH
MSW	Latest	API mocking	Mock Service Worker for intercepting network requests. Essential for testing without backend dependency.	MEDIUM

Testing strategy: Vitest for fast unit/component tests, Playwright for 3-5 critical E2E flows in CI. Avoid testing library churn - these are stable choices.

Infrastructure

Technology	Version	Purpose	Why	Confidence
Docker	Latest stable	Containerization	Multi-stage builds for lean images. FastAPI best practice: base on python:3.12-slim, separate dependency install stage. One process per container, scale at container level.	HIGH
Caddy	2.x+	Reverse proxy	REST API on localhost:2019 for programmatic route management (critical for adding/updating routes via Python control plane). Automatic HTTPS, simpler than Nginx for this use case. Atomic updates without reload.	HIGH

Why Caddy over Nginx/Traefik:

• Python control plane needs to dynamically manage routes (user ISO download endpoints)
• Caddy's JSON REST API is perfect for programmatic configuration
• Nginx requires .conf file generation + reload (not atomic)
• Traefik is overkill (designed for K8s label-based discovery)

Docker configuration:

• Uvicorn with --workers matching CPU cores (6 for build server)
• Caddy in front for HTTPS termination and routing
• Multi-stage builds: stage 1 installs deps, stage 2 copies installed packages (lean final image)
• Environment variables via pydantic-settings

ISO Generation

Technology	Version	Purpose	Why	Confidence
archiso	Latest	ISO builder	Official Arch Linux ISO builder. Use "releng" profile for full package set. Standard tool, well-documented, active maintenance.	HIGH
Docker (sandboxed)	Latest	Build isolation	Run archiso in sandboxed container for security. ISO builds from untrusted configs require isolation. Resource limits prevent abuse.	HIGH

archiso best practices (2026):

• Copy releng profile to ext4 partition (NTFS/FAT32 have permission issues)
• Use mksquashfs with: -b 1048576 -comp xz -Xdict-size 100% -always-use-fragments -noappend for best compression
• Place working dir on tmpfs if memory allows (speed improvement)
• Build command: mkarchiso -v -r -w /tmp/archiso-tmp -o /path/to/out_dir /path/to/profile/

Integration approach:

• Celery task receives config, generates archiso profile
• Spins up Docker container with archiso, mounts generated profile
• Monitors build progress, streams logs to frontend via WebSocket
• Caches resulting ISO by config hash

Development Tools

Technology	Version	Purpose	Why	Confidence
uv	Latest	Package manager	10-100x faster than pip (cold JupyterLab install: 2.6s vs 21.4s). Global cache saves disk space. Drop-in pip/pip-tools replacement. Astral's tool, active development.	HIGH
pre-commit	Latest	Git hooks	Auto-format, lint, type-check before commit. Standard Python ecosystem tool.	MEDIUM
Ruff	Latest	Linter & formatter	Rust-based Python linter/formatter. Replaces Black, isort, flake8, pylint. Blazing fast, zero config needed.	HIGH
mypy	Latest	Type checker	Static type checking for Python. Essential with Pydantic and FastAPI. Strict mode recommended.	MEDIUM
ESLint	Latest	JS/TS linter	Standard TypeScript linter. Use with typescript-eslint plugin.	MEDIUM
Prettier	Latest	Code formatter	Opinionated JS/TS/CSS formatter. Integrates with ESLint via eslint-config-prettier.	MEDIUM

Why uv over Poetry/pip-tools:

• Speed is critical for developer experience (instant feedback loop)
• uv is drop-in compatible (no workflow change)
• Poetry is slower, more opinionated (own venv logic)
• UV handles Python version management automatically

Python package installation pattern:

# Core dependencies managed by uv
uv pip install fastapi[all] uvicorn[standard] sqlalchemy[asyncio] celery[redis] pydantic-settings
uv pip install -D pytest pytest-asyncio ruff mypy pre-commit

Monitoring & Observability

Technology	Version	Purpose	Why	Confidence
Sentry	Latest SDK	Error tracking & APM	Auto-enabled with FastAPI. Captures stack traces, request context, user info. Flame charts for profiling. Industry standard. Set traces_sample_rate for performance monitoring.	HIGH
Prometheus	Latest	Metrics	Time-series metrics for tracking build queue depth, ISO generation times, API latency. Standard cloud-native monitoring.	MEDIUM
Grafana	Latest	Dashboards	Visualize Prometheus metrics. Standard pairing for observability.	MEDIUM

Observability strategy:

• Sentry for errors and APM (traces)
• Structured logging (JSON) for debugging
• Prometheus for custom metrics (ISO build duration, queue depth)
• Grafana for dashboards

Alternatives Considered

Category	Recommended	Alternative	Why Not	Confidence
Backend Framework	FastAPI 0.128+	Django/Flask	FastAPI's async, type safety, auto-docs superior for API-first app. Django is overkill, Flask is outdated.	HIGH
ORM	SQLAlchemy 2.0+	Tortoise ORM	Tortoise simpler but SQLAlchemy 2.0's type hints + performance + ecosystem maturity win. Benchmarks favor SQLAlchemy Core.	MEDIUM
Task Queue	Celery 5.6+	RQ, Dramatiq	RQ too simple for long-running builds. Dramatiq lacks ecosystem maturity. Celery's complexity justified for this use case.	HIGH
Build Tool	Vite 6+	Next.js 15+	No SSR needed (no SEO), Vite's dev speed critical, architectural freedom for 3D integration. Next.js SSR optimization wasted.	HIGH
3D Library	React Three Fiber 8+	Vanilla Three.js, Babylon.js	R3F integrates with React paradigm, better scaling. Vanilla Three.js requires manual integration. Babylon.js smaller ecosystem.	HIGH
State Mgmt	Zustand 5+	Redux Toolkit, Jotai	Redux too heavyweight. Jotai's atom model overkill for single-store use case. Zustand is sweet spot.	MEDIUM
Form Library	React Hook Form 7+	Formik	Formik unmaintained (1+ year no commits), heavier bundle, worse performance. RHF is 2026 standard.	HIGH
Reverse Proxy	Caddy 2+	Nginx, Traefik	Caddy's REST API critical for dynamic route management. Nginx requires file generation + reload. Traefik overkill.	HIGH
Package Mgr	uv	Poetry, pip-tools	uv's speed (10-100x) improves DX dramatically. Poetry is comprehensive but slow. uv is drop-in replacement.	MEDIUM
Component Lib	shadcn/ui	Material-UI, Ant Design	shadcn gives code ownership, zero dependency bloat. MUI/Ant are black boxes, harder to customize for 3D integration.	HIGH

Installation

Backend Setup

# Install uv (package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv

# Activate venv
source .venv/bin/activate

# Core dependencies
uv pip install \
  fastapi[all]==0.128.0 \
  uvicorn[standard]>=0.30.0 \
  sqlalchemy[asyncio]>=2.0.0 \
  asyncpg \
  alembic \
  celery[redis]==5.6.2 \
  redis>=6.2.0 \
  pydantic>=2.12.0 \
  pydantic-settings \
  sentry-sdk[fastapi]

# Development dependencies
uv pip install -D \
  pytest \
  pytest-asyncio \
  pytest-cov \
  httpx \
  ruff \
  mypy \
  pre-commit

# Install pre-commit hooks
pre-commit install

Frontend Setup

# Install Node.js 20+ (LTS)
# Use nvm/fnm for version management

# Create Vite + React + TypeScript project
npm create vite@latest frontend -- --template react-ts

cd frontend

# Core dependencies
npm install \
  react@latest \
  react-dom@latest \
  @react-three/fiber@latest \
  @react-three/drei@latest \
  @react-three/postprocessing@latest \
  three@latest \
  zustand@latest \
  react-hook-form@latest \
  zod@latest

# UI & styling
npm install \
  tailwindcss@latest \
  autoprefixer \
  postcss

# Initialize shadcn/ui (React 19 + Tailwind v4)
npx shadcn@latest init

# Development dependencies
npm install -D \
  @types/react \
  @types/react-dom \
  @types/three \
  vitest \
  @testing-library/react \
  @testing-library/jest-dom \
  playwright \
  @playwright/test \
  msw \
  eslint \
  @typescript-eslint/parser \
  @typescript-eslint/eslint-plugin \
  prettier \
  eslint-config-prettier \
  leva

# Initialize Playwright
npx playwright install

Infrastructure Setup

# Install Docker (use system package manager)
# Install Caddy
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy

# Install PostgreSQL 18.1
sudo apt install -y postgresql-18

# Install Redis
sudo apt install -y redis-server

# Install archiso (on Arch-based system or in Docker)
# Run on Arch Linux or in Arch container:
pacman -S archiso

Project Structure

debate/
├── backend/                    # FastAPI application
│   ├── app/
│   │   ├── api/               # API routes
│   │   ├── core/              # Config, security, dependencies
│   │   ├── crud/              # Database operations
│   │   ├── db/                # Database models, session
│   │   ├── schemas/           # Pydantic models
│   │   ├── services/          # Business logic
│   │   ├── tasks/             # Celery tasks (ISO generation)
│   │   └── main.py
│   ├── tests/
│   ├── alembic/               # Database migrations
│   ├── Dockerfile
│   ├── pyproject.toml
│   └── requirements.txt       # Generated by uv
├── frontend/                   # React + Vite application
│   ├── src/
│   │   ├── components/        # React components
│   │   │   ├── 3d/           # Three.js/R3F components
│   │   │   ├── ui/           # shadcn/ui components
│   │   │   └── forms/        # Form components
│   │   ├── stores/            # Zustand stores
│   │   ├── hooks/             # Custom React hooks
│   │   ├── lib/               # Utilities
│   │   ├── types/             # TypeScript types
│   │   └── main.tsx
│   ├── tests/
│   ├── e2e/                   # Playwright tests
│   ├── public/
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── tailwind.config.js
├── iso-builder/               # Archiso Docker container
│   ├── Dockerfile
│   └── profiles/              # Custom archiso profiles
├── docker-compose.yml         # Local development stack
├── Caddyfile                  # Caddy configuration
└── .planning/
    └── research/
        └── STACK.md           # This file

Version Pinning Strategy

• Python packages: Pin major.minor with >= (e.g., fastapi>=0.128.0) to get security patches
• Critical dependencies: Pin exact version for reproducibility (e.g., celery==5.6.2)
• Node packages: Use ^ for semver compatible updates (e.g., "react": "^19.2.3")
• Lock files: Commit uv.lock (Python) and package-lock.json (Node) for reproducible builds
• Docker base images: Pin to specific minor versions (e.g., python:3.12-slim) with digest for production

Security Considerations

• ISO builds run in sandboxed Docker containers with resource limits (prevent CPU/memory abuse)
• User uploads validated with strict schemas (Pydantic), never executed directly
• Caddy handles HTTPS termination with automatic Let's Encrypt certificates
• Database: Use asyncpg with prepared statements (SQL injection protection via SQLAlchemy)
• API: Rate limiting via FastAPI middleware (protect against abuse)
• Secrets: Environment variables only, never committed (use pydantic-settings)
• Sentry: Scrub sensitive data before sending error reports

Performance Targets

Metric	Target	Why
3D visualization	60fps	Core differentiator - must feel fluid on mid-range hardware
API response time	<100ms (p95)	User perception of responsiveness
ISO generation	<30min	Acceptable for custom distro build (archiso baseline)
Frontend bundle	<500KB gzipped	Fast initial load, code-split 3D assets
Database queries	<50ms (p95)	Adequate for CRUD operations
WebSocket latency	<50ms	Real-time build progress updates

How we achieve 60fps:

• LOD (Level of Detail) with drei's <Detailed /> - 30-40% frame rate improvement
• Draw call optimization: <100 per frame via instancing/batching
• Asset compression: Draco (geometry), KTX2 (textures)
• Mutation in useFrame, not React state (avoid re-render overhead)
• Web Workers for heavy computation (config validation off main thread)
• WebGPU renderer when available (Safari 26+, Chrome, Firefox)

Migration Path

This stack is greenfield-ready. No legacy migrations required.

Future considerations:

• TypeScript 7.0 (Go rewrite): Monitor but don't migrate until 2027+ when ecosystem stable
• React 20.x: Adopt when stable (likely 2027), no breaking changes expected based on 19.x pattern
• PostgreSQL 19: Upgrade when released (Sept 2026), follow minor release cadence
• Pydantic v3: Does not exist; stay on v2.x series

Sources

High Confidence (Official Docs / Context7):

• FastAPI Release Notes
• FastAPI Releases
• React Versions
• React 19.2 Release
• PostgreSQL Versioning Policy
• PostgreSQL 18.1 Release
• Celery Documentation - Redis
• Celery Releases
• TypeScript 5.8 Documentation
• TypeScript 5.8 Announcement
• archiso - ArchWiki
• React Hook Form Documentation
• shadcn/ui Documentation
• Sentry FastAPI Integration

Medium Confidence (Multiple credible sources agree):

• React Three Fiber vs Three.js 2026
• Vite vs Next.js 2025 Comparison
• State Management in 2025: Redux, Zustand, Jotai
• Zustand vs Redux vs Jotai Comparison
• Testing in 2026: Jest, RTL, Playwright
• FastAPI Docker Best Practices
• Caddy vs Nginx vs Traefik Comparison
• Python Package Management: uv vs Poetry
• SQLAlchemy vs Tortoise ORM Comparison
• React Hook Form vs Formik Comparison

Low Confidence (Single source, needs validation):

• 100 Three.js Best Practices (community guide, not official)
• Celery alternatives discussion threads (opinions vary widely)

---

Summary: This stack represents the 2026 industry standard for building a high-performance, type-safe, async Python API with a React 3D frontend. All major technologies are on current stable versions with active maintenance. The 60fps 3D visualization requirement is achievable with React Three Fiber and proper optimization techniques. ISO generation via Celery + archiso is proven (similar to distro builder tools). The stack avoids deprecated technologies (Formik, Python 3.8, Pydantic v1, Redux for this use case) and unproven bleeding-edge options (TypeScript 7.0, React Server Components without Next.js).