Architecture
How the web app, databases, and packages fit together — for operators and developers.
High-level shape
Axiomatic cloud is a single Next.js application (apps/platform) that serves the product UI and REST JSON API routes under /api/... (Bearer API keys or interactive use from the logged-in app). There is no separate “Cortex server” or per-module backend — modules are routes and libraries inside one deploy.
Browser → Vercel (Next.js) → Control plane DB + Tenant DB(s)
↘
Neon / Postgres- Control plane — one database: who can log in, which tenant DB to use, encrypted tenant connection strings, entity mappings, credit balance metadata.
- Tenant DB — one per tenant in production (shared in dev): entities, ledger, CRM, and all other module tables for that customer.
Request handling resolves tenant + entity + role + DEK before running business logic. Handlers that need a single entity use entity-scoped middleware; a few routes are tenant-wide (e.g. listing entities).
Packages (monorepo)
Shared code lives in workspace packages, for example:
| Package | Role |
|---|---|
@axiomatic/db | Drizzle schemas: tenant tables, control plane, migrations |
@axiomatic/core | Shared types, classifiers, bridge helpers |
@axiomatic/ui | Shared UI (navigation, shell components) |
@axiomatic/ai-tools | Cortex tool definitions used by the AI layer |
engine/ | Rust / WASM rule engine and ZK-related tooling |
The web app imports these packages; schema changes flow through Drizzle migrations applied to all tenant databases — not ad-hoc push in production.
Security and secrets
- User auth — passkeys/password for the web app; API keys (
ak_…) for programmatic access withAuthorization: Bearer. - Field-level encryption — sensitive columns encrypted with the entity DEK at the application layer; see Encryption.
- Automation — scheduled or admin routes (e.g. cron, tenant migrations) validate a shared secret such as
CRON_SECRETonAuthorization: Bearer …headers.
Billing (cloud)
Credit balance is identity-scoped in the control plane. The platform gates writes when balance is insufficient (unless self-hosted). Rates and behavior are implemented in application code, not as a separate billing microservice.
Failure mode
Operations that must succeed return errors instead of silently falling back to alternate paths — so you do not accumulate orphaned rows that need manual repair.
Docs and marketing sites
- Documentation —
apps/docs(this site), Fumadocs + MDX. - Marketing — separate Next app; links to the same app URL for sign-in.
See also
- Glossary — terms used above
- Platform overview — product map
- API Reference — HTTP surface