Alexandria
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 · logx

Dependencies point inward: adapters → app → domain → core.

LayerContainsMay import
corePure, network-free building blocks shared by both sides.Standard library and the allowed modules.
domainEntities and pure decision functions.core.
appUse cases and the ports (interfaces) they need.domain, core.
adaptersImplementations of ports and driving HTTP handlers.app, domain, core, external modules.
module.goWiring 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:

TestGuarantee
TestLayersPointInwardcore, domain and app never import outer layers, the wall clock or the test kit.
TestServerAndClientDoNotImportEachOtherThe two bounded contexts stay apart.
TestOnlyAllowedExternalModulesProduction code imports only the allow-listed modules of DP-1.
TestOnlyClockReadsWallTimeOnly internal/clock calls time.Now(); everything else receives a timex.Clock (DP-8).
TestNoProductionImportOfTestkitinternal/testkit is never linked into a binary.
TestEdgeHasNoHubNorResolverThe 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

BinaryResponsibilities
cmd/alexandria-serverLoads and validates the configuration, prepares the laboratory TLS certificate, sets up telemetry and the clock, builds server.Module and serves its handler.
cmd/alexandria-clientChecks the configuration and rule set at startup, builds client.Module and serves one HTTP server per listener.
cmd/alexandriacCommand-line front end of internal/dsl.

Supporting packages outside the two contexts:

PackageRole
internal/clockSystem and file-backed implementations of timex.Clock.
internal/telemetryStructured logging, OpenTelemetry tracing and the HTTP middleware.
internal/webuiThe console build, embedded with the gui build tag.
internal/testkitIn-memory doubles, the fake identity provider and the F6 fixtures.

On this page