efihub/CLAUDE.md

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

# 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