debate/.planning/phases/01-core-infrastructure-security/01-01-PLAN.md

---
phase: 01-core-infrastructure-security
plan: 01
type: execute
wave: 1
depends_on: []
files_modified:
  - pyproject.toml
  - backend/app/__init__.py
  - backend/app/main.py
  - backend/app/core/__init__.py
  - backend/app/core/config.py
  - backend/app/api/__init__.py
  - backend/app/api/v1/__init__.py
  - backend/app/api/v1/router.py
  - backend/app/api/v1/endpoints/__init__.py
  - backend/app/api/v1/endpoints/health.py
  - .env.example
autonomous: true

must_haves:
  truths:
    - "FastAPI app starts without errors"
    - "Health endpoint returns 200 OK"
    - "Configuration loads from environment variables"
    - "Project dependencies install via uv"
  artifacts:
    - path: "pyproject.toml"
      provides: "Project configuration and dependencies"
      contains: "fastapi"
    - path: "backend/app/main.py"
      provides: "FastAPI application entry point"
      exports: ["app"]
    - path: "backend/app/core/config.py"
      provides: "Application configuration via pydantic-settings"
      contains: "BaseSettings"
    - path: "backend/app/api/v1/endpoints/health.py"
      provides: "Health check endpoint"
      contains: "@router.get"
  key_links:
    - from: "backend/app/main.py"
      to: "backend/app/api/v1/router.py"
      via: "include_router"
      pattern: "app\\.include_router"
    - from: "backend/app/api/v1/router.py"
      to: "backend/app/api/v1/endpoints/health.py"
      via: "include_router"
      pattern: "router\\.include_router"
---

<objective>
Establish the FastAPI backend project structure with configuration management and basic health endpoint.

Purpose: Create the foundational Python project that all subsequent infrastructure builds upon.
Output: A runnable FastAPI application with proper project structure, dependency management via uv, and environment-based configuration.
</objective>

<execution_context>
@/home/mikkel/.claude/get-shit-done/workflows/execute-plan.md
@/home/mikkel/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-core-infrastructure-security/01-RESEARCH.md (Standard Stack section, Architecture Patterns section)
</context>

<tasks>

<task type="auto">
  <name>Task 1: Initialize Python project with uv and dependencies</name>
  <files>pyproject.toml, .env.example</files>
  <action>
Create pyproject.toml with:
- Project name: debate-backend
- Python version: >=3.12
- Dependencies from research standard stack:
  - fastapi[all]>=0.128.0
  - uvicorn[standard]>=0.30.0
  - sqlalchemy[asyncio]>=2.0.0
  - asyncpg<0.29.0
  - alembic
  - pydantic>=2.12.0
  - pydantic-settings
  - slowapi
  - fastapi-csrf-protect
  - python-multipart
- Dev dependencies:
  - pytest
  - pytest-asyncio
  - pytest-cov
  - httpx
  - ruff
  - mypy

Configure ruff in pyproject.toml:
- line-length = 88
- target-version = "py312"
- select = ["E", "F", "I", "N", "W", "UP"]

Create .env.example with documented environment variables:
- DATABASE_URL (postgresql+asyncpg://...)
- SECRET_KEY (for JWT/CSRF)
- ENVIRONMENT (development/production)
- DEBUG (true/false)
- ALLOWED_HOSTS (comma-separated)
- ALLOWED_ORIGINS (comma-separated, for CORS)

Initialize project with uv: `uv venv && uv pip install -e ".[dev]"`
  </action>
  <verify>
Run: `cd /home/mikkel/repos/debate && uv pip list | grep -E "(fastapi|uvicorn|sqlalchemy|pydantic)"`
Expected: All core dependencies listed with correct versions.
  </verify>
  <done>
pyproject.toml exists with all specified dependencies, virtual environment created, packages installed.
  </done>
</task>

<task type="auto">
  <name>Task 2: Create FastAPI application structure with health endpoint</name>
  <files>
backend/app/__init__.py
backend/app/main.py
backend/app/core/__init__.py
backend/app/core/config.py
backend/app/api/__init__.py
backend/app/api/v1/__init__.py
backend/app/api/v1/router.py
backend/app/api/v1/endpoints/__init__.py
backend/app/api/v1/endpoints/health.py
  </files>
  <action>
Create directory structure following research architecture:
```
backend/
  app/
    __init__.py
    main.py
    core/
      __init__.py
      config.py
    api/
      __init__.py
      v1/
        __init__.py
        router.py
        endpoints/
          __init__.py
          health.py
```

backend/app/core/config.py:
- Use pydantic-settings BaseSettings
- Load: database_url, secret_key, environment, debug, allowed_hosts, allowed_origins
- Parse allowed_hosts and allowed_origins as lists (comma-separated in env)
- Set sensible defaults for development

backend/app/main.py:
- Create FastAPI app with title="Debate API", version="1.0.0"
- Disable docs in production (docs_url=None if production)
- Include v1 router at /api/v1 prefix
- Add basic health endpoint at root /health (outside versioned API)

backend/app/api/v1/router.py:
- Create APIRouter
- Include health endpoint router with prefix="/health", tags=["health"]

backend/app/api/v1/endpoints/health.py:
- GET /health returns {"status": "healthy"}
- GET /health/ready for readiness check (will add DB check in next plan)

All __init__.py files should be empty (or contain only necessary imports).
  </action>
  <verify>
Run: `cd /home/mikkel/repos/debate && source .venv/bin/activate && uvicorn backend.app.main:app --host 0.0.0.0 --port 8000 &`
Wait 2 seconds, then: `curl -s http://localhost:8000/health | grep -q healthy && echo "Health check passed"`
Kill the server.
  </verify>
  <done>
FastAPI application starts, health endpoint returns {"status": "healthy"}.
  </done>
</task>

</tasks>

<verification>
1. `uv pip list` shows all dependencies at correct versions
2. `ruff check backend/` passes with no errors
3. `uvicorn backend.app.main:app` starts without errors
4. `curl http://localhost:8000/health` returns 200 with {"status": "healthy"}
5. `curl http://localhost:8000/api/v1/health` returns 200
</verification>

<success_criteria>
- FastAPI backend structure exists following research architecture
- All dependencies installed via uv
- Health endpoint responds at /health
- Configuration loads from environment (or .env file)
- ruff passes on all code
</success_criteria>

<output>
After completion, create `.planning/phases/01-core-infrastructure-security/01-01-SUMMARY.md`
</output>