Orbit Architect

Inspiration

Every engineering team eventually faces the same problem: architecture drift. Documents are written laying out clean boundaries, like "Frontend must never depend on the Database", but without enforcement, those rules slowly erode. What usually happens is that someone imports a utility, that utility happens to import a service, and that service queries the database. Suddenly, there is a transitive dependency chain coupling the frontend directly to the persistence layer.

It became clear that static documentation is inherently flawed because it is passive. As the project iterated through early ideas, from an "Architecture Guardian" to a "Self-Healing Architecture Flow", a core insight emerged: architecture documentation shouldn't just describe the system; it should act as the executable policy that enforces it.

What it does

Orbit Architect is a compiler for architecture documentation. It transforms plain-text architectural intent into executable CI/CD constraints.

Developers write their system boundaries in a standard architecture.md file. During the CI/CD pipeline, Orbit Architect compiles those natural-language rules into a strict policy schema. It then extracts the actual, real-world dependency graph of the codebase using GitLab Orbit and evaluates the code against the compiled policy using NetworkX.

If a developer introduces an import that violates the architecture, even through a deep transitive chain, Orbit Architect fails the pipeline. It automatically generates a severity-ranked Merge Request comment detailing exactly which rule was broken, maps the shortest dependency path using Mermaid visualizations, and suggests a refactor. If the architecture holds, it generates a clean, passing report.

How it was built

Orbit Architect was designed as a discrete pipeline of Python micro-tools:

1. compile_rules.py: Parses architecture.md and outputs a machine-readable rules.json containing the forbidden and allowed-set policies.
2. extract_orbit.py: Interacts with the GitLab Orbit CLI. Orbit indexes the repository and resolves the Abstract Syntax Tree (AST). Orbit's DuckDB-backed graph database is then queried to dump the raw graph into edges.csv.
3. evaluate_graph.py: Loads the edges into NetworkX. The graph is traversed to find direct and transitive violations, outputting the findings to violation_report.json.
4. remediate_agent.py: Consumes the violation data to construct the final mr_comment.md, utilizing Markdown and Mermaid.js for visual debugging.

A critical design decision was building on top of GitLab Orbit rather than creating a custom parser. Orbit already understands repository structure at the AST level and exposes relationships between files, symbols, and definitions. That allowed the project to focus on architectural governance instead of spending time building code intelligence infrastructure. Orbit provides the structural truth of the repository; Orbit Architect turns that truth into enforceable policy. By querying its underlying database, precise AST-level relationships are extracted, mapping exactly how files and symbols interact across the repository.

Challenges faced

The biggest technical hurdle was handling repository scoping within Orbit's database. During early network evaluations, impossible dependency edges began appearing: files depending on modules that simply didn't exist in the target application.

The initial assumption was that the extraction query contained a bug or that the graph had been incorrectly scoped. Instead of writing it off, an investigation into the underlying DuckDB-backed graph database was conducted. By manually inspecting the metadata tables and tracing project IDs, it was proven that the ghost edges were actually bleeding over from a completely different repository that had been indexed earlier in the week.

This forced the implementation of explicit repository path scoping in the SQL extraction queries. It was a frustrating bug, but diving into Orbit's internal table structures provided a much deeper understanding of how it models Directory → CONTAINS → File and File → IMPORTS → ImportedSymbol relationships.

What was learned

Treating architecture as an enforced graph problem proved to be incredibly powerful. Building on top of GitLab Orbit allowed the project to skip the notoriously difficult work of writing custom AST parsers and get straight to the higher-level logic of architectural policy. It also provided a crash course in NetworkX, specifically optimizing pathfinding algorithms to return the shortest, most readable violation chains rather than dumping raw graph data on the developer.

Accomplishments to be proud of

There is immense pride in building a tool that actually feels like it belongs in an enterprise CI/CD pipeline. This isn't simply checking imports against hardcoded rules. Orbit Architect compiles architectural intent into executable graph constraints and continuously evaluates those constraints against the repository structure extracted by Orbit. Both failure and recovery scenarios were successfully demonstrated. A repository containing architectural violations produced severity-ranked reports, Mermaid dependency graphs, and remediation guidance. After correcting the violating dependencies, the same repository passed validation and received a clean approval report.

What's next for Orbit Architect

Right now, Orbit Architect enforces dependency boundaries based on file paths and directory structures. Next, the compiler will be expanded to understand deeper semantic rules, such as enforcing specific design patterns (e.g., ensuring all classes in a repositories folder implement a specific interface). There are also plans to wrap the pipeline into a native GitLab CI Component for one-click integration into any repository. Ultimately, the goal is to make architecture documentation something teams can trust because it is continuously validated, not simply written and forgotten.

Note to Judges : I built the full working project, but I made a mistake and built it in my personal GitLab workspace instead of the provisioned Contributors Platform workspace. Because of this, my workspace was missing the Ultimate license needed to physically push the button to the AI Catalog UI. However, the complete AI Catalog Configuration-as-Code is provided in agents/agent.yml in my repository, and the Orbit pipeline integration works perfectly as shown in the video demo

Built With

• duckdb
• gitlab
• json
• mermaid
• networkx
• orbit
• python
• sql
• ubuntu
• wsl2