📖 Full Documentation Portal: Comprehensive guides, architecture diagrams, API specs, and Architecture Decision Records (ADRs) are published at caparicio-esd.github.io/alexandria.
Alexandria is a Vocabulary Hub engineered for sovereign dataspaces. It provides the single source of semantic truth to host, publish, and version domain ontologies, dereference semantic terms in real-time for dataspace connectors, and execute automated remote conformance tests.
- Vocabulary Lifecycle & Publishing: Author, version, document, and publish RDF, OWL, and SKOS vocabularies and dataset profiles extending shared dataspace models.
- Runtime Semantic Dereferencing: Real-time IRI resolution for dataspace Connectors parsing Self-Descriptions and data agreements without requiring manual bilateral coordination.
- Remote Conformance Testing: Automated semantic verification using W3C SHACL constraint shapes to certify that connector payloads and datasets comply with dataspace standards.
- Trust Anchor & Delegated Wallets: Private keys and signing operations never reside in the node; key custody is delegated to external wallets (supporting both Fafnir and Eclipse EDC IdentityHub).
- Node-Terminated Authentication: Secure OpenID Connect (OIDC) authentication with PKCE via Zitadel, issuing encrypted
HttpOnlysession cookies. - In-Process Modular Monolith: Engineered in Go around Hexagonal Architecture with strict module boundaries and complete TLS reverse proxy parity via Caddy.
- Go 1.26+
- Docker & Docker Compose
- Task (manages all development, build, and container lifecycles)
- OpenSSL (preinstalled on macOS/Linux for local CA generation)
Alexandria includes automated environment orchestration. Run:
# First time on a new workstation (trusts local CA, requires sudo once):
task tls:trust
# Bootstrap and start the entire stack:
task dev:autoThis single command brings up PostgreSQL, Caddy, Zitadel IAM, the wallet service, provisions required credentials, and starts the Alexandria node with hot-reload (air).
- Web Portal / API:
https://alexandria.127.0.0.1.nip.io:8443 - Login:
https://alexandria.127.0.0.1.nip.io:8443/api/v1/auth/login
(Default credentials:admin@alexandria.auth.127.0.0.1.nip.io/Password1!) - Decentralized Identifier (DID):
https://alexandria.127.0.0.1.nip.io:8443/.well-known/did.json - Health Check:
https://alexandria.127.0.0.1.nip.io:8443/healthz - Documentation (Local):
task docs:dev-> http://localhost:3000
All routine development and verification tasks are managed through Taskfile.yaml:
| Command | Description |
|---|---|
task dev:auto |
Orchestrate containers, bootstrap IAM/secrets, and start the node with hot reload. |
task test |
Run unit tests with race detection and generate coverage report. |
task test:integration |
Run integration test suites against live wallet services. |
task test:all |
Run complete unit and integration test suites. |
task check |
Full CI verification pipeline: format (gofumpt), lint (golangci-lint), and tests. |
task vuln |
Scan project dependencies for known vulnerabilities (govulncheck). |
task docs:dev |
Start the local Fumadocs documentation dev server with hot reload. |
task docs:build |
Build static documentation export for GitHub Pages. |
For in-depth explanations, configuration details, and architecture specifications, explore our documentation portal:
| Topic | Documentation Guide |
|---|---|
| Getting Started | Prerequisites & Local Quickstart |
| Configuration | One Document Model & Viper Overrides |
| Architecture | Hexagonal Design & Bounded Contexts |
| Wallet Port | Unified Wallet Port & Adapters (Fafnir / IdentityHub) |
| Remote Conformance | SHACL Shape Validation & Conformance Testing |
| Authentication & IAM | Zitadel OIDC, PKCE & Session Security |
| REST API Reference | HTTP Endpoints Catalog |
| Architecture Decisions | Accepted ADRs (0001 - 0007) |
alexandria/
├── cmd/alexandria/ # Application entrypoint & composition root
├── config/ # Baseline configuration (config.yaml)
├── deploy/ # Docker Compose and Helm deployment charts
├── docs/ # Documentation portal (Fumadocs + Next.js)
│ ├── app/ # Documentation site routes & landing page
│ ├── content/docs/ # Markdown/MDX documentation source
│ └── adr/ # Original Architecture Decision Records
├── internal/
│ ├── auth-proxy/ # Bounded context: Zitadel OIDC guard & session handling
│ ├── httpapi/ # Gin engine, route mounting pipeline & health probes
│ ├── observability/ # Logging (slog), metrics & telemetry
│ ├── ssi-auth/ # Bounded context: DID resolution, wallet port & adapters
│ │ ├── wallet/ # Unified wallet.Wallet port & domain models
│ │ ├── fafnir/ # Driven adapter for Fafnir wallet
│ │ └── identityhub/ # Driven adapter for Eclipse EDC IdentityHub
│ └── storage/ # Database repositories and migrations
└── Taskfile.yaml # Automation and development workflows
This project is licensed under the Apache 2.0 License. See LICENSE for details.