Reference architecture
A production-ready system,
from edge to data.
A representative design for a multi-tenant operations platform where fast interactions, reliable background work, and traceable decisions matter.
- Scope
- Web, mobile, partner integrations
- Pattern
- Modular core with event-driven workers
- Priority
- Reliability, security, operability
Architecture map
Keep the request path short.
Make every boundary visible.
The synchronous path returns only what the user needs. Work that can fail independently moves to durable events, while telemetry follows the request end to end.
Synchronous request Durable event Stateful service
Clients
HTTPS + correlation ID
Edge and access
Verified identity + tenant
Application
SQL, cache + durable events
Data and messaging
Request journey
One action,
five controlled boundaries.
Enter through the edge
Static assets are served from the CDN. The WAF, rate limits, and request validation reduce unwanted traffic before it reaches application compute.
Establish identity
OIDC creates a short-lived session. The gateway passes verified identity and tenant context, never client-supplied permissions, to the application.
Execute the use case
The BFF shapes data for the interface while the modular core owns business rules and writes the authoritative transaction to PostgreSQL.
Move slow work off-path
A committed outbox event is published to the queue. Idempotent workers handle integrations and notifications without delaying the user response.
Observe every boundary
A correlation ID connects browser telemetry, gateway logs, service traces, queue processing, and audit events for faster diagnosis.
Design decisions
Complexity must
earn its place.
Modular core before microservices
Clear module boundaries preserve future options without paying the network, deployment, and consistency costs of distributed services too early.
PostgreSQL is the source of truth
Transactions protect core workflows. Redis accelerates reads, but every cache entry remains disposable and can be rebuilt from durable data.
Events carry facts
Workers consume durable facts such as BookingConfirmed. At-least-once delivery is expected, so consumers use idempotency keys and safe retries.
Tenant context is mandatory
Tenant identity is established at authentication, propagated through every request, and enforced again in the data-access layer.
Operating the system
Designed for the day
after launch.
Reliability
Recover without guessing.
Health checks cover dependencies, not just processes. Timeouts are bounded, retries include jitter, dead-letter queues retain failed work, and recovery procedures are rehearsed.
- Availability and latency SLOs
- Idempotent commands and consumers
- Point-in-time database recovery
Security
Trust no client assertion.
Identity and tenant context are verified server-side. Secrets rotate, privileged actions create audit events, and access follows least privilege.
Delivery
Change in small, reversible steps.
CI checks types, tests, migrations, and dependency risk. Progressive rollout and feature flags separate deployment from release.
The outcome
A system teams can
change with confidence.
The architecture is intentionally evolutionary: a strong transactional centre, explicit asynchronous boundaries, and enough telemetry to make the next decision from evidence.