Fallstudie · Meine Arbeit bei tyntec, in einer neuen Domäne
Meridian
Eine Versandplattform für deutsche Onlineshops: echte Kurierpreise, auf Deutsches Recht geprüfte Kurierverträge sowie Änderungen der Routenregeln mit Testlauf und Vier-Augen-Prinzip.
2026SoloprojektFull-Stack Software EngineeringAI Engineering – vom Workflow bis zum Produkt
Über das Projekt
Meridian steht zwischen einem Onlineshop und seinen Paketdiensten. Es vergleicht DHL, Hermes, DPD und GLS für jedes Paket, prüft Verträge mit Paketdiensten am deutschen Recht und ändert Routing-Regeln erst nach einem Testlauf und einer zweiten Freigabe.
Java 21 und Spring Boot halten Preisberechnung, Vertragsprüfungen und Routing-Regeln explizit und testbar; React und TypeScript geben dem Team eine klare Ansicht auf Vergleiche und vorgeschlagene Änderungen. Kafka transportiert Sendungsereignisse, während privater S3-Speicher die Verträge jedes Unternehmens getrennt hält.
Ein lokales Sprachmodell Qwen2.5 7B läuft über Ollama und liest die Vertragsklauseln, die die Regeln nicht lesen. Jede Antwort wird mit der Klausel abgeglichen, bevor ein Mensch sie sieht. Grafana zeigt, was passiert.
Was es besonders macht
KI-Workflow-Automatisierung, gemessen
Ich habe ein lokales Sprachmodell für die Klauseln eingeführt, die die Regel-Engine nicht lesen konnte, beide Leser behalten und an denselben gelabelten Verträgen gemessen: Bei ungewöhnlicher Formulierung stieg die Zahl gefundener Regeln von 0 auf 4 von 6, ohne dass eine falsche Regel angenommen wurde.
Vertragsprüfung am deutschen Recht
Verträge mit Paketdiensten werden an §§ 431, 438, 439 und 449 HGB und § 73 PostG geprüft, bevor sie ein Paket steuern. In den Versandplattformen, die ich mir angesehen habe, habe ich das nicht gefunden.
Echte Daten mit Quellen
Echte Paketdienste, echte Produkte und veröffentlichte Preise, jeweils mit Quelle und Prüfdatum. Beispieldaten sind dort gekennzeichnet, wo sie vorkommen.
So funktioniert es
01
Paketdienste vergleichen
Für jedes Paket wendet Meridian die eigenen Größen- und Gewichtsregeln jedes Paketdienstes an, wählt den günstigsten passenden Service und zeigt Preis und Lieferzeit nebeneinander. Jeder Preis verweist auf seine Quelle.
02
Vertragsprüfung am deutschen Recht
Einen Vertrag als PDF oder Word hochladen. Haftung, Anzeigefristen und Verjährung werden am HGB und am PostG geprüft, und eine Bedingung, die gegen das Gesetz verstößt, stoppt den Entwurf.
03
Paketereignisse über Kafka
Sendungsereignisse laufen über drei Partitionen mit der Sendung als Schlüssel. Fehlerhafte Ereignisse gehen in ein Dead Letter Topic und blockieren nie den Rest, und Grafana zeigt Durchsatz, Lag und Dead Letters.
04
Privater Vertragsspeicher
Jedes Unternehmen sieht nur seine eigenen Verträge in S3. Das interne Team von Meridian kann sie für den Support lesen, und jeder Zugriff wird im Audit-Log festgehalten.
KI-Workflow-Automatisierung
- 01
Das Problem mit Regeln allein
Jeder Paketdienst formuliert Routing anders: „Postleitzahlbereich 50“, „the 20 postal area“, „PLZ-Gebiet 8“. Mein Regelleser verstand nur Formulierungen, für die er ein Muster hatte, also bedeutete jeder neue Vertrag ein weiteres handgeschriebenes Muster. Bei ungewöhnlich formulierten Verträgen fand er 0 von 6 Routing-Regeln.
- 02
Warum ein KI-Workflow
Unterschiedliche Sprache zu lesen, können Sprachmodelle gut; zu entscheiden, was erlaubt ist, muss exakt bleiben. Deshalb habe ich die Aufgabe geteilt. Ein lokales Modell (keine Daten verlassen den Rechner, keine API-Kosten) liest die Klauseln, die die Regeln nicht lesen, und deterministische Prüfungen und Menschen entscheiden.
- 03
Was es gelöst hat
Bei denselben ungewöhnlichen Verträgen fanden Regeln plus Modell 4 von 6 Regeln statt 0, jede angenommene Regel war richtig, und keine Falle wurde zur Regel. Neue Formulierungen brauchen kein neues Muster im Code mehr.
| Gelabelte Verträge | Leser | Ganz richtig | Gefundene Regeln | Fallen als Regel |
|---|---|---|---|---|
| 14 Verträge, übliche Formulierung | Regeln | 14 von 14 | 15 von 15 | 0 |
| 14 Verträge, übliche Formulierung | Regeln + Modell | 14 von 14 | 15 von 15 | 0 |
| 10 Verträge, ungewöhnliche Formulierung und Fallen | Regeln | 4 von 10 | 0 von 6 | 0 |
| 10 Verträge, ungewöhnliche Formulierung und Fallen | Regeln + Modell | 7 von 10 | 4 von 6 | 0 |
In einem Lauf fand das Modell 4 von 6 erwarteten Regeln. Alle 4 vorgeschlagenen Regeln waren richtig; es erfand keine. Die Ergebnisse können zwischen lokalen Läufen variieren, auch bei Temperatur 0.
Gebaut auf meiner Produktionsarbeit bei tyntec
Bei tyntec baue und betreibe ich fullstack Services. Meridian überträgt diese Muster in eine neue Domäne. Die Zahlen hier stammen von tyntec, nicht von Meridian; Details zu Kunden, Produkten und Daten sind bewusst weggelassen.
- Nachrichten am Tag durch Kafka-Pipelines
- Millionen
- Länder in geplanter, verteilter CSV-Verarbeitung
- 50+
| Pattern | Bei tyntec | In Meridian |
|---|---|---|
| Routing-Konfiguration | Ein Operator-Tool für Routing-Regeln, getrennt von der Logik, die sie anwendet, jede Änderung protokolliert und rückgängig zu machen. | Routing-Regeln als versionierte Daten, befüllt aus Verträgen mit Paketdiensten durch die Regeln und den KI-Workflow. |
| Kafka-Pipelines | Millionen Nachrichten am Tag: idempotente Consumer, Reihenfolge pro Kunde, fehlerhafte Ereignisse in Quarantäne. | Ereignisse der Paketdienste auf drei Partitionen mit der Sendung als Schlüssel, mit Dead Letter Topic, beobachtet in Grafana. |
| Prüfen vor dem Speichern | Operatoren sehen genau, was geschrieben wird, bevor etwas gespeichert wird. | Ein Testlauf mit aktuellen Paketen und eine zweite Freigabe, bevor eine Regel live geht. |
Herausforderungen und Gelerntes
Herausforderung: In meinem ersten Kafka-Lasttest blieben zwei der drei Partitionen mit einem Lag von etwa 400 Ereignissen stehen. Das Standard-Dead-Letter-Topic von Spring Kafka war mit nur einer Partition angelegt worden, sodass fehlerhafte Ereignisse aus den Partitionen 1 und 2 nicht abgelegt werden konnten und jedes gesunde Ereignis dahinter wartete.
Lösung: Ich habe das Dead Letter Topic ausdrücklich benannt und ihm drei Partitionen gegeben, damit ein fehlerhaftes Ereignis seine Partition behält, und einen Test mit eingebettetem Kafka-Broker genau für diesen Weg ergänzt. Der nächste Lauf mit 16.493 Ereignissen lief auf einen Lag von 0 ab, jedes Ereignis nachgewiesen.
Gelernt: Dieselbe Lehre wie in der Produktion bei tyntec: Eine fehlerhafte Nachricht darf nie die gesunden blockieren. Auch Standardwerte sind Entscheidungen, deshalb braucht der Dead-Letter-Weg einen eigenen Test.
Eingesetzte Technologien
Backend ·Java 21
- Die Domäne als einfache Records und Klassen: Vertragsleser, Prüfung am deutschen Recht, Routing-Regeln, Regeländerungen, Paket-Lebenszyklus.
- Keine Framework-Importe in der Domäne; Architekturtests lassen den Build sonst scheitern.
Backend ·Spring Boot
- Die REST-API, Validierung der Anfragen und Fehler im Problem-Details-Format (RFC 9457).
Sicherheit ·Spring Security
- Zwei getrennte API-Bereiche: ein öffentlicher für Vergleich und Vertragsprüfung und eine Konsole für das Team mit den Rollen Operator, Freigabe und Lesen.
Dokumente ·Apache PDFBox
- Liest Text aus hochgeladenen PDF-Verträgen aus; DOCX, ODT und Klartext verarbeitet die App mit den ZIP- und XML-APIs von Java.
Testing ·JUnit, AssertJ und MockMvc
- 93 % Testabdeckung für einzelne Frachtrechtsregeln und API-Abläufe: Regeländerungen entwerfen, testen, einreichen und freigeben.
Testing ·ArchUnit
- Hält die Domäne frei von Spring und Jackson und die Anwendungsschicht frei von Adaptern.
Testing ·Auswertung des Vertragslesers
- 14 gelabelte Verträge mit Fallen, etwa versteckten Anweisungen und Klauseln mit Bedingungen, bei jedem Build gelesen, mit Precision und Recall pro Lauf.
KI ·Ollama mit qwen2.5 7B
- Ein lokales Sprachmodell, das die Vertragsklauseln liest, die der Regelleser nicht liest, und in einem festen JSON-Schema antwortet.
- Jede Antwort durchläuft eine Prüfung gegen die Klausel, danach dieselbe Rechtsprüfung, denselben Testlauf und dieselbe Freigabe wie jede andere Regel.
- Mit den Regeln allein an denselben gelabelten Verträgen verglichen.
Speicher ·AWS S3 mit LocalStack
- Hochgeladene Verträge über das AWS SDK für Java mit serverseitiger Verschlüsselung gespeichert; lokal LocalStack in Docker, AWS S3 per Konfiguration.
- Privater Speicher pro Unternehmen: Kein Unternehmen sieht die Dateien eines anderen, und jeder Lesezugriff des internen Teams wird im Audit-Log festgehalten.
Frontend ·React, TypeScript, React Router und Vite
- Die Web-App: Startseite, Vergleich der Paketdienste, Vertragsprüfung, Regeländerungen und Kassenvorschau.
Testing ·Vitest und Testing Library
- Komponententests für die Versandwahl, das Prüfergebnis und den Testlauf von Regeländerungen.
Testing ·Playwright
- End-to-End-Browsertests prüfen Web-App und API zusammen: Paketdienstvergleich, Vertragsprüfungen und Uploads, Änderungsfälle, Checkout und Handybreite. Sie laufen in GitHub Actions.
Build ·Gradle und GitHub Actions
- Eine Pipeline für Backend-Tests, Typprüfung, Web-Tests, Web-Build und Browsertests.
Lokale Infrastruktur ·Docker Compose
- Startet den lokalen S3-Dienst, Kafka, Kafka UI, Prometheus, Grafana und Kafka Exporter.
Daten ·PostgreSQL und FlywayGeplant
- Ersetzt den Speicher im Arbeitsspeicher hinter den vorhandenen Ports.
Sicherheit ·KeycloakGeplant
- Login für die Konsole.
Messaging ·Apache Kafka und Spring Kafka
- Sendungsereignisse der Paketdienste auf einem Topic mit drei Partitionen, mit der Sendung als Schlüssel, damit die Ereignisse einer Sendung in Reihenfolge bleiben.
- Drei Consumer-Threads, Retries mit Back-off und ein Dead Letter Topic, das Schlüssel und Partition jedes fehlgeschlagenen Ereignisses behält, sodass ein fehlerhaftes Ereignis nie den Rest blockiert.
- Ein Simulator sendet Lastspitzen mit Duplikaten, vertauschten Schritten, kaputtem JSON und unbekannten Sendungen; ein Test mit eingebettetem Broker belegt den Dead-Letter-Weg.
Observability ·Micrometer, Prometheus, Grafana, Kafka UI und Kafka Exporter
- Micrometer stellt Ereignisergebnisse, Dead Letters, Verarbeitungszeit und Prüfwarteschlange bereit; Prometheus sammelt sie, und Kafka Exporter ergänzt den Consumer Lag pro Partition.
- Ein vorkonfiguriertes Grafana-Dashboard und Kafka UI zeigen Ereignisse, Topics, Nachrichten und Consumer Groups.
Mehr erfahren?
Ich zeige Ihnen gern die Produkt- und Engineering-Entscheidungen in einem Call. Lassen Sie uns sprechen.