Developer Guide

This guide covers everything you need to get klartext.jetzt running locally, understand the project structure, and work effectively in a GitHub Codespace.

---

Prerequisites

Tool	Version	Install	Notes
Python	3.12+	python.org	Required
Node.js	20+	nodejs.org	Required
Supabase CLI	latest	supabase.com/docs/guides/cli	Installed automatically by setup.sh if missing
GitHub CLI	latest	cli.github.com	Optional — needed for Codespace management

---

Local setup

Clone the repo and run the bootstrap script once:

git clone https://github.com/ThorstenDittmar/klartext.git
cd klartext
bash setup.sh

setup.sh will:

1. Check all prerequisites
2. Create api/.venv and install Python dependencies
3. Install the klartext CLI command (pip install -e api/)
4. Run npm install for the frontend
5. Start the local Supabase stack (supabase start)

After supabase start prints the connection details, copy the values into api/.env:

# api/.env
ANTHROPIC_API_KEY=sk-ant-...
SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=sb_secret_...
ENVIRONMENT=development

---

Environment variables

api/.env

Variable	Description	Where to find it
ANTHROPIC_API_KEY	Anthropic API key for Claude	console.anthropic.com → API Keys
SUPABASE_URL	Local Supabase API URL	Printed by supabase start
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key (bypasses RLS)	Printed by supabase start
ENVIRONMENT	development or production	Set manually

frontend/.env.local

Variable	Description
VITE_SUPABASE_URL	Same as SUPABASE_URL above
VITE_SUPABASE_ANON_KEY	Anon key printed by supabase start

---

CLI commands

After setup, the klartext command is available in your virtual environment:

source api/.venv/bin/activate

Command	Description
klartext start	Start the FastAPI server with auto-reload at http://localhost:8000
klartext test	Run unit tests (excludes integration tests)
klartext test --all	Run unit + integration tests (requires running Supabase + API keys)
klartext test -v	Run unit tests with verbose output
klartext health	Call /health and print per-dependency status
klartext testdata	Seed the database with a consistent test dataset (requires running API + Supabase)
klartext db reset	Reset local database and re-apply all migrations
klartext db status	Show status of the local Supabase instance

---

API endpoints

The interactive API docs are available at http://localhost:8000/docs when the server is running.

Method	Path	Description
GET	/health	Infrastructure health check
GET	/docs	Interactive Swagger UI
POST	/narratives/import	Import a narrative from a Markdown file
GET	/narratives	List all narratives
GET	/narratives/{id}	Get a narrative with its scenes
POST	/narratives/{id}/scenes/{scene_id}/extract-claims	Extract claims from a scene
GET	/narratives/{id}/scenes/{scene_id}/claims	List claims for a scene
POST	/claims/extract	Extract claims from raw text

Health check response

{
  "status": "ok",
  "version": "0.1.0",
  "checks": {
    "database": { "status": "ok" },
    "anthropic": { "status": "ok" }
  }
}

status is "ok" when all checks pass, "degraded" when one or more fail. HTTP status is always 200 — read the body to detect degradation.

---

Database

The migration files in supabase/migrations/ are the single source of truth for the schema — klartext db reset rebuilds the database entirely from them. Never run SQL manually in the Supabase dashboard.

To add a schema change:

# 1. Create a new migration file (Supabase generates the timestamp prefix)
supabase migration new describe_your_change

# 2. Write the SQL in the generated file

# 3. Apply and verify locally
klartext db reset

The migration history lives in git log -- supabase/migrations/. Planned schema changes belong in GitHub Issues, not here.

---

Testing

klartext test          # unit tests only (fast, no external services)
klartext test --all    # includes integration tests (needs Supabase + API keys)
klartext test -v       # verbose output

The test suite follows four layers, always written before implementation:

1. Domain — pure unit tests, no mocks
2. Services — unit tests with fake repositories
3. Repositories — @pytest.mark.integration tests against real Supabase
4. Routers — API tests via FastAPI TestClient

Integration tests are excluded from the default run (pytest.ini sets -m 'not integration').

---

GitHub Codespaces

The repository works out of the box in a GitHub Codespace.

First-time setup in a Codespace

The Codespace already has the repository cloned. Run the bootstrap script — it installs the Supabase CLI automatically if missing:

bash setup.sh

Then fill in api/.env with the values printed by supabase start:

nano api/.env
# SUPABASE_URL=http://127.0.0.1:54321
# SUPABASE_SERVICE_ROLE_KEY=sb_secret_...
# ANTHROPIC_API_KEY=sk-ant-...   ← see section below

Adding secrets to a Codespace

Set the ANTHROPIC_API_KEY as a Codespace secret so it is available automatically:

gh secret set ANTHROPIC_API_KEY --app codespaces --repo ThorstenDittmar/klartext

Then restart the Codespace for the secret to take effect. Alternatively, export it for the current session:

export ANTHROPIC_API_KEY=sk-ant-...

Running integration tests in a Codespace

cd api
SUPABASE_URL=http://127.0.0.1:54321 \
SUPABASE_SERVICE_ROLE_KEY=sb_secret_... \
python3 -m pytest tests/ -m integration -v

---

CI/CD

GitHub Actions workflows run on every push and pull request:

Workflow	Trigger	What it does
lint.yml	push / PR	ruff check, ruff format --check, mypy on API; eslint, tsc on frontend
test.yml	push / PR	Unit tests (no Supabase required)
deploy-docs.yml	push to main (docs/** changed)	Builds and deploys MkDocs to GitHub Pages

---

Architecture

klartext/
├── api/                   # Python 3.12 + FastAPI
│   ├── routers/           # HTTP routing only
│   ├── services/          # Business logic (OOP)
│   ├── repositories/      # Data access (Supabase adapters)
│   ├── models/            # Domain objects
│   ├── schemas/           # Pydantic request/response shapes
│   ├── exceptions/        # Exception hierarchy per layer
│   ├── providers/         # AI provider adapters (Claude)
│   ├── parsers/           # Input parsers (Markdown)
│   ├── cli.py             # typer CLI
│   └── main.py            # FastAPI app entry point
├── frontend/              # React 18 + TypeScript + Vite
├── supabase/
│   ├── migrations/        # SQL migration files (source of truth)
│   └── config.toml        # Supabase project config
├── docs/                  # MkDocs Material — specification + developer docs
├── setup.sh               # One-shot bootstrap script
└── .github/workflows/     # CI/CD pipelines

See CLAUDE.md for the full coding standards.