Contributing
Repository layout
The components in the repository, what language each is written in, and where each is documented.
The repository is a monorepo. Each component lives under libs/ with its own README, and a root justfile drives every development task.
Components
| Path | Language | What it is | Docs |
|---|---|---|---|
libs/plane | Python | The control plane: the HTTP API, the hub that terminates operator streams, and the reactor that derives alerts. One package, three processes, one Postgres. | Control plane, Plane configuration |
libs/operator | Go | hangar-operator, one per cluster. Syncs desired state from the hub into CRDs, renders each deployment as an NVIDIA Dynamo graph, and reports observed state. | Clusters, Operator configuration |
libs/gateway | Go | The data plane. One OpenAI-compatible hop that routes on model, terminates the agents’ tunnels, and identifies tenants. | Gateway, Gateway configuration |
libs/agent | Go | hangar-agent, one per cluster. Dials out to every gateway replica and proxies inference to the model’s frontend inside the cluster. | Agent configuration, Data plane |
libs/console | TypeScript | The web console (React, TanStack Router). Talks to the plane’s HTTP API only. | Console |
libs/cli | Go | hgr, the command line. Same API as the console, with stable JSON output and an offline --fake backend. | hgr CLI |
libs/chart/cluster-setup | Helm | Everything a cluster installs to be managed: the operator, the agent, CRDs, the NVIDIA Dynamo platform, the DCGM exporter, and optional monitoring. | Cluster setup chart, Chart values |
libs/packages/contract | Markdown, JSON | The plane-operator wire protocol, the HTTP API conventions with its generated route reference and OpenAPI schema, the device-class table, and the fixture corpus both sides test against. | Wire protocol, API conventions |
libs/packages/tunnel | Go | Both ends of the gateway-agent tunnel. Its own module because neither side owns it. | Data plane |
libs/benchmarking | Python | hgrbench. Runs four load generators against an OpenAI-compatible endpoint and reports them side by side. | hgrbench |
libs/transit | Go | hgrtransit. Measures the request path (gateway, tunnel, agent) on one host, with no GPU and no cluster. | hgrtransit |
libs/conformance | Python | hgrconform. Probes an OpenAI-compatible endpoint and diffs its behaviour against a reference provider. | hgrconform |
Top-level directories
libs/ one directory per component, each with its own README
docs/architecture/ how the system is put together, and why
docs/decisions/ architecture decision records
docs/operations/ deploying and running the system
docs/roadmap.md what is planned and not built
docs/glossary.md the terms the docs and code use
dev/ local-development scripts: seed data, the fake fleet, the kind config
compose.yml the local control plane: Postgres, migrations, api, hub
justfile every development task
scripts/ repository checks
.github/ CI workflows, issue and pull request templates, CODEOWNERS
.githooks/ pre-commit and commit-msg hooks