architecture

Architecture Documentation

How Hort is built and operated: everything here describes the architecture as shipped in the crates/ workspace.

Organised along Diátaxis:

Explanation — understand the design

Start here if you want to know why the system looks the way it does.

1. Overview — goals, authority hierarchy, the shape of the system.
2. Layering and crate map — where code lives and who may depend on whom.
3. Domain model — entities, ports, actors, content hashes.
4. Event sourcing — streams, events, dual-write, projections.
5. Content-addressable storage — streaming CAS and its invariants.
6. Format handlers — capability taxonomy and what's compiled-in today.
7. Security — trust boundaries, auth, authz, defence in depth, and what operators still own.
8. The prefetch pipeline — triggers, the transitive cascade, dedup layers, and why warming never bypasses quarantine.
9. Index construction — the Source → Filter → Builder spine, the no-leak filter order, and IndexMode's bounded semantics.
10. The scanning pipeline — scanner/advisory ports, SBOM extraction, the scan-job lifecycle, and the externally-triggered rescan/advisory ticks.
11. Event notifications — subscriptions, webhook/NATS delivery, the privileged-category gate, and the best-effort delivery contract.

How-to — task-oriented recipes

Configuration and operations

• Declare configuration via $HORT_CONFIG_DIR (gitops)
• Wire secrets for proxy.secretRef:
• Tune HTTP transport timeouts
• Verify a release with cosign verify-blob
• Use hort-cli for admin operations (--admin, --expires-in)
• Install hort-cli
• Shell completions for hort-cli
• Federate k8s workload identity (preferred, no PAT at rest)
• Federate CI OIDC (GitHub Actions / GitLab) via /auth/exchange
• Rotate service-account PATs via the worker reconciler (fallback)
• Enable provenance (Sigstore/cosign) verification
• Quarantine patch-candidates and release
• Recover stranded (failed-scan) artifacts
• The curator workflow
• Third-party attribution

Format-specific

• Add a format handler
• Configure OCI pull-through with verified upstream
• Configure npm pull-through with verified upstream
• Configure PyPI pull-through with verified upstream

Deployment

• Install hort-server on Kubernetes
• Install hort-server + hort-worker on a single Linux host
• Helm chart — values reference
• Helm chart — edge overlays
• Install fully sovereign against registry.hort.rs
• Upgrade a running deployment (and ### Migration notice releases)
• Provision the two Postgres roles
• Trust internal or corporate CAs (extraCaBundle)
• Admin identity and the Dex bootstrap
• Enable admin-task CronJobs
• Split the control plane onto a dedicated listener
• Security hardening checklist

Operate

• Claim-based RBAC
• Provision a Prometheus scraper ServiceAccount for /metrics
• OCI image-pull secret / token
• Public supply-chain deployment

Operator

• IdP setup
• Upstream trust model

Reference — look up exact values

Information-oriented, exhaustive, kept in lockstep with the code.

• hort-server and hort-worker configuration — every env var and CLI subcommand/flag, with defaults, required-ness, and startup interlocks.
• The hort-server Helm chart — rendered-resource matrix, install-time schema rules, hook ordering, workload wiring, and chart-vs-binary caveats.
• Public event taxonomy — domain events external consumers may subscribe to, with payload fields, stream, and stability contract.
• npm format — entity reference — every npm registry entity as hort handles it: stored, derived, or discarded, and why; updated whenever an initiative changes an entity's class.
• Apply-time linter rows — coverage matrix — every named gitops apply-time lint row and what it rejects, the retirement trigger for each row that exists because a control is missing, and — separately — where the surfaces with no named row are actually validated.

Tutorial — learn by tracing one request

• Follow a PyPI upload end-to-end

Rendering the PlantUML diagrams

Diagrams are inline fenced code blocks tagged plantuml. Render them with any PlantUML-aware viewer (IntelliJ PlantUML plugin, VS Code PlantUML extension, plantuml CLI, or the online server).

Primary sources

When this documentation and the code disagree, the code wins — but the authoritative standing decisions live in the architecture decision records under docs/adr/. The starting point is the decision index and open-items register; each ADR names the live mechanism (code, test, or gate) that enforces it. Official protocol specifications outrank everything (see ADR 0011).