Architecture Intelligence Platform

Agents should reason about architecture — not reconstruct it.

AIP gives coding agents evidence-qualified architecture context.

It reconciles declared API contracts with observed runtime behavior so an agent can distinguish:

• dependencies that are declared and observed;
• dependencies seen in production but documented nowhere;
• declared relationships not observed in the selected runtime window;
• facts AIP cannot safely establish.

Every answer is snapshot-bound and traceable to evidence. The agent-facing tools are read-only, qualified end to end against four real coding-agent clients — see the compatibility matrix.

Run the 5-Minute Demo · MCP Tools · How It Works

LegacyPricingService was never declared. AIP observed the dependency at runtime as OBSERVED_ONLY and traces the claim back to its OpenTelemetry evidence.

⭐ Star AIP if evidence-qualified architecture context for coding agents is a problem you want solved.

Video Walkthrough · Evaluation · Boundaries · Documentation · Research Landscape

See It in Five Minutes

Requires Docker (with Compose), curl and jq. No LLM API key — nothing on this path calls a model:

git clone https://github.com/michaelegner/architecture-intelligence-platform.git
cd architecture-intelligence-platform
cp .env.example .env
examples/runtime-demo/mcp-demo.sh

The script starts AIP + Neo4j + an OTel Collector, imports the bundled example architecture, seeds one timestamp-frozen batch of runtime telemetry, then drives tools/list → get_architecture_drift → get_evidence over plain HTTP/JSON-RPC — the same direct 2026-07-28 request path a compatible MCP client would take.

Asking get_architecture_drift about order-service returns two findings:

| Dependency | Qualification | What it means | |---|---|---| | LegacyPricingService | OBSERVED_ONLY | A runtime dependency observed in the seeded telemetry that nothing declares | | unused-q | NOT_OBSERVED_IN_WINDOW | Declared in asyncapi.yaml, not seen in this window — deliberately not reported as "unused" or "dead" |

ProductService and PaymentService (via payment-q) are CONFIRMED — declared and observed — and correctly don't appear at all: drift returns discrepancies, never matches. get_service_dependencies is the tool that lists all four. Alongside the two claims the answer carries a limitations entry: AIP declining to name a consumer for unused-q that it cannot evidence. Each claim's evidence_refs then resolve through get_evidence, at the same snapshot_id, to the asyncapi.yaml that declared one and the OpenTelemetry window that observed the other.

<details> <summary><b>The full JSON both calls return</b></summary>

get_architecture_drift for order-service, exactly as the demo prints it — its jq flattens snapshot.snapshot_id and keeps the fields that matter here, rather than showing the full envelope:

{
  "snapshot_id": "aip:snapshot:v1:685a34157b6842b00d7130b8490df63060c3d80871c2ed6f56cd9206e62342d8",
  "outcome": "PARTIAL",
  "limitations": [
    {
      "code": "UNRESOLVED_IDENTITY",
      "message": "queue:unused-q has no single evidenced consumer service; retained as the direct queue target rather than guessed.",
      "claim_ids": ["aip:claim:v1:ca0dd73ba391552edd6d2cc06cddd919a8af97f362cdb47392e78325219fd612"]
    }
  ],
  "claims": [
    {
      "dependency": "unused-q",
      "via": "unused-q",
      "qualification": "NOT_OBSERVED_IN_WINDOW",
      "evidence_refs": ["evidence:asyncapi:order-service"]
    },
    {
      "dependency": "LegacyPricingService",
      "via": "GET /pricing/{sku}",
      "qualification": "OBSERVED_ONLY",
      "evidence_refs": ["evidence:otel:demo:2026-08-26:bfae54276215"]
    }
  ]
}

Feeding those evidence_refs back into get_evidence at the same snapshot_id returns the provenance behind each claim:

[
  {
    "id": "evidence:asyncapi:order-service",
    "evidence_type": "DECLARED",
    "source_type": "ASYNCAPI",
    "source_locator": "examples/order-service/asyncapi.yaml"
  },
  {
    "id": "evidence:otel:demo:2026-08-26:bfae54276215",
    "evidence_type": "OBSERVED",
    "source_type": "OPENTELEMETRY",
    "source_locator": "opentelemetry"
  }
]

</details>

Because every seeded span is frozen rather than clock-derived, two clean runs produce the same qualifications and the same snapshot_id. Run examples/runtime-demo/mcp-demo.sh --down to tear it back down. For the step-by-step version — every curl spelled out, with what each answer means — see examples/runtime-demo/hero-demo.md.

What You Can Do With It

Find dependencies nobody wrote down. Real traffic reveals calls that exist in no spec, manifest or diagram. AIP surfaces them as OBSERVED_ONLY, with the observation window that saw them — OrderService -> LegacyPricingService in the demo above.

Check whether the architecture you declared is the one that's running. Drift is reported per dependency and in both directions — declared but not observed, observed but never declared — each qualified rather than asserted.

Give a coding agent context it can cite. Three read-only MCP tools hand an agent direct dependencies, drift and provenance bound to one graph snapshot, so it can tell a fact from a guess — and so it can never write to the model it is reading from.

Connect AIP to Your Coding Agent

Prepare the deterministic demo without running the scripted MCP calls yourself:

examples/runtime-demo/mcp-demo.sh --serve

AIP is now available at http://localhost:8000/mcp. Configure a coding-agent client using the examples below — configuration syntax is verified against each client's current official docs.

Qualified client/platform combinations are listed in the v0.4.2 compatibility matrix. Other combinations are unverified unless listed.

Codex CLI

codex mcp add aip --url http://localhost:8000/mcp

Claude Code

claude mcp add --transport http --scope local aip http://localhost:8000/mcp

<details> <summary>Cursor / VS Code</summary>

Cursor — .cursor/mcp.json:

{ "mcpServers": { "aip": { "url": "http://localhost:8000/mcp" } } }

VS Code — .vscode/mcp.json:

{ "servers": { "aip": { "type": "http", "url": "http://localhost:8000/mcp" } } }

</details>

Then ask:

Use AIP to find architecture drift for service:order-service in the demo environment between 2026-08-26T00:00:00Z and 2026-08-27T00:00:00Z. For every finding, explain its qualification and resolve its evidence using the same snapshot. Do not infer facts AIP does not establish.

Expected AIP findings:

• LegacyPricingService — OBSERVED_ONLY (observed at runtime, never declared)
• unused-q — NOT_OBSERVED_IN_WINDOW (declared, not seen in this window — never "unused" or "dead")

Here's Codex CLI doing exactly that, live:

These instructions target locally running clients — a hosted/cloud agent usually can't reach your localhost. /mcp has no public-internet authentication in v0.4.2; keep it local or on a trusted network. AIP itself needs no LLM API key for this path; your client may still need its own.

Detailed per-client setup, verification sources, and cleanup instructions →

Why?

An agent changing a service needs to know what that service actually talks to. Today it often gets that from two problematic sources: architecture documentation that may have drifted from reality, and plausible inference from whatever code happened to fit in the context window. Both sound equally confident, and neither lets the agent tell a fact from a guess.

AIP answers that question from evidence that already exists and is already maintained as part of normal development — OpenAPI/AsyncAPI specs, a minimal manifest for the one thing they can't express (who calls what), and, optionally, real OpenTelemetry traffic. Dependency and drift answers state which evidence supports each claim, whether runtime observation agrees with what was declared, and what AIP could not establish: a dependency that was never observed is reported as not observed, never as absent, and an unresolved identity is never guessed. Evidence drill-down resolves those evidence references at the same snapshot without creating new architecture claims.

AIP may help agents reason about architecture, but an agent must never become the source of architectural truth. — ROADMAP.md's v0.4 principle

MCP Tools

AIP exposes the validated architecture model at /mcp — via either the direct 2026-07-28 envelope or standard negotiated MCP client initialization (see Boundaries) — as exactly three read-only tools:

| Tool | Answers | |---|---| | get_service_dependencies | What does this service directly depend on, and is each dependency confirmed by runtime observation? | | get_architecture_drift | Which of those direct dependencies disagree with what was declared — observed but undocumented, or declared but not observed in this window? | | get_evidence | What is the actual provenance behind those claims — which spec file, manifest, or observation window? |

All three perform zero graph writes and need no LLM API key — the whole surface is deterministic — and none of them will invent, guess, or upgrade an unresolved fact: insufficient evidence comes back as a limitations entry, never as silence.

What each answer contains, what it is bound to, and what the surface deliberately does not do: Boundaries below. Full reference, including the exact JSON-RPC call shape: docs/mcp.md.

Quick Start

To run the whole platform (REST API, Service Explorer, MCP endpoint) rather than just the demo:

cp .env.example .env
docker compose up

.env.example's NEO4J_PASSWORD is a fixed local-only default (change-me-local) — fine for trying this out, never for anything reachable outside your machine.

Then open http://localhost:8000. config.yaml already points at this repo's examples/ fixture services, so POST /api/import works immediately against them. See docs/development.md for running locally without Docker, the test suite, and linting.

How AIP Works

Evidence in, qualified architecture facts out:

OpenAPI · AsyncAPI · architecture.yaml   (declared)
OpenTelemetry traces                     (observed)
        -> canonical model -> evidence-backed graph -> qualified claims -> MCP tools / REST / UI

Hand-maintained architecture documentation drifts because nothing forces it to agree with the system. AIP never stores an architecture fact without the evide