Code becomes architecture facts

One local librarian for every project you care about.

ArchGuardian turns repositories into project-owned architecture metadata and lets a local Librarian index, query, and reason across them through CLI and MCP. The project keeps the truth. The app builds the map.

See the model Explore commands

`.archguardian/` is canonical Git shares project facts Federation is derived CLI and MCP share one backend

Operating model

Project-owned facts. Local orchestration. Optional shared federation.

1 Project contract

1 Local librarian

2 Truth states

0 Required central services

North star

Think of it as a librarian with a shelf of project books.

Each repository owns its own architecture book. ArchGuardian catalogs the books you add, builds a federated view across them, and gives agents structured facts instead of guesses.

Why this exists

AI is speeding up implementation faster than teams can preserve architectural visibility.

Most teams do not need another generic assistant. They need a way to derive architecture from source, keep it with the project, and query it across many repositories without inventing a central platform first.

The polyrepo tax

Developers can change one repo without seeing who depends on it elsewhere. Cross-project impact remains a manual search problem.

Architecture docs decay

Handwritten docs drift quickly. The only durable source is the code and configuration that actually define the system.

General AI lacks system memory

It can generate local code, but it does not reliably know ownership, aliases, blast radius, or downstream contracts.

Core model

ArchGuardian has four layers, each with a clean boundary.

The important shift is ownership. Projects own deterministic facts. The local app owns registration, indexing, CLI, MCP, and optional reasoning. Federation is rebuilt from the project layer rather than replacing it.

Project Core

The canonical architecture data lives in the repo under `.archguardian/`.

`arch_manifest.yaml` for identity
`system.graph.json` for deterministic graph facts
optional `service_aliases.yaml`

Sentinel

The scan and refresh engine that turns source and config into validated project metadata.

extractors and signatures
evidence levels
identity candidate extraction

Librarian

The local hub that registers projects, loads their graphs, and exposes one backend for CLI and MCP.

local project registry
graph loader and index
project and federated queries

Federation

A derived view across registered projects. Local-first by default, optionally extended later with imported snapshots.

rebuildable from project facts
never the canonical source of truth
ready for agents through MCP

Workflow

Use normal Git workflows. Make architecture metadata travel with the repo.

This is the key operational advantage. Developer A scans and commits project metadata. Developer B pulls the same repository, adds it to their local Librarian, and immediately benefits from the latest committed architecture snapshot.

Add a project

The Librarian registers a local repository and checks whether `.archguardian/` data already exists.

Scan or refresh

The Sentinel scans source and config, then writes validated project-owned artifacts.

Commit the graph

The project shares its latest architecture snapshot through Git, just like any other reviewed artifact.

Federate locally

The Librarian merges all registered project graphs into a local federated index for project and cross-project queries.

Truth state A

Committed graph

The versioned baseline the team has shared through Git.

portable
reviewable
safe for CI baseline checks

Truth state B

Working graph

The latest local scan for the current checkout, including uncommitted changes.

useful for branch impact
useful before commit
must stay visible alongside committed truth

What lives in the repo

Project-owned

manifest
graph snapshot
alias map

What lives locally

Librarian-owned

project registry
index state
private settings and reasoning state

Interfaces

CLI and MCP should be two surfaces over one backend.

The command model is intentionally practical. Registry operations belong to the Librarian. Scanning updates project-owned `.archguardian/` data. Project and federated queries read through the same graph loader and index.

Local librarian registry

Add, remove, list, refresh.

These commands manage which projects the current developer has chosen to catalog locally. They do not alter ownership of project facts.

CLI: `add-project <path>` CLI: `remove-project <project_ref>` CLI: `list-projects` MCP: `add_project(path)` MCP: `remove_project(project_ref)` MCP: `list_projects()`

Project-scoped operations

Refresh and inspect one registered project.

These commands operate on project-owned data under `.archguardian/` and keep committed and working graph states available to the Librarian.

CLI: `scan <path>` CLI: `refresh-project <project_ref>` CLI: `diff <project_ref>` MCP: `get_project_graph(project_ref)` MCP: `get_project_dependencies(project_ref, service_name)` MCP: `resolve_project_identity(project_ref, alias)`

Cross-project queries

Read the derived map across all registered projects.

Federated tools should operate on the same local in-memory index whether they are called from the CLI, an editor, or an agent through MCP.

MCP: `get_federated_dependencies(service_name)` MCP: `get_impact_radius(service_name)` MCP: `search_patterns(keyword)` Output: project and cross-project graph facts

Optional reasoning

Use LLMs after structured retrieval, not before.

Reasoning should sit after graph retrieval so agents stay grounded in evidence rather than broad raw-code context.

MCP: `lint_architecture(diff, model?)` Input: diff plus graph facts Rule: evidence beats narrative

Roadmap

Pivot from PoC to product in layers, not all at once.

The implementation order matters. Stabilize the project contract first, then the local Librarian, then the Git workflow, then policy and CI, and only then optional broader federation.

Project contract

Settle `.archguardian/`, manifest support, deterministic graph output, and validation.

Local Librarian

Add project registration, graph loading, federated index, and shared backend services for CLI and MCP.

Shared Git workflow

Make committed versus working graph states visible and practical in normal team workflows.

Policy and CI

Add impact analysis, graph-aware checks, and machine-readable reporting in delivery pipelines.

Optional federation beyond one machine

Import snapshots or use a shared registry later, without changing the project contract.

Design rule

Do not make the central hub the only place where graphs live.

If the local registry disappears, ArchGuardian should still be able to rebuild from project-owned `.archguardian/` artifacts.

FAQ

Short answers for the architectural choices that matter.

Why not keep the graph only in a central service?

Because the project needs to stay portable, reviewable, and useful offline. Git sharing of deterministic project facts is a feature, not a workaround.

Is the Librarian the source of truth?

No. The Librarian is the local orchestrator over project-owned facts. Federation is derived and rebuildable.

Does this replace Copilot or Cursor?

No. It gives agents and editors a graph-backed architecture layer they do not have today.

Why keep both committed and working graphs?

Because teams need a shared baseline and developers need branch-level truth before they commit.

Do I need networked federation from day one?

No. Local-first is the default. Shared federation is an extension, not a prerequisite.

Where should LLMs fit?

After structured graph retrieval. Facts should come from the project contract and federated index first.