Orbit Architecture Drift Detector

• 

  Before/after dependency graph — green new edges, red-ringed cycle nodes (inventory.ts ↔ pricing.ts), enlarged god function node

• 

  MAJOR DRIFT score 15.67 — metric bars showing coupling spike from 1.0 to 1.86 and fan-out jumping from 4 to 16

Inspiration

A normal git diff shows which lines changed. But it never tells you the thing that actually breaks systems — how your architecture changed. Did this commit introduce a circular dependency? A god function? Did coupling quietly spike?

What it does

Orbit Architecture Drift Detector takes two git commits, indexes each one with GitLab Orbit's code knowledge graph, diffs the two dependency graphs, and grades the structural drift:

• STABLE — no meaningful change
• MINOR DRIFT — review advised
• MAJOR DRIFT — fix before merging

It detects:

• New circular dependencies (Tarjan SCC algorithm)
• New god functions (high fan-out detection)
• Coupling and cohesion changes
• Dependency depth changes
• Refactoring suggestions (exactly which import to remove to break a cycle)

How we built it

Three access surfaces, one engine:

1. CLI — drift compare <commitA> <commitB> --repo .
2. GitLab Duo Agent — published to AI Catalog, ask in plain English inside GitLab
3. Next.js + React Flow Dashboard — visual before/after dependency graph

The engine uses GitLab Orbit (orbit index) to index each commit under an isolated HOME directory (so runs never clobber each other), stores commit-scoped graphs in DuckDB, then diffs the two graphs using set-based operations.

Challenges

Orbit indexes the current working tree — it has no commit-scope. So we built a snapshot orchestrator using git worktree to check out each commit in isolation, run Orbit under a separate HOME, then copy the resulting DuckDB graph into our project database tagged by commit SHA.

What we learned

GitLab Orbit's knowledge graph is a powerful foundation for architecture-level tooling that goes far beyond what git diff can show.

What's next

• CI/CD integration — fail pipelines on MAJOR DRIFT
• MR comment bot — post drift report automatically on every merge request
• Historical drift tracking — visualize architecture evolution over time

Built With

• duckdb
• elk.js
• gitlab-duo-agent-platform
• gitlab-orbit
• next.js
• node.js
• react-flow
• typescript
• vitest