Architecture · public decisions
Decisions.
The architecture decisions we've made — for our clients (anonymized) and for our own systems. Documented in full so they can be defended, debated, or borrowed.
ADR-0042
RAG over a vector index, not fine-tuning
Ground-truth changes weekly. Index rebuilds are cheap; fine-tunes are not.
acceptedADR-0041
NATS JetStream as the event backbone
Operational simplicity beats theoretical throughput at our message volume.
acceptedADR-0040
Two-pass extraction for multimodal documents
Layout-aware extractor first, reasoning model second. Fail-loud between them.
acceptedADR-0039
pgvector, not a managed vector database
Joins matter more than benchmarks at our query volume.
acceptedADR-0038
Temporal for long-running workflows
Notification flows span hours. State must survive restarts and deploys.
acceptedADR-0037
WorkOS for enterprise SSO, not Keycloak
SAML and SCIM are commodities. Operating Keycloak is a part-time engineering job.
acceptedADR-0036
800ms p95 latency budget for retrieval-augmented chat
Set the budget before choosing the components, not after.
acceptedADR-0035
Row-level security as the default isolation boundary
RLS in Postgres for every tenanted table. No exceptions in app code.
acceptedADR-0034
Streaming geospatial ingest, batch enrichment
Two pipelines from one source, optimized for different SLOs.
acceptedADR-0033
Fail-closed defaults across all middleware
Every middleware that cannot reach its dependency returns 503, never 200.
accepted