Initial commit – TimeMaster Zeiterfassung & HR-Tool

Stand: agent-06 (Audit-Log), agent-05 (Krankmeldung), agent-07 Phase 1 (Personalnummer), Busylight-Pull-Integration, TOTP/2FA, Abwesenheiten, Zeiterfassung, Kiosk-Grundgerüst. Migrations 0001–0023 deployed auf 192.168.1.137 + .164. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-23 20:03:27 +02:00
commit 1fedd683e0
178 changed files with 29896 additions and 0 deletions
@@ -0,0 +1,73 @@
+# 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)
+```