Architektur

Systemarchitektur

DaZ Pilot ist ein Monorepo mit vier Komponenten: Mobile App, Web-Dashboard, Node.js-Backend und Python-ML-Sidecar. Der komplette Stack läuft containerisiert.

Überblick

Die Architektur trennt klar zwischen Client-Anwendungen, Orchestrierung und rechenintensiver ML-Arbeit. Externe Kommunikation läuft ausschließlich über TLS 1.3, der ML-Service ist nur intern erreichbar. Zugriffsrechte sind rollenbasiert (Schüler:in, Lehrkraft, Admin, Super-Admin).

Mobile App

React Native / Expo

Web-Dashboard

Next.js + KERN UX

core-backend

Node.js · Express 5 · TypeScript

PostgreSQL

Kysely · Classifier-Blobs

ml-service

FastAPI · SigLIP 2 · sklearn

Qdrant

Vektor-Datenbank

Containerisiert via Docker Compose. Externe Kommunikation ausschließlich über TLS 1.3. ML-Service ist nur intern erreichbar.

Komponenten

Komponente	Beschreibung	Details
`app/`	Mobile App für Schüler:innen	React Native mit Expo, File-based Routing
`backend/`	REST-API mit npm Workspaces	Express 5, TypeScript, PostgreSQL, Kysely
`ml-service/`	Python-Sidecar für SigLIP-2-Bilderkennung	FastAPI, PyTorch, scikit-learn, Qdrant-Client
`dashboard/`	Web-Dashboard für Lehrkräfte	Next.js + KERN UX
`infra/`	CI/CD-Konfiguration	GitLab-CI

Projektstruktur

Das Repository ist als Monorepo organisiert. Der Root koordiniert alle Sub-Pakete über npm workspaces und Docker-Compose.

text

daz-pilot/
├── app/                    Mobile App (React Native / Expo)
├── backend/                Backend-Monorepo (Node.js / Express)
│   ├── Dockerfile          Multi-Stage-Build für API, Worker & Migrator
│   └── workspaces/
│       ├── core-backend/           Express-API-Server
│       ├── backend-api-types/      Zod-Schemas und API-Typen
│       ├── backend-utils/          Geteilte Middleware und Utilities
│       ├── database/               Kysely-Datenbankschicht
│       ├── database-migrator/      Datenbank-Migrationen
│       └── tests/                  Test-Suite
├── ml-service/             Python-Sidecar (SigLIP 2 + FastAPI)
│   └── Dockerfile          Python-Image (FastAPI / uvicorn)
├── dashboard/              Web-Dashboard (Next.js + KERN UX)
├── docs/                   Dokumentation (inkl. ARCHITECTURE.md)
├── infra/                  CI/CD-Konfiguration
│   └── gitlab-ci.yml       GitLab-CI-Pipeline
├── scripts/                Standalone-Skripte
├── docker-compose.yml      Lokaler Stack
├── .env.example            Vorlage für .env
├── package.json            Root-Package
└── LICENSE                 EUPL-1.2

Backend-Workspaces

Das Backend selbst ist als npm-Workspaces-Monorepo aufgebaut. Jedes Workspace-Paket hat eine klar definierte Verantwortung.

Workspace	Paketname	Verantwortung
`core-backend`	`@daz-pilot/core-backend`	Express-Server, Router, Controller, Auth-Middleware, OCR
`backend-api-types`	`@daz-pilot/daz-pilot-backend-api-types`	Zod-Schemas und OpenAPI-Typen
`backend-utils`	`@daz-pilot/backend-utils`	Middleware, Logger (Pino), Fehlerbehandlung, Health-Checks
`database`	`@daz-pilot/database`	PostgreSQL-Pool und Kysely-Typen
`database-migrator`	`@daz-pilot/database-migrator`	Datenbank-Migrationen (Kysely)
`tests`	`@daz-pilot/tests`	Test-Suite (Node.js Built-in Test Runner)

Tech-Stack

Komponente	Technologie	Version
Mobile App	React Native + Expo	Expo ~54, RN 0.81
Web-Dashboard	Next.js + KERN UX	–
Backend	Node.js / Express	Node 22, Express 5.2
ML-Sidecar	Python / FastAPI / PyTorch	Python 3.11+
Sprache	TypeScript	5.9
Datenbank	PostgreSQL + Kysely	Kysely 0.28
Vektordatenbank	Qdrant	1.14
Validierung	Zod	4.3
Bilderkennung	SigLIP 2 SO400M (HuggingFace) + LinearSVC	–
Video-Verarbeitung	ffmpeg + sharp (Laplacian-Schärfefilter)	ffmpeg ≥ 6
OCR	Tesseract	–
Text-to-Speech	Device Native TTS	–
API-Dokumentation	Swagger UI + OpenAPI	–
Containerisierung	Docker	–
CI/CD	GitLab CI	–
Lernplattform	Moodle (Integration)	ab 4.x

Datenmodell (Auszug)

PostgreSQL ist Source of Truth für Nutzer:innen, Fachbegriffe, Klassen, Quizze und Classifier-Blobs. Alle Tabellen teilen die Basisspalten _id, _created_at und _updated_at.

Bereich	Tabellen	Beschreibung
Schulen	`schools`, `school_invitations`	Schul-Entitäten und rollenbasierte Einladungen
Benutzer	`super_admins`, `teachers`, `students` + Sessions	Drei Nutzerrollen mit SHA-256-gehashten Session-Tokens
Fachbegriffe	`technical_terms`	Bild, deutsche Form (Genus/Singular/Plural), Qdrant-Vektor-Referenz
Objekterkennung	`school_classifiers`, `training_jobs`	joblib-Blobs (BYTEA) pro Schule + Postgres-basierte Job-Queue
Klassen	`classes`, `class_teacher_joins`	Klassen mit Fortschritts-Tracking
Arbeitsaufträge	`assignments`, `assignment_technical_term_joins`	PDF-Uploads pro Klasse mit erkannten Fachbegriffen
Quizze	`quizzes`, `quiz_technical_term_joins`	Quiz-Definition und individueller Fortschritt