Architecture
Architecture Overview
Hexagonal architecture of Alexandria: two bounded contexts, a pure shared core, composition roots and the rules enforced by archtest.
Architecture Overview
Alexandria follows Hexagonal Architecture (ports and adapters). The code is one Go module with two bounded contexts — the server and the client — that share a pure core and never import each other.
Layers
cmd/alexandria-server cmd/alexandria-client cmd/alexandriac
│ │ │
▼ ▼ ▼
internal/server internal/client internal/dsl
├─ adapters (HTTP, SQLite, ├─ adapters (proxy, hub (profile language)
│ blobs, JWT, signer, │ client, SQLite, files,
│ compilers, fetcher) │ evaluator, admin API)
├─ app (use cases, ├─ app (sync, trust,
│ ports) │ edge, rules, ports)
└─ domain (entities, └─ domain (rules, state,
authorization) classification, action)
│ │
└────────────┬─────────────┘
▼
internal/core
timex · semver · canon · ni · did · vc · lifecycle
pkgv · codes · problem · schemas · jsonld · logxDependencies point inward: adapters → app → domain → core.
| Layer | Contains | May import |
|---|---|---|
core | Pure, network-free building blocks shared by both sides. | Standard library and the allowed modules. |
domain | Entities and pure decision functions. | core. |
app | Use cases and the ports (interfaces) they need. | domain, core. |
adapters | Implementations of ports and driving HTTP handlers. | app, domain, core, external modules. |
module.go | Wiring of one bounded context. | Everything of its own side. |
cmd/* | Composition roots: configuration, clock, telemetry, listeners. | The module of its side. |
Rules Enforced by Tests (internal/archtest)
The architecture is checked on every make test by parsing the imports of the production code:
| Test | Guarantee |
|---|---|
TestLayersPointInward | core, domain and app never import outer layers, the wall clock or the test kit. |
TestServerAndClientDoNotImportEachOther | The two bounded contexts stay apart. |
TestOnlyAllowedExternalModules | Production code imports only the allow-listed modules of DP-1. |
TestOnlyClockReadsWallTime | Only internal/clock calls time.Now(); everything else receives a timex.Clock (DP-8). |
TestNoProductionImportOfTestkit | internal/testkit is never linked into a binary. |
TestEdgeHasNoHubNorResolver | The hot path has no hub client and no DID resolver, so it cannot make a network request to decide (REQ-SYS-002). |
TestExplainHasNoEffects | :explain has no upstream, agreement store or event sink, so it cannot have effects (REQ-CLI-032). |
The last two guarantees are structural: the capability is absent from the type, rather than merely unused.
Composition Roots
| Binary | Responsibilities |
|---|---|
cmd/alexandria-server | Loads and validates the configuration, prepares the laboratory TLS certificate, sets up telemetry and the clock, builds server.Module and serves its handler. |
cmd/alexandria-client | Checks the configuration and rule set at startup, builds client.Module and serves one HTTP server per listener. |
cmd/alexandriac | Command-line front end of internal/dsl. |
Supporting packages outside the two contexts:
| Package | Role |
|---|---|
internal/clock | System and file-backed implementations of timex.Clock. |
internal/telemetry | Structured logging, OpenTelemetry tracing and the HTTP middleware. |
internal/webui | The console build, embedded with the gui build tag. |
internal/testkit | In-memory doubles, the fake identity provider and the F6 fixtures. |