Experience
web-advisor · web-client · web-ops · web-compliance · web-admin. Five Next.js 14 apps, server-rendered, locale-aware, multi-calendar.
Architecture
Six layers, one governed control plane.
A modular monolith on TypeScript with sidecars in Python (AI orchestrator, pricing) and Java (FIX gateway). Five Next.js applications. Hash-chained audit, three-layer auth, first-class i18n. Built to extract, not to refactor.
The six layers
Each layer is an explicit contract.
Gateway & Auth
Kong API gateway, Zitadel for OIDC, OPA for policy, OpenFGA for relationships. Every request is authenticated, authorized, and policy-checked.
Workflow
Temporal worker. Ten workflows: onboarding, trade order, audit verify, case management, AI interaction, recon, KYC recheck, suitability review.
Domain
NestJS modular monolith with ten bounded contexts. Strict DDD layout per context: domain, application, infrastructure, interface.
Data & Events
Postgres + TimescaleDB + pgvector. Redis for cache. Redpanda for events. MinIO for documents. OpenSearch for full-text search.
Governance
Hash-chained audit. Marquez for OpenLineage. Vault for secrets. OpenTelemetry pipelines into Prometheus, Loki, Tempo.
Component tour
Every service, every role.
Each component is independently deployable and owns its own Helm sub-chart, OTel resource, and Vault path.
| Service | Stack | Port | Role |
|---|---|---|---|
| apps/api | NestJS 10 · Fastify · Drizzle · Zod | 3000 | Modular monolith with 10 bounded contexts; OpenAPI auto-generated. |
| apps/worker-temporal | Temporal TS SDK 1.17 | — | 10 workflows on task queues default, trading, ai, documents, reconciliation. |
| apps/ai-orchestrator | FastAPI · LangGraph · NeMo · Langfuse | 7100 | 5 graphs (briefing, commentary, NBA, triage, suitability_draft); RAG via pgvector. |
| apps/pricing-service | FastAPI · QuantLib · numpy | 7000 | Pricing, TWR / MWR, VaR (historical sim), exposure analytics. |
| apps/fix-gateway | Spring Boot 3.3 · QuickFIX/J 2.3 | 9876 | NewOrderSingle / OrderCancelRequest / ExecutionReport routing; embedded simulator. |
| apps/web-advisor | Next.js 14 · Zitadel · TanStack Query | 3001 | Primary product surface — clients, portfolios, orders, AI insights. |
| apps/web-client | Next.js 14 | 3002 | Client portal — 7-stage onboarding wizard, portfolio, statements, requests. |
| apps/web-ops | Next.js 14 | 3003 | Operations console — onboarding queue, stuck workflows, recon, KYC dashboard. |
| apps/web-compliance | Next.js 14 · Monaco editor | 3004 | Compliance console — audit explorer, case queue, Rego rule editor. |
| apps/web-admin | Next.js 14 | 3005 | Tenant admin — locale defaults, users, roles, branding. |
| Postgres + TimescaleDB + pgvector | 14+ | 5432 | OLTP, time-series for positions, embeddings for RAG. |
| Redis | 7 | 6379 | Cache · BullMQ · idempotency · per-tenant cost counters. |
| Redpanda | Kafka API | 9092 | Event bus — 25 topics, ULID event IDs, Snappy compression. |
| MinIO | S3 API | 9000 | Documents bucket. Evidence bucket with object-lock (compliance mode). |
| OpenSearch | — | 9200 | Locale-aware analyzers; client search; document full-text. |
| Zitadel | Go | 8080 | OIDC, MFA, projects, roles. JWTs verified via JWKS. |
| OPA | Go | 8181 | Policy decisions — access, suitability, restricted_list, aml, ai_actions, data_access. |
| OpenFGA | Go | 8086 | Relationships — primary_advisor, delegated_advisor, household, viewer, editor, trader. |
| Vault | HashiCorp | 8200 | Secrets engine; per-tenant KV path; transit signing for audit witnesses. |
| Langfuse | Postgres-backed | 3001 | LLM trace store. Cost capture per request. |
| LiteLLM | Python | 4000 | Multi-provider LLM gateway with per-tenant rate limits + budget caps. |
Modular monolith
Don't refactor. Extract.
The api app is a NestJS modular monolith with strict module boundaries. Cross-context imports are blocked at lint time. When a context needs to scale independently, we extract it to its own service without rewriting clients.
When we don't extract
Most contexts share latency budgets and operational footprint. Extracting them adds overhead without benefit. We keep them in the monolith with strict module boundaries enforced by ESLint and TypeScript paths.
- Identity, client, audit, documents, onboarding, case
- Cross-context calls go through public interfaces only
- Domain events are typed and registered in
@wealthos/contracts
When we do extract
Sidecars for fundamentally different runtimes or scaling profiles.
- ai-orchestrator — Python LangGraph + NeMo Guardrails ecosystem
- pricing-service — QuantLib needs Python and a different scaling pattern
- fix-gateway — Spring Boot + QuickFIX/J in Java 21
- worker-temporal — Temporal worker is a separate runtime by design
Multi-tenant isolation
Three layers of authorization. Belt, braces, RLS.
Every request flows through Zitadel (authentication), OpenFGA (relationships), and OPA (policy). Once authorized, the API runs in an AsyncLocalStorage scope holding the tenant id; Drizzle issues SET LOCAL app.tenant_id before each query. Postgres RLS enforces the tenant filter even if a query forgets to.
If any layer is bypassed, the others stop the request. Defense in depth, by construction.
Hash-chained audit
Every regulated action lands here. None of them can leave.
Construction
contentHash = SHA256(canonicalJson({occurredAt, actor, action, resource, metadata}))
chainInput = prevHash + ":" + contentHash
recordHash = SHA256(chainInput)
genesisHash = SHA256("wealthos-genesis:" + tenantId)Per-tenant chain. BEFORE UPDATE and BEFORE DELETE triggers raise audit_events is append-only. auditVerificationWorkflow runs hourly via Temporal cron; opens a breach-severity case on any mismatch.
AI lifecycle
Every prompt walks through guards.
Input guardrails (NeMo) → OPA ai_actions policy → RAG retrieval (per-tenant pgvector, OPA-filtered) → LangGraph node execution → output guardrails → Langfuse trace span → human approval if state mutates.
LiteLLM enforces per-tenant cost ceilings in Redis. Approval mutations run as the approver's identity, not the AI's. The audit log shows the human, with metadata.aiInteractionId linking back.
Workflow durability
Ten Temporal workflows. Always.
Long-running orchestrations are durable, replayable, and versioned via workflow.patched().
| Workflow | Task queue | Trigger | Description |
|---|---|---|---|
| onboardingWorkflow | default | API call | Full client onboarding: KYC → suitability → docs → e-sign → compliance review → provision |
| tradeOrderWorkflow | trading | API call | Pre-trade checks → approval (if needed) → FIX route → fills → terminal |
| caseManagementWorkflow | default | API call | SLA timer with auto-escalation (max 3); states track API |
| auditVerificationWorkflow | default | Cron 0 * * * * | Hourly chain verification; opens case on mismatch |
| periodicReviewWorkflow | default | Cron daily | Per-account suitability + compliance evaluation |
| aiInteractionWorkflow | ai | API call | Approval gate (24h timeout) + commit-as-approver |
| documentSignatureWorkflow | documents | API call | DocuSeal envelope + reminders |
| reconciliationWorkflow | reconciliation | Cron 0 23 * * * | Daily position / transaction reconciliation |
| kycRecheckWorkflow | default | Cron 0 2 1 * * | Monthly KYC refresh sweep |
| suitabilityReviewWorkflow | default | Cron annual | Per-client annual suitability review |
Deployment topology
Helm umbrella. Argo CD. Per-tenant region.
The umbrella Helm chart composes 10 sub-charts; consumed by Argo CD via infra/argocd/apps/wealthos-prime.yaml. Each env (dev / staging / prod) has its own values overrides.
Architecture workshop
Map your stack to Modir in 90 minutes.
An architect-led discovery: jurisdictions, identity, integrations, calendars, deployment topology — costed pilot scope as the deliverable.