# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project

**University Process Hub (UPH)** — modulares FastAPI-Backend für Fakultätsprozesse (TH Nürnberg). Einstieg ist ein RSS-Server, erweiterbar durch Module in `app/modules/`. Dient als Basis für studentische Arbeiten.

## Commands

```bash
# Abhängigkeiten installieren
pip install -r requirements.txt

# Entwicklungsserver starten
uvicorn app.main:app --reload

# Mit APP_PREFIX (Traefik-Simulation)
APP_PREFIX=/uph uvicorn app.main:app --reload

# Tests ausführen
pytest

# Einzelnen Test ausführen
pytest tests/test_foo.py::test_bar -v

# Formatting & Linting
black app/
flake8 app/
```

## Architektur

### Konfiguration (`app/core/config.py`)

Zentrale `Settings`-Klasse via `pydantic-settings`. Werte kommen aus `.env` oder Umgebungsvariablen:

- `APP_PREFIX` — Traefik-Pfadpräfix (z. B. `/uph`). Wird als `root_path` an FastAPI übergeben, damit alle Routen inkl. WebSockets und Swagger UI automatisch korrekt geroutet werden.
- `DATABASE_URL` — `sqlite:///./app.db` lokal, `mysql+pymysql://...` in Produktion. Kein separates Flag nötig — SQLAlchemy erkennt den Dialekt aus der URL.
- Singleton via `@lru_cache` → `get_settings()` als FastAPI-Dependency injizierbar.

### App-Entrypoint (`app/main.py`)

`FastAPI(root_path=settings.APP_PREFIX)` — das ist der einzige Ort, an dem `APP_PREFIX` angewendet wird. Kein Prefix-Middleware-Hack nötig.

### Modulstruktur

Jedes Feature liegt in `app/modules/<name>/` mit:
- `router.py` — `APIRouter`, wird in `main.py` per `app.include_router()` eingebunden
- `service.py` — Businesslogik (keine direkten FastAPI-Abhängigkeiten)
- `models.py` — SQLAlchemy-Models

Module müssen ohne tiefgreifende Core-Abhängigkeiten exportierbar sein (für studentische Arbeiten).

### Datenbank (`app/core/database.py`, noch zu erstellen)

Zentrales `database.py` mit SQLAlchemy 2.0 Engine und Session-Factory. Sessions werden als FastAPI-Dependency (`Depends(get_db)`) injiziert.

### Authentifizierung (`app/core/auth.py`, noch zu erstellen)

OAuth2/JWT als FastAPI-Dependencies. Referenzimplementierung liegt in `/Users/oliver/Development/Operations/django-app/authstuff` (Django-Logik, muss auf FastAPI portiert werden).

## Deployment

- Traefik-basiertes pfadbasiertes Routing via `APP_PREFIX`
- Docker & Docker Compose (Configs in `docker/`)
- Celery + Redis als Task-Queue (`app/worker/`)
- Admin-UI via `sqladmin`