Inspiration

AI agents can now generate a whole application — frontend, backend, database, tests — in minutes. Generation is no longer the bottleneck; understanding what was generated is. Six months later a developer opens a 1,200-line pricing_engine.py and nobody knows why it exists, whether it's safe to change, or who understands it. Today's tools check bugs, security, and formatting — almost nothing checks maintainability for the next human. As AI writes more code, that gap becomes one of the biggest software-engineering problems of the era. We built Atlas to close it.

What it does

Atlas treats long-term maintainability as a first-class, measurable signal. It runs a four-stage loop — Detect → Explain → Recommend → Act — over any repository indexed by GitLab Orbit, across five capabilities:

Architecture Guardian — detects layer violations (e.g. a presentation file importing the datastore directly) and circular dependencies using Tarjan's strongly-connected-components algorithm on Orbit's import graph. Knowledge Guardian — computes bus factor and ownership concentration from git history. Documentation Guardian — scores undocumented functions and modules. Remediation Agent — opens GitLab issues for each risk, and an actual merge request with safe fixes (module docstrings, a CODEOWNERS file, and auto-generated onboarding guides), assigning a reviewer. Executive Dashboard — a self-contained HTML health dashboard with a score gauge and per-file risk bars. It also computes Robert Martin's instability metric I = Ce/(Ca+Ce) per file to find fragile hubs.

How we built it

A Python engine (standard library only) that queries the GitLab Orbit Knowledge Graph via glab orbit remote query. Orbit Definition nodes give every function's line span and type → complexity with zero parsing. Orbit IMPORTS edges give the dependency graph → we run real graph algorithms on it (cycle detection, instability, layering rules). Git history provides authorship for bus-factor analysis. Findings flow into a GitLab Duo custom flow (published to the AI Catalog, MIT) where Duo's LLM does the Explain/Recommend reasoning, and into GitLab issues/MRs for the Act step. A .gitlab-ci.yml runs Atlas in-pipeline and comments the report on merge requests; a pyproject.toml exposes a one-command atlas CLI. 44 unit + integration tests. How we use GitLab Orbit (core to the project) Atlas does not parse source code itself — Orbit is the source of truth for code structure. We query Orbit's Knowledge Graph for Definition line spans and types (complexity), and traverse File -[IMPORTS]-> ImportedSymbol -[IMPORTS]-> Definition to reconstruct the file dependency graph, on which we run cycle detection and coupling/instability analysis. Most Orbit demos build code search; Atlas shows Orbit can power code sustainability — a new capability for the graph.

Challenges we ran into

Orbit is experimental; the File.path filter behaved differently from Definition.file_path, so we adapted our queries to the fields that worked. The AI Catalog flow schema differed from the docs — we iterated against the GraphQL aiCatalogFlowCreate validation (singular toolset, dict prompt_template, required routers, flow.entry_point) to publish a valid, released flow. Designing a remediation MR that is always safe (docs + ownership only, never logic) so it can be opened autonomously.

Accomplishments we're proud of

A genuinely novel use of Orbit (sustainability, not search). A full autonomous loop that doesn't just report — it opens real issues and a real merge request. Real graph algorithms (Tarjan SCC + Martin instability) on live Orbit data. Published, public, MIT-licensed flow in the AI Catalog. What we learned That the Orbit Knowledge Graph is a powerful substrate for reasoning about code, not just retrieving it — and that "is this code sustainable for the next human?" is a question you can actually answer with a graph + git + an LLM.

What's next

Auto-generate architecture diagrams from the Orbit IMPORTS/CALLS graph. Open remediation MRs that safely split complexity hotspots, not just add docs. Track repository health over time and alert on regressions. Extend beyond Python using Orbit's language-agnostic graph.

Built With

• gitlab-ai-catalog
• gitlab-duo-agent-platform
• gitlab-orbit
• glab
• graph-algorithms
• maintainable
• python
• tarjan-scc