Klara

Klara ist ein ruhiges, übersichtliches Werkzeug für Lehrkräfte – entwickelt für den Schulalltag, nicht für die Schulsekretariat.

Statt langer Einführungen und komplizierter Menüs bietet Klara das Wesentliche: Schülerprofile anlegen, Beobachtungen festhalten, Leistungen dokumentieren – alles an einem Ort, ohne Ablenkung.

Ob nach einer Unterrichtsstunde schnell eine Notiz zur Mitarbeit, vor der Notenkonferenz einen Überblick über alle Schularbeiten einer Klasse, oder beim Elterngespräch auf konkrete Beobachtungen zugreifen – Klara ist in Sekunden einsatzbereit.

Ein digitaler Notizblock mit Struktur. Für Lehrkräfte, die lieber unterrichten als verwalten.

🌐 https://klara.abler.tirol

---

Inhalt

• Produktidee
• Stack
• Projektstruktur
• Lokale Entwicklung
• Umgebungsvariablen
• Verfügbare Skripte
• Architekturprinzipien
• API

---

Produktidee

Klara hilft Lehrkräften dabei, schnell und ohne Aufwand folgendes zu dokumentieren:

• Schülerprofile – Name, Bild, Geburtsdatum, Elterninformationen
• Pädagogische Notizen – Mitarbeit und Verhalten, fachbezogen und chronologisch
• Leistungsdokumentation – Schularbeiten, Überprüfungen, Ergebnisse je Schüler
• Beurteilungsgrundlagen – übersichtlich abrufbar, ohne automatische Notenlogik

---

Stack

Bereich	Technologie
Monorepo	Nx
Frontend	Angular 20 mit SSR
Backend	NestJS 11
Datenbank	PostgreSQL 17
ORM	TypeORM
Containerisierung	Docker / Docker Compose
Reverse Proxy	Traefik mit automatischem TLS (Let's Encrypt)

---

Projektstruktur

/
├── apps/
│   ├── klara/          # Angular Frontend (SSR)
│   └── server/         # NestJS Backend
├── libs/
│   └── domain/         # Shared Library: DTOs, Interfaces, Enums
│                       # Import via @app/domain
├── dockerfiles/
│   ├── Dockerfile.backend
│   ├── Dockerfile.frontend
│   └── nginx.conf
├── conf/
│   └── postgres/
│       └── .env.template
├── docker-compose.yml      # Produktion (mit Traefik)
├── docker-compose.dev.yml  # Lokale Entwicklung
└── .env.example

Shared Library @app/domain

Die Library libs/domain ist die einzige Quelle der Wahrheit für alle geteilten Typen zwischen Frontend und Backend.

import { NoteType, AssessmentEventType } from '@app/domain';

Sie enthält DTOs, TypeScript-Interfaces und Enums. Beide Apps importieren ausschließlich aus @app/domain – keine doppelten Typdefinitionen.

---

Lokale Entwicklung

Voraussetzungen

• Docker und Docker Compose
• Node.js 20+ und npm (für Entwicklung ohne Docker)

Mit Docker starten

# 1. Umgebungsvariablen vorbereiten
cp .env.example .env
cp conf/postgres/.env.template conf/postgres/.env
# Werte in beiden Dateien anpassen

# 2. Alle Services starten
docker compose -f docker-compose.dev.yml up --build

# Frontend:  http://localhost
# Backend:   http://localhost/api
# Swagger:   http://localhost/api/docs
# DB:        localhost:5432

Ohne Docker (Entwicklungsmodus)

npm install

# Backend starten
npx nx serve server

# Frontend starten (separates Terminal)
npx nx serve klara

Der Angular Dev-Server proxied /api automatisch auf http://localhost:3000 (siehe apps/klara/proxy.conf.json).

---

Umgebungsvariablen

Kopiere .env.example nach .env und passe die Werte an:

# Datenbank
TYPEORM_HOST=db
TYPEORM_PORT=5432
TYPEORM_DATABASE=klara
TYPEORM_USERNAME=user
TYPEORM_PASSWORD=dein-passwort
TYPEORM_SYNC=true

# App
NODE_ENV=production
PORT=3000

# Uploads (Avatare)
# Vollständiger Pfad zum Upload-Verzeichnis inkl. Unterordner
UPLOAD_DIR=/data/uploads/avatars

# Auth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_CALLBACK_URL=https://klara.abler.tirol/api/auth/google/callback
JWT_SECRET=change-me-in-production
JWT_EXPIRES_IN=8h

Für die Datenbank zusätzlich conf/postgres/.env aus dem Template befüllen.

---

Verfügbare Skripte

# Bauen
npx nx build server      # NestJS Backend bauen
npx nx build klara       # Angular Frontend bauen

# Tests
npx nx test server       # Backend Unit Tests
npx nx test domain       # Shared Library Tests
npx nx test klara        # Frontend Unit Tests

# Linting
npx nx lint server
npx nx lint klara
npx nx lint domain

---

Architekturprinzipien

Shared DTOs als Vertragsgarantie Alle API-Typen leben in libs/domain. Eine Änderung dort bricht sofort Tests in Frontend und Backend – kein stiller Drift zwischen den Schichten.

MVP-first Jede Funktion muss einer Lehrkraft im Alltag direkt helfen. Was das nicht tut, kommt nicht in den MVP.

Einfachheit vor Vollständigkeit Klara ist kein Schulverwaltungssystem. Es ist ein fokussiertes Werkzeug, das Lehrkräfte ohne Einführung sofort verstehen und verwenden können.

---

API

Das Backend ist unter /api erreichbar.

Umgebung	URL
Produktion	https://klara.abler.tirol/api
Lokal (Docker)	http://localhost/api
Lokal (ohne Docker)	http://localhost:3000/api

Swagger-Dokumentation:

https://klara.abler.tirol/api/docs   # Produktion
http://localhost/api/docs            # lokal via Docker
http://localhost:3000/api/docs       # lokal ohne Docker

Health-Check: GET /api/healthz → { "status": "ok" }

Endpunkte (Übersicht)

Ressource	Pfad
Schüler	/api/students
Avatar-Upload	/api/students/:id/avatar
CSV-Import	/api/students/import
Klassen	/api/classes
Fächer	/api/subjects
Notizen	/api/notes
Leistungsereignisse	/api/assessments
Schülerergebnisse	/api/assessments/:id/results
Konto löschen	DELETE /api/auth/account

---

Datenschutz (DSGVO)

Klara speichert personenbezogene Daten von Schülerinnen und Schülern (Name, Geburtsdatum, Elterndaten, Noten, Beobachtungen). Der Betreiber einer Klara-Instanz ist für die datenschutzkonforme Nutzung verantwortlich.

Pflichten des Betreibers

• Erstellung einer Datenschutzerklärung gemäß Art. 13/14 DSGVO
• Sicherstellung einer Rechtsgrundlage für die Verarbeitung (z. B. schulrechtliche Grundlage, Einwilligung)
• Abschluss eines Auftragsverarbeitungsvertrags (AVV) mit dem Hosting-Anbieter
• Führen eines Verzeichnisses von Verarbeitungstätigkeiten (Art. 30 DSGVO)
• Sicherstellung der Betroffenenrechte (siehe unten)

Betroffenenrechte (Art. 15, 17, 20 DSGVO)

Recht	Umsetzung in Klara
Auskunft (Art. 15)	Schülerdaten sind in der App einsehbar; vollständiger Export manuell möglich
Löschung (Art. 17)	Schüler können einzeln gelöscht werden (inkl. aller verknüpften Daten via CASCADE). Lehrkräfte können ihr Konto unter Einstellungen löschen.
Portabilität (Art. 20)	Noch nicht als automatisierter Export umgesetzt – geplant für eine spätere Version

Technische Maßnahmen

• Alle Schüler-Verknüpfungen (Notizen, Elterndaten, Leistungsergebnisse) sind mit onDelete: 'CASCADE' konfiguriert – ein gelöschter Schüler hinterlässt keine verwaisten Datensätze
• Beim Löschen einer Lehrkraft werden via CASCADE alle Schüler, Notizen und Leistungsdaten dieser Lehrkraft mitgelöscht
• Authentifizierung via httpOnly-Cookie (kein Token in URL oder localStorage)
• TYPEORM_SYNC ist in Produktion deaktiviert (kein unbeabsichtigter Datenverlust)

---

Lizenz

MIT – siehe LICENSE.md