# Entwickler-Dokumentation
Technische Dokumentation für Entwickler, die an SeminarPlan arbeiten oder es erweitern möchten.
# Architektur-Übersicht
SeminarPlan besteht aus mehreren Komponenten, die zusammenarbeiten:
| Komponente | Technologie | Beschreibung |
|---|---|---|
| Frontend (Web) | Vue 3, TypeScript, Vite | SPA mit V1 (klassisch) und V2 (Desktop-Shell) |
| Frontend (Desktop) | Electron | Web-App verpackt als Desktop-Anwendung |
| API | Fastify 5, Node.js | REST-API mit V1- und V2-Endpunkten |
| Datenbank | MongoDB | Dokumentenbasierte Datenbank mit Mongoose ODM |
| WebSocket | @fastify/websocket | Echtzeit-Updates und Locking |
| Dokumentation | VuePress | Diese Dokumentation |
# Tech-Stack
# Backend (API)
| Paket | Zweck |
|---|---|
| Fastify 5 (opens new window) | Web-Framework (Routing, Plugins, Hooks) |
| MongoDB (opens new window) + Mongoose (opens new window) | Datenbank + ODM |
| @fastify/swagger (opens new window) | OpenAPI/Swagger-Dokumentation (automatisch generiert) |
| @fastify/websocket (opens new window) | WebSocket-Verbindungen |
| JSON Web Tokens (opens new window) | Authentifizierung |
| Mocha (opens new window) | E2E- und Unit-Tests |
# Frontend (Web-App)
| Paket | Zweck |
|---|---|
| Vue 3 (opens new window) + TypeScript | UI-Framework |
| Vite (opens new window) | Build-Tool und Dev-Server |
| Pinia (opens new window) | State Management (43 Entity-Stores) |
| TailwindCSS (opens new window) + DaisyUI (opens new window) | CSS-Framework |
| @tanstack/vue-query (opens new window) | Server-State (V2-Datenschicht) |
| FullCalendar (opens new window) | Kalender-Integration |
| ApexCharts (opens new window) | Diagramme und Charts |
| CKEditor 5 (opens new window) | Rich-Text-Editor |
| Vitest (opens new window) | Unit-Tests |
| Playwright (opens new window) | E2E-Tests |
# Desktop-App
Die Desktop-Anwendung ist die Web-App, verpackt mit Electron (opens new window) und Electron Forge (opens new window). Sie bietet zusätzliche Features wie Vollbild-Modus, Dateizugriff und Hintergrundprozesse.
# Setup
# Voraussetzungen
- Linux oder macOS Host
- Docker (opens new window) + Docker Compose (opens new window)
- Git (opens new window)
- Node.js (opens new window) (v20+)
- Bun (opens new window) (für das Frontend)
# Entwicklungsumgebung starten
# API starten
cd seminarplan-api
npm install
npm run dev
# Frontend starten
cd seminarplan-app-vue
bun install
bun run dev
# Befehle
# Frontend
| Befehl | Beschreibung |
|---|---|
bun run dev | Dev-Server starten |
bun run build | Production-Build |
bun run tsc | TypeScript-Check (kein Emit) |
bun run unit | Unit-Tests einmalig |
bun run unit:watch | Unit-Tests im Watch-Modus |
bun run e2e | E2E-Tests (headless) |
bun run e2e:headed | E2E-Tests (sichtbarer Browser) |
bun run e2e:ui | Playwright UI-Modus |
# API
| Befehl | Beschreibung |
|---|---|
npm run dev | Dev-Server mit Hot-Reload |
npm run routes | Alle registrierten Routen anzeigen |
npm run test:e2e | E2E-Tests |
npm run test:unit | Unit-Tests |
# Continuous Integration
Deployments laufen über CircleCI (opens new window):
- Staging: Automatisch nach erfolgreichem Test auf dem Hauptbranch
- Production: Automatisch bei neuen Git-Tags (neue Version)
- Dokumentation: Bei jedem Commit
Infrastruktur: Kubernetes + Helm-Charts + Docker-Images.
# Frontend-Architektur
# V1 vs. V2
SeminarPlan hat zwei UI-Schichten, die parallel existieren:
| V1 (Klassisch) | V2 (Desktop) | |
|---|---|---|
| Navigation | Seitenmenü mit Routen | Desktop-Shell mit Fenstern |
| Datenhaltung | Pinia-Stores (komplett geladen) | TanStack Query + V2 Data Clients |
| Route | /kontakte, /buchungen, ... | /v2 (alles in einer Route) |
| Programme | Views als Vue-Komponenten | Fenster mit Programm-Registry |
Beide Schichten teilen sich Stores, WebSocket-Events und Authentifizierung. V2 kann V1-Views als "Legacy Surfaces" in Desktop-Fenstern anzeigen.
# Wichtige Verzeichnisse
src/
├── api/ # V1 API-Services (54 Services)
├── components/ # Gemeinsame UI-Komponenten
├── composables/ # Business-Logik (Hooks)
├── config.ts # Umgebungskonfiguration
├── modules/ # Utilities (Constants, Status, Icons, ...)
├── stores/ # Pinia-Stores (43 Entity-Stores)
├── views/ # V1-Views (Seiten)
└── v2/ # V2 Desktop-Shell
├── app/ # V2Root.vue (Bootstrap)
├── shell/ # Desktop-Framework (Shell, Taskbar, Startmenü)
├── programs/ # Ein Ordner pro V2-Programm
├── composables/ # 87+ Shell-Composables
├── data/ # V2 API-Clients (41 Dateien)
└── types/ # V2-spezifische TypeScript-Typen
# Neuen Store anlegen
Wenn du einen neuen Store hinzufügst, musst du ihn an folgenden Stellen registrieren:
- Types in
src/api/types/types.ts - API Service in
src/api/<Entity>Service.ts - Store in
src/stores/<Entity>Store.tsmitcrud-Config - Autoload in
src/composables/autoload.ts(falls global benötigt) - WebSocket-Mapping in
src/composables/storeHelper.ts - Activity-Tracking in
src/modules/Activity.ts
# Weitere Themen
- API-Dokumentation -- REST-Endpunkte, Authentifizierung, Response-Formate
- Extensions -- API mit eigenen Plugins erweitern
- Icons -- Icon-System in SeminarPlan
# Nützliche Werkzeuge
| Tool | Zweck |
|---|---|
| MongoDB Compass (opens new window) | Datenbank visuell durchsuchen |
| Postman (opens new window) | API-Endpunkte testen |
| Swagger UI | Eingebaut unter /v1/api-docs und /v2/api-docs |
| Debug-Routen | /debug, /debug/components, /debug/websocket, /debug/store |
| V2 Debug Lab | Programm im V2 Desktop mit Store-Inspector |