Architecture Decision Records¶

ADR-001: Self-Hosted Kroki¶

Status: Accepted · Date: 2026-08-01

Context¶

The archlint platform needs to render 25+ diagram types (PlantUML, Mermaid, D2, Graphviz, Structurizr, C4-PlantUML, and more). The public Kroki instance at kroki.io was used initially but proved unreliable: - Rate limiting caused render failures under load - Mermaid support was broken on the public instance - ~300ms latency per render (external network call) - No control over availability or version

Decision¶

Deploy a local Kroki instance as a K8s pod in the hermes namespace. All diagram rendering goes through the local instance at kroki.hermes.svc.cluster.local:8000.

Consequences¶

Positive: No rate limiting. Mermaid, BPMN, D2 all functional. ~50ms rendering latency. Full control over version and configuration.
Negative: Kroki pod requires 5 containers (core + mermaid + bpmn + excalidraw + blockdiag) and ~2GB memory. Adds operational complexity.
Neutral: 3 diagram types (bytefield, bpmn, symbolator) remain broken — confirmed as upstream Kroki bugs, not our deployment.

ADR-002: Single Namespace Consolidation¶

Status: Accepted · Date: 2026-08-01

Context¶

Services were initially split across two K8s namespaces: archlint (application services) and hermes (AI agent's namespace). This required cross-namespace DNS (archlint-site.archlint.svc) and separate RBAC configurations.

Decision¶

Consolidate all archlint services into the hermes namespace. The Hermes agent now has full write access to all services. Old archlint namespace deleted.

Consequences¶

Positive: Simplified DNS (same namespace). Hermes agent can manage everything. Single ServiceAccount for RBAC.
Negative: Less isolation between AI agent and application services.
Neutral: Cloudflare tunnel ingress updated to point to archlint-site.hermes.svc.cluster.local.

ADR-003: Axum-Based Reverse Proxy¶

Status: Accepted · Date: 2026-08-01

Context¶

The platform needed to serve multiple web UIs (MkDocs, Slidev, Excalidraw) under a single domain archlint.dev. Options considered: 1. Kubernetes Ingress (requires LoadBalancer or NodePort — not available with Cloudflare tunnel) 2. Nginx sidecar (adds complexity, another process to manage) 3. Reverse proxy built into the Rust backend (already running, minimal overhead)

Decision¶

Add reverse proxy routes in the existing Rust/Axum archlint-site backend. Each sub-service gets a path prefix (/docs, /slides, /whiteboard, /reports) proxied to the respective K8s Service.

Consequences¶

Positive: Single binary handles everything. No additional process. Sub-millisecond proxy overhead. Works with Cloudflare tunnel.
Negative: Rust binary now has proxy responsibilities. Proxy code must handle streaming, headers, and error cases.
Neutral: 50 lines of Rust added. reqwest client already available for Kroki rendering.

ADR-004: MkDocs + Kroki Plugin for Documentation¶

Status: Proposed · Date: 2026-08-01

Context¶

The MkDocs documentation site needs to show rendered architecture diagrams, not just code blocks. Three approaches considered: 1. Pre-render all diagrams as SVG files and embed as <img> tags (stale, requires manual rebuild) 2. Use Mermaid.js client-side rendering (limited to Mermaid only, not PlantUML/D2/etc.) 3. Write a custom MkDocs plugin that calls the local Kroki instance at build time

Decision¶

Build mkdocs-kroki, a custom MkDocs plugin that intercepts ```kroki type=X code blocks and replaces them with rendered SVG images (base64-encoded data URIs). The plugin calls the local Kroki instance at build time.

Consequences¶

Positive: All 25+ diagram types available in docs. Diagrams are baked into the static HTML (no runtime dependency). Rebuild picks up diagram changes.
Negative: Build-time rendering means docs build is slower. Kroki must be available during build.
Alternative considered: mdbook-kroki (pre-existing plugin for mdBook). Rejected because MkDocs Material has superior UX (search, dark mode, navigation tabs).

ADR-005: Project-Centric Data Model¶

Status: Proposed · Date: 2026-08-01

Context¶

The platform's persistent data (diagrams, ADRs, stakeholders) needs a schema that supports the full architect workflow: whiteboard sketches → formal diagrams → ADRs → published docs.

Decision¶

Use PostgreSQL (already running) with a project-centric schema. Each project owns its diagrams, ADRs, stakeholders, and constraints. An artefact_links table connects related items (e.g., whiteboard session → diagram, diagram → ADR).

Consequences¶

Positive: All data in one place. Foreign keys enforce integrity. JSONB for flexible fields (Excalidraw state). Full-text search for ADRs.
Negative: Schema complexity. Migration management needed.
Neutral: Reuses existing PostgreSQL instance. Builds on uuid primary keys for portability.