Architecture — the Aetherin core
This document is the map of the codebase: what lives where, why it lives there, and what a change may not do. The boundaries are not aesthetic — each one exists because breaking it would be invisible in a diff and visible in production.
scripts/check-structure.sh enforces the rules below in CI.
1. The four planes
The system has four trust levels. Every request moves through them, and each boundary is a place where a credential is checked.
Internet
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. EDGE — aetherin-middleware (Vercel) │
│ public entry point: auth gate, CORS, size limits, │
│ circuit breaker, security headers, request id │
│ credential: operator session OR client API key │
└─────────────────────────────────────────────────────────────┘
│ x-service-token (server-to-server) + caller's credential
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. HOST EDGE — Caddy on the box (optional) │
│ TLS termination, /aether/api → core, /aether/gateway/* │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. CORE — aetherin-server-core │
│ ┌───────────────────────┐ ┌─────────────────────────┐ │
│ │ 3a. DATA PLANE │ │ 3b. CONTROL PLANE │ │
│ │ high volume, hot path │ │ low volume, high impact │ │
│ │ chat, embeddings, │ │ keys, providers, models,│ │
│ │ usage, budgets │ │ orgs, team, admin, │ │
│ │ credential: API key │ │ pricing, billing │ │
│ │ no cookie, no CSRF │ │ credential: session + │ │
│ │ │ │ CSRF proof, role-gated │ │
│ └───────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. PLATFORM — internal only, never exposed │
│ kernel, plugins, providers, store, sealed secrets, │
│ discovery worker, pricing engine, policies │
└─────────────────────────────────────────────────────────────┘Why the planes are separated. A defect in the data plane costs latency and money; a defect in the control plane costs credentials, other tenants' data, or the deployment. They have different failure costs, different review depths, and different availability requirements — so they must not share a package where a change to one is indistinguishable from a change to the other. The control plane is where role checks, CSRF proofs and the audit trail live; the data plane is where the hot path lives and where a per-chunk allocation would show up.
2. The package map (current)
pkg/pluginsdk/ the public plugin contract — semver-frozen, no internal imports
internal/kernel/ the microkernel: transport, plugin host, config, events,
secrets, storage. Stdlib-only. Imports nothing but itself
and pkg/pluginsdk.
internal/platform/ cross-cutting runtime, no product concepts:
security/ origin policy, CSRF proof, SSRF target policy
httpx/ CORS handler, request-id propagation
internal/api/ the HTTP boundary: handlers, DTOs, authorization, CSRF,
error envelope, route registration
internal/auth/ password hashing, API-key hashing, CSRF generation
internal/billing/ plans, Stripe, ledger, events, CSV export
internal/discovery/ the feed engine (openrouter/static_file) + the worker
internal/fallback/ the upstream retry/fallback policy
internal/pricing/ default/recommended/effective price engine
internal/providers/ the upstream adapters (OpenAI, Anthropic, Gemini, …)
internal/ratelimit/ budget counters and rate limiting
internal/secretsource/ the pluggable secret backends (env/file/infisical/vault/aws)
internal/store/ persistence: Postgres + the in-memory fakes
plugins/ring0/ kernel plugins: healthz (real), config, eventbus, registry,
secrets, storage, transport (scaffolds)
plugins/ring1/ product plugins: auth, metering, providerregistry,
ratelimit, router (scaffolds)The rules
| # | Rule | Enforced by |
|---|---|---|
| 1 | internal/kernel imports nothing outside itself and pkg/pluginsdk | check-structure.sh |
| 2 | pkg/pluginsdk imports nothing from internal/ | check-structure.sh |
| 3 | internal/platform imports no product package | check-structure.sh |
| 4 | A plugin never imports another plugin | check-structure.sh |
| 5 | The direct dependency set is frozen | check-structure.sh |
| 6 | Every internal/ package is in this map | check-structure.sh |
| 7 | A new capability needs an SDK constant, a host gate, docs, and a test | review (AGENTS.md) |
| 8 | The request fast path does not allocate per chunk | review + benchmarks (AGENTS.md) |
| 9 | Metering and logging never block a streaming response | review (AGENTS.md) |
3. The target structure
internal/api is 13,400 lines across 20 files. It is the one place where the planes are *not* separated: a change to billing sits in the same package as a change to the chat path, and a reviewer cannot see the blast radius without reading every file. The target splits it by plane and by domain:
internal/httpapi/ the transport boundary only:
DTOs, error envelope, CSRF, authorization helpers,
route registration. Knows no domain.
internal/identity/ sessions, users, orgs, workspaces, teams, invites, RBAC
internal/catalog/ providers, models, routes, pricing, discovery
internal/metering/ usage events, budgets, the ledger
internal/commerce/ plans, checkout, portal, invoices, Stripe webhooks
internal/gateway/ the data plane: chat, embeddings, chain resolution.
Owns its benchmarks (the hot path).Why this order. The split is by *plane first* (gateway versus the rest), then by *domain*. Plane first because that is the security boundary that matters: a package that serves the data plane must not import the control plane's authorization code, or the hot path would grow an RBAC dependency.
How it happens safely. A mechanical package move breaks the compiler in every file it touches, which is the point: the compiler is the refactoring tool. The order is:
- Move
chat.go+chain.go→internal/gateway(2 files, 380 lines).
They depend on store, providers, fallback, ratelimit — all of which stay put. No domain logic moves.
- Move
auth.go,orgs.go,team.go,tenant.go→internal/identity. - Move
pricing.go,routes.go, andinternal/discovery→
internal/catalog.
- Move
usage.go+internal/billing→internal/metering/internal/commerce. internal/apikeeps onlyapi.go,dto.go,helpers.go,csrf.go,
authorization.go, health.go, webhooks.go and becomes internal/httpapi.
Each step is a separate PR with the full suite green, and no step changes behaviour. The MODULE_* toggles in api.go keep working: they are read at registration time and the registration moves with the code.
4. The plugin system — honest status
plugins/ring0/healthz is a real plugin. The other eleven are 34-line scaffolds: a manifest, an empty Init, and a TODO(Wave 2). The real product logic lives in internal/, not in plugins.
This is a documentation problem as much as a code problem: AGENTS.md describes a plugin architecture that does not exist yet, so an agent reading it will look for product logic in plugins/ring1/ and find nothing.
Two honest ways out:
- Implement the ring. Make
ring1/authown sessions and RBAC,ring1/metering
own usage collection, ring1/providerregistry own provider CRUD, ring1/router own route registration. That is the architecture the SDK was designed for, and it is a large but well-defined refactor.
- Retire the scaffolds. Delete them, keep
ring0/healthzas the worked
example, and rewrite AGENTS.md to describe the structure that actually exists: kernel + platform + httpapi + domain packages.
The second is cheaper and removes a lie; the first is the better end state. Until one is chosen, plugins/ring1/* should be treated as documentation of an intent, not as a seam that new work is expected to follow.
5. The core's dependency set
github.com/golang-migrate/migrate/v4 schema migrations
github.com/google/uuid identifiers
github.com/jackc/pgx/v5 Postgres driver
github.com/redis/go-redis/v9 Redis client
golang.org/x/crypto password hashingThat is the whole set. It is frozen: check-structure.sh fails the build when go.mod gains a direct dependency, because adding one is an architectural decision (AGENTS.md) and not an implementation detail.
6. The rest of the project
| Repo | Group | What it owns |
|---|---|---|
aetherin-common | contract | the OpenAPI spec, JSON schemas, codegen config, the docs site |
aetherin-server-core | runtime | this document |
aetherin-middleware | edge | the Vercel proxy: auth gate, CORS, circuit breaker, crons |
aetherin-frontend | console | the Next.js operator console |
aetherin-deploy | operations | box deployment, secrets chain, backups, migrations fetch |
aetherin-gtm | go-to-market | launch copy, positioning, pricing page copy |
The contract comes first. aetherin-common/openapi/openapi.yaml is the source of truth; clients are regenerated from it and CI fails on drift. A change to a request or a response shape is a change to the contract, then to the core, then to the clients — never the other way round.