The building-block view of arc42: the context first, then one whitebox per box that opens, down to the modules of the code. Every box but the User is a link: a box with a whitebox leads to the level below, every other box to the chapter that documents it.
A building-block view shows a system as nested boxes: the context view has the system as one black box among its communication partners, and each whitebox opens one box to show the blocks inside it and the lines between them. The tables under each diagram carry the responsibility of every box and the text of every line. The diagrams are exported from the model in docs/architecture.yaml and rebuilt with the site.
Each diagram's legend shows a sample of the four line kinds:
business
Solid, the strongest line, with a plain arrowhead: the catalog flows. Provide, require, reports, catalog pushes and the queries that answer them.
admin
Thin and solid with a key as its head: operation and login. Administration, authentication, settings, the backup download and the directory lookups behind a login.
telemetry
Dotted with a gauge as its head: traces and metrics. They leave every request through middleware, so no box calls Telemetry on purpose.
async-outbound
Dashed with an envelope as its head: pushes that leave the request. Webhook deliveries from the outbox and the live updates streamed to the dashboard.
Sanshain sits between the build pipelines of many microservices: Build Tooling publishes specs and Backstage catalog files as Producer and fetches pinned endpoint snippets as Consumer, while people use the web dashboard to inspect versions and the dependency graph and AI clients ask the catalog over MCP. Human login can be delegated to LDAP/AD or an OIDC provider; machine clients always use API tokens, full or read-only. State lives in SQLite or PostgreSQL, a Backup Job pulls consistent snapshots, traces and metrics go to an optional observability stack, and every catalog fact is pushed as a signed event to the webhook receivers on the allow-list.
Claude Code or another MCP client that asks the catalog questions: list and describe services, find an endpoint, read a spec, walk the graph, diff and blame versions. Read-only, rate-limited, catalog data only.
MCP tool calls with a read-only API token (Streamable HTTP) (Sanshain Service)
Helm CronJob (or any scheduler) that downloads a consistent SQLite snapshot nightly and keeps the last N files; on PostgreSQL a pg_dump CronJob takes its place and never talks to Sanshain.
GET /admin/backup/sqlite with a full API token (HTTPS) (Sanshain Service)
Maven plugin, cargo-sanshain, Go CLI, JS client/GitHub Action and Conan plugin; publish specs and the Backstage catalog-info.yaml for a Producer and fetch pinned endpoint snippets for a Consumer during CI builds.
provide / require / report (REST, API token) (Sanshain Service)
Any URL on the admin's allow-list, a Slack or a Teams incoming webhook: receives the signed events Sanshain emits (version published or deprecated, provide rejected, dependency recorded, branch cut, catalog recorded), retried from the outbox for 24 hours.
–
signed event POSTs: JSON envelope or Slack/Teams message (HTTPS, HMAC-SHA256) (Sanshain Service)
Central registry for OpenAPI, AsyncAPI and gRPC specs: Producers publish versioned specs, Consumers download only the endpoints they pin, and the resulting dependency graph is tracked, shown, pushed as signed webhook events and served to AI clients over MCP.
Hexagonal layering: the HTTP API and the MCP Server translate requests into use cases; Application Services hold the business rules and depend on traits in the domain layer (models, permissions, ports - shared by every box, so not drawn). Infrastructure adapters implement those ports: Auth Providers for human login and Persistence for storage. Spec parsing is kept apart from the use cases so that the free validator and the publish path apply identical rules. Webhooks are their own flow: the use cases write events into an outbox in the same transaction as the fact, and a background worker delivers them, so a slow receiver never slows a provide. Telemetry is fed by middleware layers on every request rather than by explicit calls. Line kinds: business (catalog flows), admin (operation and login), telemetry (traces, metrics), async-outbound (pushes that leave the request).
Use cases (src/application): provide and require specs, version-line rules, release branches and graph timelines, Backstage catalog context, reports, administration, authentication with token scopes and permission checks, and the MCP catalog answers. Depends only on domain ports.
Adapters for human login (src/infrastructure/*_provider.rs, tls.rs): local Argon2 accounts, LDAP/AD bind and group lookup with connect and operation timeouts, and the OIDC authorization code flow.
Axum router, handlers and middleware (src/presentation, src/lib.rs): REST endpoints for provide/require/catalog/report/admin/auth, token and session authentication with full or read-only token scope, permission guards per route, SSE/WebSocket live updates, webhook management and the /metrics endpoint.
Model Context Protocol endpoint for AI clients (src/presentation/mcp.rs, src/application/mcp_service.rs; documented in the Developer track, MCP chapter): POST /mcp, Streamable HTTP, stateless, behind a read-only API token; tools list_services, describe_service, find_endpoint, get_spec, get_graph, diff_versions and blame answer from the catalog only, rate-limited per token and size-budgeted per answer.
Implements the SpecRepository port: a Moka cache with a 10 s data TTL in front of interchangeable sqlx repositories for SQLite and PostgreSQL, including schema migrations, the webhook outbox tables and the SQLite snapshot.
OpenTelemetry tracer with OTLP exporter (src/infrastructure/telemetry.rs) and the Prometheus recorder behind /metrics; fed by the tracing and metric layers of every request.
Browser dashboard (static/*.html, static/js, askama templates): producers, consumers, version timelines, diffs, dependency graph with peripheral resources and catalog context, reports, audit, observability, webhook and admin pages, account page with API tokens, plus the anonymous spec validator.
Outbound events (src/application/webhook_service.rs, webhook_delivery.rs, src/infrastructure/webhook_sender.rs, ADR-0009): decides which hooks a fact reaches (global hooks plus the hooks of the Producer and of its Consumers along the require graph), writes the deliveries to the outbox with the fact, and a worker claims due deliveries, renders JSON, Slack or Teams bodies, signs them with HMAC-SHA256 and POSTs them with backoff for 24 hours; egress is limited to the admin's host allow-list.
The endpoint groups follow the public REST surface documented in api.yaml: Build Tooling provides, requires, pushes catalog files and pulls reports; the Web UI uses reports, live updates, administration and login; the Backup Job uses one admin route with a full API token. Every group hands its work to the Application Services; the admin group also manages webhooks and streams the SQLite snapshot. Authentication, token scopes, permission guards, CSRF and observability apply to every request alike, so they are drawn as the Request Guards band rather than as a box every line passes through.
/admin/* (handlers/admin.rs, roles.rs, webhooks.rs): producers, versions, promotion, diffs, branches, trunk graph and timelines, consumers, users, roles, groups, maintainers, settings, cleanup, observability, audit, webhooks in three scopes with the egress allow-list, and the SQLite snapshot download.
/auth/login, /auth/oidc/login and callback, /auth/logout, /auth/register, /auth/me and /tokens (handlers/auth.rs): human login, sessions and API tokens with a full or read-only scope.
POST /provide, /provide/asyncapi, /provide/grpc and PUT /catalog/{systemname} (handlers/api.rs): a Producer publishes an OpenAPI, AsyncAPI or Protobuf spec version or its Backstage catalog-info.yaml.
Cross-cutting request handling every endpoint passes (middleware.rs, lib.rs): API token (full or read-only scope) and session authentication, per-route permission guards, CSRF validation, CORS, compression, tracing and Prometheus layers feeding Telemetry, plus health/ready/metrics and HTML page routes.
GET /require, /require/asyncapi, /require/grpc, POST /require-bundle, GET /endpoint-versions and /producers/{name}/versions (handlers/api.rs): a Consumer fetches pinned endpoint snippets and discovers versions.
Split by use case rather than by entity: the write path (Provide) and the read path (Require) were pulled out of spec_service so neither flow is interleaved with rules it does not need, and the version rules were isolated as pure functions so they can be decided without a database. Release graphs and reports, administration, and access control each form their own module. Every module except Version Rules is reached from the HTTP API. All of them except Version Rules also store through the SpecRepository port; to keep the diagram readable that line is drawn only from Administration.
Authentication and authorization (auth_service.rs, authz.rs, directory_roles.rs): password hashing, login and tokens, token scopes (a read-only token is refused on every route that changes the catalog), resolving an Actor with roles, groups and maintainer scopes, and short-lived caching of directory-derived roles.
Operator use cases (admin_service.rs): delete producers, consumers and versions, deprecate versions, retention settings and cleanup of snapshots, dependencies and trunk data, user approval, webhook settings and destructive resets.
Release graphs (branch_service.rs, report_service.rs, ADR-0004/0005): create, rename and delete sanshain-branches from trunk or another branch at an instant, timelines and graph diffs, and dependency reports scoped to dev, main or a branch (JSON, Markdown, isolation).
Backstage catalog-info use case (catalog_service.rs, src/backstage.rs, ADR-0007): a build pushes its catalog-info.yaml; the Peripheral Resources its Component depends on join the graph as shared nodes and travel into release cuts and diffs, and its owner, description, source location and links are shown on the system page and node.
Publish use case (provide_service.rs, ADR-0003): accept a spec for a Producer, enforce version and stability rules, store the version line with its endpoints, promote snapshots to GA and harvest AsyncAPI subscribes.
Consume use case (require_service.rs, ADR-0003): resolve a Consumer's pin to an exact version, return just the requested endpoint or bundle, and record the dependency and trunk/branch pins it implies.
Read use cases (spec_service.rs): endpoint views, version listing, diffs, endpoint history and provide timeline, plus spec parsing and stream helpers shared with Provide and Require.
The cache is a decorator over the same port the SQL repositories implement, so the use cases never know whether a read came from memory or the database; cached data expires after 10 seconds, so a second instance sees changes without a shared cache. The backend is chosen at startup. The snapshot bypasses the port on purpose: it is a file-level copy made by the SQLite engine, not a query.
Moka-based caching decorator around the SpecRepository port (src/infrastructure/cached_repository.rs); configurable and clearable from the admin settings.
sqlx implementations of SpecRepository for SQLite and PostgreSQL plus schema migrations (src/infrastructure/sqlite_repository.rs, postgres_repository.rs, database.rs, migrations).
Consistent copy of the SQLite database made by the engine itself with VACUUM INTO (src/infrastructure/sqlite_snapshot.rs): one snapshot at a time, written to a temporary file next to the database, streamed to the caller and removed afterwards. PostgreSQL instances refuse the download and point to pg_dump.