Executive Summary
Bundeszulassung24 ist eine produktionsreife Plattform für die vollständig digitale Abwicklung von Kfz-Zulassungsvorgängen in Deutschland. In knapp 5 Monaten wurde ein End-to-End-System aufgebaut, das Endkund:innen durch einen geführten Antragsprozess führt, Zahlungen per Stripe abwickelt, Dokumente KI-gestützt analysiert, interne Teams über rollenbasierte Panels steuert und den gesamten Lebenszyklus eines Antrags revisionssicher protokolliert.
Die Plattform läuft produktiv auf einer containerisierten Infrastruktur mit automatischer SSL-Verwaltung, serviert ein PWA-fähiges Frontend mit über 30 SEO-optimierten Seiten und integriert einen KI-Chatbot für Kundenberatung. Konzeption, Architektur, Implementierung und operative Stabilisierung wurden vollständig von TYS Dijital Performans verantwortet; die architektonische und technische Gesamtleitung lag bei Yılmaz Saraç.
Plattformarchitektur: Monorepo-Struktur
Die Entscheidung für ein Monorepo (Turborepo v2 + pnpm v9) war architektonisch zentral: Typ-Konsistenz vom Datenbankschema bis zur Frontend-Eingabe, gemeinsame Validierungsregeln und ein einziger Paketbaum reduzieren Integrationsfehler und verkürzen die Feedback-Schleife bei Änderungen.
| Schicht | Technologie | Begründung |
|---|---|---|
| API | Fastify 4 + TypeScript 5 (strict) | ~2× schneller als Express, natives JSON-Schema, Plugin-Architektur |
| Kunden-Frontend | Next.js 14 App Router | SSR + CSR hybrid für SEO-kritische Landing Pages und interaktive Formulare |
| Admin/Operator | Refine.dev 4 + Ant Design 5 | CRUD-optimiert, eingebaute RBAC-Patterns, schnelle Panelentwicklung |
| Datenbank | PostgreSQL 16 | ACID, JSONB für flexible Formulardaten, bewährtes Ökosystem |
| Cache / Sessions | Redis 7 | Rate-Limiting, Session-Verwaltung, Fastify-Plugin-Integration |
| Objektspeicher | MinIO (self-hosted, S3-kompatibel) | Dokumente bleiben in Deutschland (DSGVO), kein Cloud-Lock-in |
| Zahlung | Stripe | PCI-DSS-konform, Multi-Methode (Card, Apple Pay, Google Pay, Klarna) |
| Dokumentenanalyse | OpenAI GPT-4o Vision | OCR + KI-Extraktion aus Zulassungsbescheinigungen, Ausweisen, eVB |
| Gmail API (OAuth2) | Transaktionale E-Mails ohne Drittanbieter, volle Kontrolle | |
| Reverse Proxy | Traefik v2.11 | Automatische Let's-Encrypt-Zertifikate, Docker-native |
| KI-Chat | OpenAI GPT-4o | Domänenspezifische Kundenberatung mit strukturiertem System-Prompt |
Datenmodell: 22 Tabellen, 13 Enumerationen
Das Datenbankschema wurde in Prisma 5 definiert und bildet die fachliche Domäne vollständig ab: Nutzerkonten, Anträge, Fahrzeuge, Dokumente, Zahlungen, Versionshistorie, Kommentare, Zuweisungen sowie SEO/AI-Management-Tabellen.
Kernmodelle
| Modell | Felder | Zweck |
|---|---|---|
| User | 25 | Kund:innen + Personal, 5-stufiges Rollenmodell, Firmenkundenfelder, Sicherheitsfelder |
| Submission | 20 | Zentrale Prozessinstanz, Referenznummer B24-XXXXXX, 11-stufiger Status, JSON-Formulardaten, Preis-Dreiklang |
| SubmissionVersion | 10 | Audit-Trail: Jede Änderung erzeugt eine neue Version mit Snapshot und Änderungsquelle |
| Vehicle | 23 | Vollständige Fahrzeugdaten: FIN, Kennzeichen, Plakettentyp, Sicherheitscodes, eVB |
| Document | 14 | Hochgeladene Belege mit MinIO-Pfad, OCR-Flag, Konfidenzwert und extrahierten Daten |
| Payment | 14 | Stripe-Integration: PaymentIntent-ID, 6 Zahlungsmethoden, Teilrückerstattung |
SEO/AI-Management (5 dedizierte Modelle)
SeoSettings (14 Felder), SchemaMarkup (21 Felder), AiVisibility (15 Felder), BrandLock (20 Felder), FaqItem (8 Felder), alle über das Admin-Panel verwaltbar. Zusätzlich SeoGeoPage für bundeslandbasierte Geo-SEO-Seiten.
API-Architektur: 14 Route-Module, 50+ Endpunkte
Die API wurde als modulares Fastify-Plugin-System aufgebaut. Jeder Request durchläuft eine feste Pipeline: Helmet CORS Rate-Limiting (Redis, 100 req/min) JWT-Verifikation Zod-Validierung Business-Logik Response.
| Prefix | Zeilen | Kernfunktionen |
|---|---|---|
| /api/auth | 615 | Register (bcrypt 12), Login (5-Versuch-Sperre), Refresh-Token-Rotation, E-Mail-Verifizierung |
| /api/submissions | 673 | CRUD, Referenznummern-Generator (B24-XXXXXX), XSS-Sanitization, Versionshistorie |
| /api/payments | 385 | Stripe PaymentIntent mit Kupon-Logik, Webhook mit rawBody-Signaturprüfung, atomare Transaktion |
| /api/documents | 627 | Upload zu MinIO (30 MB), presigned URLs, KI-Analyse (GPT-4o Vision), Konfidenz-Scoring |
| /api/admin | 981 | Dashboard (14 parallele DB-Queries), Nutzerverwaltung, Preisanpassung |
| /api/admin/seo | 357 | CRUD für SeoSettings, SchemaMarkup, AiVisibility, BrandLock, FaqItems, GeoPages |
| /api/operator | 573 | Priorisierte Warteschlange, Dokumentenanforderung per E-Mail |
| /api/chat | 217 | KI-Chatbot (GPT-4o, domänenspezifischer System-Prompt) |
Sicherheitsarchitektur: 12 Layer
| Schicht | Implementierung |
|---|---|
| Transport | HTTPS erzwungen (Traefik HTTPHTTPS-Redirect), HSTS |
| Authentifizierung | JWT (8h Access, httpOnly-Cookie) + Refresh-Token (7 Tage, Rotation) |
| Autorisierung | 5-stufiges RBAC: super_admin> admin> senior_operator> operator> customer |
| Brute-Force-Schutz | failedLoginCount + lockedUntil (15 min nach 5 Fehlversuchen) |
| Eingabevalidierung | Zod-Schemata auf body, params, querystring |
| XSS-Prävention | isomorphic-dompurify: sanitizeText(), sanitizeEmail(), sanitizeObject() |
| CORS | Whitelist: nur bundeszulassung24.de Subdomains |
| Rate-Limiting | Redis-backed, 100 Requests pro Minute pro IP |
| Sicherheitsheader | @fastify/helmet (X-Frame-Options, X-Content-Type-Options, Referrer-Policy) |
| Datei-Sicherheit | 30 MB Upload-Limit (Fastify), 35 MB Body-Limit (Traefik) |
| Cookie-Policy | httpOnly, secure, sameSite: lax, domain:.bundeszulassung24.de |
| Fehlerbehandlung | Globaler Error-Handler: 500er werden per E-Mail an Tech-Team gemeldet |
Stripe-Integration: Resilient Payment Flow
Der Payment-Flow verbindet Stripe mit dem internen Antragssystem in einer atomaren Transaktion: Kunde wählt Service Frontend erstellt PaymentIntent Stripe Elements verarbeitet die Zahlung Webhook empfängt Bestätigung In einer einzigen DB-Transaktion werden Payment, Submission, SubmissionVersion und Kupon-Counter atomar aktualisiert E-Mail-Benachrichtigungen an Kund:in und Admin-Team.
Besonderheit: Der rawBody-Workaround für die Stripe-Signaturverifikation wurde als Custom ContentTypeParser implementiert, damit der JSON-Body für die Anwendung verfügbar bleibt, während der rohe Buffer für die Signaturprüfung erhalten bleibt.
KI-gestützte Dokumentenanalyse (GPT-4o Vision)
Der Analyse-Endpunkt verarbeitet hochgeladene Dokumente mittels GPT-4o Vision:
- Upload: Bis zu 5 Dateien gleichzeitig (JPEG, PNG, PDF, max. 30 MB)
- OCR + Extraktion: Domänenspezifischer Prompt identifiziert den Dokumenttyp und extrahiert alle relevanten Felder
- Feld-Mapping: 5 dokumenttypspezifische Mapping-Tabellen (ZB I: 14 Felder, ZB II: 3 Felder, Personalausweis: 9 Felder, eVB: 3 Felder, SEPA: 4 Felder)
- Konfidenz-Scoring: Jedes extrahierte Feld erhält einen Konfidenzwert (0.0-1.0); bei Duplikaten wird der höhere Wert bevorzugt
KI-Chatbot: Domänenspezifische Beratung
Ein GPT-4o-basierter Assistent (217 Zeilen Backend, 333 Zeilen Frontend-Widget) berät Kund:innen in natürlicher Sprache. Der System-Prompt enthält alle 4 Servicetypen mit Preisen, Dokumentenanforderungen und Entscheidungslogik. Guardrails verhindern erfundene Informationen und Rechtsberatung.
Service-Router: Intelligenter Entscheidungsbaum
Statt Kund:innen zu zwingen, selbst den richtigen Zulassungstyp zu kennen, implementiert der Service-Router (551 Zeilen) einen regelbasierten Entscheidungsbaum: Abmeldung (29 EUR), Neuzulassung (149 EUR), Wiederzulassung (129 EUR), Umschreibung (139 EUR). Jedes Ergebnis zeigt Preis, benötigte Dokumente, geschätzte Dauer und Warnhinweise.
Kunden-Frontend: Next.js 14 PWA mit 30+ Seiten
Das Web-Frontend umfasst über 30 Seiten: SSR-optimierte Inhaltsseiten (Preise, So funktioniert's, FAQ, Standorte, Wissen, Sicherheit) und interaktive Client-Komponenten (Formularstrecke pro Servicetyp, Dashboard, Auth). Cookie-Consent-Banner mit 4-Kategorien-Granularität (Notwendig, Funktional, Analyse, Marketing) und Barrierefreiheits-Toolbar (Schriftgrößenanpassung, Hochkontrastmodus, Reduzierte Bewegung).
Admin-Panel: Vollständige Management-Funktionalität
Refine.dev 4 + Ant Design 5 mit Echtzeit-Dashboard (14 parallele Datenbankabfragen), Antrags- und Nutzerverwaltung, Stripe-Zahlungsübersicht, Wissensbank-Editor (Markdown), SEO-Management (6 Untermodule: SeoSettings, SchemaMarkup, AiVisibility, BrandLock, FaqItems, GeoPages) und Preisanpassung.
Operator-Panel: Fokussierte Fallbearbeitung
Eigenständiges Vite-Projekt mit priorisierter Warteschlange (älteste zuerst), Dokumenten-Download, Statuswechsel mit Versionsprotokollierung und Dokumentenanforderung per E-Mail. Separater Token-Namespace ermöglicht gleichzeitiges Einloggen in Admin und Operator auf demselben Browser.
E-Mail-System: Gmail API mit 12+ Templates
Gmail API (OAuth2) mit eigenständigem Service-Layer (482 Zeilen): 12+ transaktionale E-Mail-Templates (Registrierung, Zahlung, Statuswechsel, Dokumentenanforderung) und interne Benachrichtigungen bei neuen Anträgen, Zahlungen und Server-Fehlern. Abandoned-Draft-Reminder sendet automatisch Erinnerungen an inkomplette Anträge nach 2 Stunden Inaktivität.
Infrastruktur: 8 Container, Automatische SSL
Produktions-Setup mit 8 Docker-Containern: Web (Next.js), API (Fastify), Admin (Vite+nginx), Operator (Vite+nginx), PostgreSQL 16, Redis 7, MinIO (S3-kompatibel) und Traefik v2.11 als Reverse Proxy mit automatischen Let's-Encrypt-Zertifikaten. Multi-Stage Docker Builds mit Non-Root-Usern. Deployment per rsync mit immutable.env-Dateien auf dem Server.
SEO & AI-Sichtbarkeit: 8+ Schema-Typen
Dynamische JSON-LD-Daten (Organization, WebSite, LocalBusiness, Service, OfferCatalog, FAQPage, BreadcrumbList, HowTo), bundeslandbasierte Geo-SEO-Seiten, llms.txt-Endpoint, granulare AI-Permissions und E-E-A-T-Signale, alles aus der Datenbank verwaltbar.