Valutra – Architecture & System Design

Key architectural decisions that ensure determinism, enforceability, and operational reliability at scale.

Valutra models financial decisions as cash flows and simulates them deterministically over a configurable horizon.

• Deterministic, rule-based multi-year cash-flow simulation over a user-defined horizon.
• Data model separates planned transactions from historical/executed payments.
• Retirement cost model derives future baseline expenses from explicitly tagged transactions and projects them forward.
• Loan lifecycle is modeled as scheduled cash-flows with separate repayment state tracking.
• Asset growth projection uses time-series value history and forward projections.
• FREE/PRO plan logic and role-based access control are enforced server-side (capability resolution + usage limits).

End-to-end technical ownership across architecture, implementation, and operations.

• End-to-end technical ownership of the codebase (frontend, backend, data model, operations).
• Defines security and access-control patterns (authentication, role-based access control, capabilities, usage limits, audit logging).
• Owns schema evolution and migration strategy (Prisma + PostgreSQL).
• Owns quality controls (tests, linting, accessibility checks).

A single, strongly typed Next.js application with centralized server-side enforcement and shared validation across UI and API boundaries.

The system keeps business rules enforceable on the server while sharing types and validation rules across UI and API boundaries.

• Single Next.js 15 application (App Router) using TypeScript.
• Type-safe API layer via tRPC; shared validation via Zod.
• React Server Components and Client Components share a consistent server-side API contract.
• Internationalization is route-based via next-intl.
• Documentation pages are rendered from MDX content.
• Domain logic is isolated from UI concerns; validation and enforcement are performed server-side.

Server-rendered pages for performance and correctness, with client-side interactivity where required.

• React 19 + Next.js App Router; Server Components for SSR + Client Components for interactivity.
• Data fetching/state: tRPC with TanStack Query, HTTP batching, and SuperJSON serialization.
• Forms: React Hook Form with Zod schemas to align client/server validation.
• Styling: Tailwind CSS v4 with enforced semantic token usage (custom color lint scripts).

Centralized server-side enforcement for authentication, authorization, and all sensitive state transitions.

• API layer: tRPC procedures for public and authenticated use cases.
• Request context includes session, database access, localization, request tracing metadata, and headers.
• Auth: NextAuth (Auth.js) credentials provider; bcrypt password hashes; JWT sessions with sliding expiration.
• Authorization: protected routes and API procedures enforce role-based access control, capability resolution, and usage limits server-side.
• Security controls: in-memory rate limiting for authentication and public endpoints; administrative endpoints and scheduled jobs are restricted to secret-protected access.

A PostgreSQL data model optimized for deterministic simulation and auditability.

• PostgreSQL with Prisma ORM, schema migrations, and generated client.
• Business dates are stored as YYYY-MM-DD strings to avoid time zone drift.
• Monetary values use decimal precision; conversion and parsing are handled at API boundaries.
• Consistency: critical write operations run under Serializable isolation.
• Auditability: append-only audit logging for sensitive and administrative operations.

AI is treated as an optional, server-orchestrated extension point.

• Not implemented: no runtime LLM calls in production and no active provider configuration.
• Planned extension: add a server-side orchestration layer callable from tRPC/route handlers.
• Design intent: keep prompts, token accounting, and provider selection isolated to server-only modules.

Monetization rules are implemented as strict backend constraints, independent of the client.

• Plan state and validity are stored in the database and resolved into an effective plan for each request.
• Capability resolution and usage limits are centralized and enforced server-side.
• Demo access is a strict read-only mode; write operations require a non-demo role.
• Privileged administrative actions are restricted to administrative roles.

A deployment process designed for safe schema evolution, controlled releases, and operational stability.

• Primary deployment target: Vercel with scheduled jobs.
• Database migrations and Prisma client generation run before the application build.
• Environment validation is enforced via @t3-oss/env-nextjs with production-grade configuration.
• Local development uses a Dockerized PostgreSQL instance.

Quality, security, and accessibility are treated as enforceable engineering constraints, supported by automated verification.

• Accessibility requirement: WCAG 2.2 AA is defined as a mandatory release criterion.
• Accessibility is treated as a non-functional architectural requirement, not as post-processing.
• Keyboard navigation: full operability, no traps, predictable tab order.
• Focus management: visible focus, focus continuity, and modal focus trapping.
• Screen reader compatibility: correct labels/roles, meaningful announcements for dialogs.
• Automated accessibility testing: Playwright + axe-core with targeted regression tests.
• Testing: automated unit, component, integration, and end-to-end test coverage.
• Tooling: ESLint, Prettier, security lint rules, and automated contrast checks.
• Production readiness: request IDs propagated through middleware and API responses; centralized error reporting.
• Operational safeguards: scheduled and administrative jobs are protected by secrets and PostgreSQL advisory locks to prevent concurrent runs.

I operate, maintain, and evolve Valutra independently — including deployments, incident analysis, schema evolution, and ongoing quality assurance.