Alexandria
Architecture

Bounded Contexts

The server and client bounded contexts of Alexandria: their domain, use cases and ports.

Bounded Contexts

Each side is a self-contained module with the same internal shape: domain/, app/, adapters/ and a module.go that wires them. The standalone binaries and the in-process tests build the module the same way.


Server (internal/server)

Domain

Namespace, Steward, Principal, Vocabulary and Revision, Draft, Candidate, Event, and the authorization decision of §3.5 as a pure function of the operation, the principal and steward membership.

Use cases (app)

Use caseResponsibility
NamespacesCreate and read namespaces; assign, list and remove stewards.
Vocabularies / vocabulary readerRegister vocabularies, store content, refresh proxies; a separate read path with no upstream fetcher.
AuthoringDrafts: create, replace under If-Match, validate, propose.
ReleaseApprove or reject a candidate; plan dates, check invariants, publish and sign.
RevocationRevoke a version under REV-1–REV-4 and issue a listing.
ListingIssue and serve the signed listing and records.
PublicationResolve /pub routes.
QueryEvents and candidates.

Ports

PortPurpose
NamespaceRepo, StewardRepo, VocabRepo, DraftRepo, CandidateRepo, ReleaseStore, ListingStore, EventLogPersistence, combined in Store.
BlobStoreContent-addressed bytes.
KeySignerSigns with the hub key.
DIDResolverResolves the hub's own DID document.
UpstreamFetcherDownloads a proxy vocabulary.
ProfileCompilerValidates a draft and compiles its package.

Client (internal/client)

Domain

Rules and rule selection, the state machine, classification, the action tables, the admission table, the snapshot of in-force versions, retention, and the VHub-Verdict header. All are pure functions: Decide receives everything a decision depends on.

Use cases (app)

Use caseResponsibility
SyncThe S1–S13 pipeline and the atomic acceptance of a listing.
HubTrustThe cached hub DID document and proof verification V0–V4.
EdgeThe hot path: decide, forward or reject, capture agreements, feed the audit, emit events.
ExplainerThe same decision without effects.
RulesRule-set CRUD with optimistic concurrency.
AgreementsThe agreement registry and revocation notices.
AuditThe passive audit buffer and report.
StatusStatus documents, the clock-skew estimate and state-change events.
GCPackage collection.

Ports

PortPurpose
HubAPIListing, manifests and package files.
DIDResolverHub DID document.
EvaluatorEvaluates a message against the artefacts of one package.
ContinuityStore, PackageStore, RuleStore, AgreementRepo / AgreementReaderPersistent state.
EventSink, MetricsObservability.
UpstreamThe connector behind the proxy.

The published snapshot is immutable and swapped atomically, so a request always sees one consistent listing, one set of packages and one rule-set revision.


Profile Language (internal/dsl)

The alexandria.profiles/v1 compiler is independent of both contexts. alexandriac uses it directly, and the server reaches it through the compiler_dsl adapter when compiler: dsl is configured.

On this page