Plumb — make architecture executable

Inspiration

Every team has architecture rules — "the UI never touches the database directly," "the domain layer has no framework imports," "no cyclic dependencies," "all DB access goes through the repository." They're the load-bearing decisions of a codebase, yet they live nowhere but in senior engineers' heads and stale wiki pages. Linters check style; type checkers check types; nothing checks architecture — so codebases erode silently, one merge request at a time. GitLab Orbit turns a codebase into a queryable graph — exactly what you need to make architecture checkable.

What it does

Plumb makes architectural rules executable and enforced. You declare invariants in a small rules file; Plumb compiles each into structural queries over the GitLab Orbit code graph, finds the exact dependency edges that break them, and reports every violation with its file:line, the rule's intent, and a concrete fix.

Five rule types: layering (ordered layers, no skips/upward edges), forbidden-import, no-cycles (dependency cycles), placement (where a capability may live), and boundary (enter a zone only through its gateway).

Two modes:

• plumb audit — a full architectural health report plus a drift metric (an erosion score over time).
• plumb check --base <ref> — reports only the violations a merge request introduces, posts them as an MR comment, and fails the pipeline. Drift prevention at the gate.

How we built it

• GitLab Orbit is the load-bearing core. Plumb queries Orbit's DuckDB code graph (gl_file, gl_imported_symbol, gl_definition, gl_edge) via orbit sql --format json, resolves imports to internal files, and builds a normalized in-memory graph. plumb explain <rule> prints the literal Orbit queries each rule runs — the integration is real, not a wrapper.
• A Rust engine — a rules DSL, selector compiler, and five evaluators running as deterministic predicates and graph algorithms (cycles via Tarjan SCC). 24 unit tests plus a gated end-to-end golden test against a live Orbit index.
• Shipped as a GitLab Duo skill, plus an AI Catalog agent and flow, each wired to the Orbit graph tools (query_graph, get_graph_schema).
• AI-native split: detection is deterministic and trustworthy; the explanation and fix are AI-native via Duo. A GitLab CI template gates merge requests live.

Challenges we ran into

• Orbit has no edge linking an import to its target file, so Plumb resolves imports itself (exact-stem-first, deterministic suffix fallback).
• Orbit's Rust indexer emits Windows-style backslash paths while the Python indexer uses forward slashes — Plumb normalizes separators so selectors compare consistently (a candidate upstream Orbit fix).

What we learned

A queryable code graph changes what's possible: rules that were tribal knowledge become a versioned, enforced, explainable artifact. The hard part of "executable architecture" isn't the rules engine — it's having a trustworthy structural representation of the code, which is exactly what Orbit provides.

What's next

• First-class import resolution for Rust/TypeScript module systems, to unlock layering & cycles on more languages.
• Orbit Remote mode: gate MRs using the full SDLC graph server-side.
• Auto-suggested starter rules inferred from a codebase's existing structure.

Built With

• clap
• duckdb
• gitlab-ci/cd
• gitlab-duo-agent-platform
• gitlab-orbit
• petgraph
• rust
• serde