Architecture · stack · primitives · trade-offs
Built for operators who care about the boring parts.
The stack, the primitives, the trade-offs. Nothing here is handwaved. If you're an architect or security reviewer, this page is for you.
Stack diagram · 7 layers
The layers, top to bottom.
Hover any block. Every layer is replaceable; none of them are tightly coupled to a vendor.
▢
Frontend
Next.js · React · Tailwind
App Router. Server components for fast first paint, client components for interactivity. Routes are pre-rendered where possible.
⌖
API
NestJS · TypeScript
Module-per-domain. DTOs validated at the edge. Every endpoint declares its risk class and required ABAC attributes.
▤
Database
PostgreSQL · Drizzle ORM
Per-tenant schemas. Soft-delete + snapshot + audit baked into the base entity. Migrations versioned with rollback proofs.
▣
Cache
Redis
Hot reads, idempotency keys, ephemeral session state. Per-tenant key prefixes. Never the source of truth.
↯
Real-time
WebSocket Gateway
Per-tenant gateway. Backpressure-aware. Falls back to long-poll on bad networks. Bound to entity-channels, not user-channels.
✦
LLM
Pluggable · default: Gemini
Pluggable LLM — default Gemini with implicit prompt caching always on; explicit context caching is an opt-in flag for large system prompts. Also runs on NVIDIA, GPUHub, or any OpenAI-compatible runtime. Cache-backed prefixes cut cost per call at production volume — measured in your tenant's AI-Ops report. Swap providers per tenant.
♪
Voice
Pluggable · Whisper · Kokoro
Pluggable voice — default STT Whisper small.en (English-optimized; multilingual on upgrade), default TTS Kokoro at 24kHz. Real-time first audio. Swap any compatible engine. The LLM never decides flow transitions — the server does.
Production-grade · 9 / 9
Primitives, not promises.
Every operational entity ships with these from day one. Not a v2 roadmap item. Not behind a feature flag.
- ✓Multi-tenant from day one
- ✓Optimistic concurrency
- ✓Idempotent action ledger
- ✓Soft-delete + restore
- ✓Snapshot system
- ✓Retention policies
- ✓Cold-archive support
- ✓Unified audit log
- ✓JWT verification metadata
Connector setup · 4 steps
Wire a connector in under a day.
Most teams ship their first probe in an afternoon. Promote autopilot tiers later, on your timeline.
STEP 01
⌬
Register
POST /esap/connectors
{
"name": "pos.foodics",
"baseUrl": "https://api.foodics.com/v5",
"auth": { "kind": "jwt", "secret": "ENV:FOODICS_JWT" }
}STEP 02
◎
Probe
POST /esap/connectors/pos.foodics/probes
{
"endpoint": "GET /orders",
"interval": "30s",
"rule": { "field": "status", "eq": "stuck" }
}STEP 03
⊟
Classify
PATCH /esap/connectors/pos.foodics/risk
{
"endpoint": "POST /refunds",
"class": "WRITE-HIGH",
"tier": "MANAGER"
}STEP 04
▷
Promote
POST /esap/connectors/pos.foodics/promote
{
"tier": "AUTO",
"blast": 30,
"moneyCap": 1000
} Self-host vs managed
Two ways to run Apogee.
Same code. Same primitives. The only difference is who pages when something breaks at 2am.
| Dimension | Self-host | Managed |
|---|---|---|
| Data residency | Your VPC, any region | EU · KSA · US tenants |
| Provisioning | Helm chart, ~4 hours | Spin-up in under 1 day |
| Updates | You apply | Rolling, zero downtime |
| On-call | Your SRE | Our SRE · 24/7 |
| Audit export | S3 bucket of choice | S3 or SIEM stream |
| Custom connectors | Yes | Yes — co-built |
| Tenant data isolation | Always | Always |
| Public cost | Self-hosted licence | Per-deployment, contact |
Want the printable version?
Architecture brief covers everything on this page, plus auth flows, ABAC examples, retention policy templates, and the connector schema reference.