# TimeMaster – Architektur

## Stack

| Schicht | Technologie |
|---------|------------|
| Backend | Python 3.12 · FastAPI · SQLAlchemy (async) |
| Datenbank | PostgreSQL 16 |
| Cache / Sessions | Redis 7 |
| Frontend | React 18 · TypeScript · Tailwind CSS |
| Prozess-Manager | systemd |
| Reverse Proxy | Nginx + Let's Encrypt |
| E-Mail | Resend.com |
| Datei-Storage | Lokales Filesystem / S3-kompatibel |

## Verzeichnisstruktur

```
/opt/timemaster/
├── backend/
│   ├── app/
│   │   ├── core/          # Config, DB, Security, Dependencies
│   │   ├── models/        # SQLAlchemy ORM Models
│   │   ├── schemas/       # Pydantic v2 Schemas
│   │   ├── routers/       # FastAPI Router (je Modul)
│   │   └── services/      # Business-Logik (je Modul)
│   ├── migrations/        # Alembic
│   └── tests/             # pytest
└── frontend/
    ├── src/
    │   ├── features/      # Auth, Zeit, Urlaub, Dashboard, Kiosk
    │   └── shared/        # Komponenten, Hooks, Utils
    └── dist/              # Build-Output (von Nginx ausgeliefert)
```

## Rollen & Berechtigungen

```
SUPER_ADMIN     → Plattform-Betreiber, alle Firmen
COMPANY_ADMIN   → Vollzugriff eigene Firma
HR              → Personalakten lesen, Berichte
MANAGER         → Genehmigungen für eigenes Team
EMPLOYEE        → Eigene Daten, eigene Anträge
```

## Authentifizierung

- **Access Token**: JWT, 30 Minuten gültig
- **Refresh Token**: Opaque, 30 Tage, rotation bei jedem Refresh
- **Kiosk**: Eigener Token-Flow, PIN/NFC/QR/Liste

## Datenbankschema (Übersicht)

```
companies ──< departments
companies ──< users ──< sessions
users ──< time_entries
users ──< absences ──> absence_types
users ──< vacation_balances
companies ──< kiosk_devices
companies ──< audit_logs
```

## API-Versionierung

Alle Endpunkte unter `/api/v1/`. Zukünftige Breaking Changes → `/api/v2/`.

## Deployment (nativ)

```
systemd → uvicorn (4 worker) → FastAPI
nginx → :443 → :8000 (API) + /opt/timemaster/frontend/dist (React)
```