Valutra – Architektur & Systemdesign

Valutra modelliert Finanzentscheidungen als Cash-Flows und simuliert diese deterministisch über einen frei wählbaren Zeitraum.

• Deterministische, regelbasierte mehrjährige Cash-Flow-Simulation über einen frei wählbaren Zeitraum.
• Datenmodell trennt geplante Transaktionen von historischen/ausgeführten Zahlungen.
• Renten-/Ruhestandskostenmodell leitet zukünftige Basiskosten aus explizit getaggten Transaktionen ab und projiziert sie fort.
• Kredit-Lifecycle als geplante Cash-Flows mit separater Rückzahlungs-Statusverfolgung.
• Vermögenswachstum mit Zeitreihen-Historie und Vorwärtsprojektionen.
• FREE/PRO und rollenbasierter Zugriff werden serverseitig erzwungen (Funktionsumfang + Nutzungslimits).

Ich verantworte die technische Umsetzung end-to-end – von den Architekturentscheidungen bis zu Verantwortung für Qualitätssicherung und Betrieb.

• End-to-end technische Verantwortung für die Codebase (UI, API, Datenmodell, Ops).
• Definition von Security- und Access-Control-Patterns (Auth, Rollen, Berechtigungen).
• Verantwortung für Schema-Evolution und Migrationsstrategie (Prisma + Postgres).
• Verantwortung für definierte Qualitätskriterien (Tests, Linting, A11y-Checks).

Die Architektur ist so aufgebaut, dass Geschäftsregeln und Durchsetzung serverseitig zentral bleiben, während UI und API strikt typisiert und validiert sind.

Ein integriertes Next.js-System verbindet UI, API und Validierung über gemeinsame Typen und ein serverseitiges Ausführungsmodell.

• Single Next.js 15 Anwendung (App Router) mit TypeScript.
• Interne API via tRPC; Shared Types und Validation via Zod.
• React Server Components rufen tRPC via In-Process Caller auf; Client Components über /api/trpc.
• Internationalisierung route-basiert (/[locale]/...) via next-intl Middleware/Plugin.
• Statische Dokumentation via MDX (content/docs/*) und In-App Rendering.
• Geschäftsregeln sind von der UI getrennt; Validierung und Durchsetzung erfolgen ausschließlich serverseitig.

Das Frontend setzt auf SSR/Server Components, starke Typisierung und ein konsistentes Daten- und Formularmodell, um UX und Fachlogik sauber zu entkoppeln.

• React 19 + Next.js App Router; Server Components für SSR und Client Components für Interaktivität.
• Data Fetching/State: tRPC + @tanstack/react-query mit HTTP-Batching; superjson Serialisierung.
• Forms: react-hook-form mit Zod-Schemas für konsistente Client/Server-Validierung.
• Styling: Tailwind CSS v4 mit erzwungener semantischer Token-Nutzung (Custom Lint Scripts).

Im Backend werden Authentifizierung, Autorisierung und Berechtigungen an zentraler Stelle erzwungen – inklusive Sicherheitsmechanismen und auditierbarer Zustandsänderungen.

• API-Layer: tRPC-Router unter src/server/api/routers/* mit publicProcedure / authenticatedProcedure.
• Context enthält Session, Prisma Client, locale-aware Translator, requestId und Headers.
• Auth: NextAuth (Auth.js) Credentials Provider; bcrypt Password Hashes; JWT Sessions (Sliding).
• Authorization: Route Middleware blockt geschützte Seiten; tRPC erzwingt Auth und Rollen/Berechtigungen.
• Sicherheitsmechanismen: In-Memory Rate Limiting für Auth und Public Endpoints; Admin/Cron Endpoints per Secrets abgesichert.

Das Datenmodell ist auf deterministische Simulation und langfristige Wartbarkeit ausgelegt, inklusive Auditierbarkeit und transaktionaler Konsistenz.

• PostgreSQL + Prisma ORM (prisma/schema.prisma) mit Migrations und generiertem Client.
• Business Dates als DateOnly-Strings (YYYY-MM-DD) als String @db.VarChar(10), um TZ-Drift zu vermeiden.
• Money als Prisma Decimal; Conversion/Parsing an API-Grenzen.
• Konsistenz: Schreiboperationen via withTransaction() mit Serializable Isolation.
• Auditability: Append-only AuditLog Modell für sensitive/admin Operationen.

KI ist als optionaler, serverseitig orchestrierter Erweiterungspunkt gedacht – ohne Abhängigkeiten im laufenden Produktionsbetrieb.

• Nicht implementiert: keine Runtime-LLM-Calls und keine Provider-Konfiguration in src/env.js.
• Geplante Erweiterung: serverseitige Orchestrierung, aufrufbar aus tRPC/Route Handlers.
• Design-Intention: Prompts, Token-Zählung und Provider-Auswahl strikt in server-only Modulen kapseln.

Monetarisierung und Feature-Zugriff sind als harte Backend-Regeln implementiert, damit Plan-Nutzungslimits und Rollen nicht vom Client abhängig sind.

• Monetarisierungsdaten liegen in der DB (User.plan, planValidUntil) und werden im tRPC Context zu einem effektiven Plan aufgelöst.
• Funktionsumfang und Nutzungslimits sind zentralisiert (resolveCapabilities, getLimit) und werden serverseitig via Guards erzwungen.
• UserRole.DEMO ist ein harter Read-only Override; Mutations prüfen Non-Demo vor Schreiboperationen.
• adminProcedure beschränkt privilegierte Aktionen auf UserRole.ADMIN.

Deployment und Build-Prozess sind so aufgebaut, dass Migrationen, Generierung und Umgebungsvalidierung zuverlässig Teil des Deployment-Prozesses sind.

• Primäres Deployment Target: Vercel (vercel.json buildCommand, scheduled cron endpoints).
• Build-Prozess: prisma migrate deploy und prisma generate vor dem Next.js-Build.
• Umgebungsvalidierung via @t3-oss/env-nextjs mit produktionsseitiger Absicherung.
• Lokale Entwicklung mit Dockerized Postgres (docker-compose.yml, start-database.sh).

Qualität, Security und Barrierefreiheit sind als systematische Engineering-Praktiken verankert – mit automatisierten Tests, Tooling und klaren Betriebsleitplanken.

• Barrierefreiheits-Anforderung: WCAG 2.2 AA als verbindliches Qualitätskriterium vor Produktionsfreigabe.
• Barrierefreiheit ist eine nicht-funktionale Anforderung der Architektur, kein nachträgliches Styling.
• Tastaturnavigation: volle Bedienbarkeit, keine Traps, vorhersehbare Tab-Reihenfolge.
• Fokussteuerung: sichtbarer Fokus, Fokus-Kontinuität und Fokusbindung in Modals.
• Screenreader-Kompatibilität: korrekte Labels/Roles, sinnvolle Ansagen für Dialoge.
• Automatisierte A11y-Tests: Playwright + axe-core (test:a11y) plus gezielte Regression Tests.
• Testing: Vitest (Unit), Vitest + RTL (Component), Vitest (Integration; DB Reset via Prisma), Playwright (E2E).
• Tooling: ESLint (next lint), Prettier, Security Lint Rules, automatisierte Contrast Audits.
• Produktionsbetrieb: Request IDs durch Middleware und API Responses; zentralisiertes Error Reporting.
• Absicherung des Betriebs: Cron/Admin Jobs per Secrets und Postgres Advisory Locks gegen Parallelität abgesichert.

Ich betreibe, warte und entwickle Valutra eigenverantwortlich weiter – inklusive Deployment, Monitoring/Fehleranalyse, Schema-Evolution und kontinuierlicher Qualitätsabsicherung.