Architecture Intelligence Platform README

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. Four real coding-agent clients were qualified end to end against v0.4.2 — see the v0.4.2 compatibility matrix. That qualification has not been repeated since.

Run the 5-Minute Demo · Realistic Demo: Quarkus Super Heroes · MCP Tools · How It Works

MCP Registry: io.github.michaelegner/architecture-intelligence-platform

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 request path a compatible MCP client would take.

Asking get_architecture_drift about order-service returns two findings:

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.

{
  "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"]
    }
  ]
}

[
  {
    "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"
  }
]

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.

Quarkus Super Heroes: understand the fight service before changing it

The five-minute demo uses a small synthetic landscape. This one uses a real multi-service system, Quarkus Super Heroes, from AIP's v0.5.0 real-system qualification. The task: before changing image narration in rest-fights, what do I need to know? One command replays the already-qualified evidence. It needs Docker and curl; no Quarkus build, Kafka, cluster or model key:

examples/quarkus-super-heroes-demo/run.sh

The answer for rest-fights shows seven operation-level CALLS, three CONFIRMED at runtime and four NOT_OBSERVED_IN_WINDOW, and a DEPLOYED_AS resolved through a configured mapping. It also shows a PUBLISHES_TO Topic fights, declared by a disclosed operator-authored AsyncAPI overlay. Its consumer stays an explicit UNRESOLVED_IDENTITY rather than a guess. The gRPC call AIP cannot answer yet is labelled as outside the answer, not hidden.

Demo README · question-by-question walkthrough · where dependencies are established · recorded Claude Code conversation

Pitstop: which services receive the event you are about to change?

Try locally → · Try hosted →

A second real system, Pitstop (a .NET garage-management sample on RabbitMQ), on a different broker and stack. The task: before replacing StartTime and EndTime in MaintenanceJobFinished, who receives from the exchange it is published to, and what must I still inspect? One command replays an authored, frozen observation window. It needs Docker and curl; no .NET, RabbitMQ or model key:

examples/pitstop-demo/run.sh

Ask the publisher: AIP resolves five receivers of the fanout exchange through their named queues, one of which (ReportingService) no Pitstop document lists, with their evidence and the publisher's qualification. It states, rather than hides, that it holds no payload or field-level knowledge, so which receiver reads StartTime is what you must still inspect. The local replay is the reproducible mode. The canonical demo is a continuously running, instrumented Pitstop feeding a hosted AIP instance, queried for a completed UTC day (the local --live mode needs the private instrumented fork; the hosted demo exposes only its public read-only MCP endpoint and requires no credentials). An optional Claude Code plugin (and an optional mod that shows AIP's answer next to the agent's plan) is described in the demo README; both install from this repository's Claude Code marketplace (claude plugin marketplace add michaelegner/architecture-intelligence-platform).

Demo README · question-by-question walkthrough · input provenance

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. Five read-only MCP tools hand an agent direct dependencies, drift, provenance, caller locality and API consumer usage, each 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. They were qualified against v0.4.2 and have not been re-qualified since. 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

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

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

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; 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 through standard negotiated MCP client initialization (see Boundaries) as exactly five read-only tools:

All five 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 evidence that produced it, so declared and observed signals stay distinguishable instead of collapsing into one undifferentiated "truth".

Declared vs observed

Every relation in the graph carries evidence, and its evidence can be DECLARED (from a spec/ manifest), OBSERVED (from real telemetry), or both. That's what turns into a status:

Removing a stale declaration never deletes a relation that still has observed evidence — it degrades CONFIRMED to OBSERVED_ONLY instead. See docs/graph-model.md for the exact invariant this guarantees and why it matters. The dependency and drift MCP tools above return exactly these qualifications; nothing is upgraded or smoothed over on the way out.

Ingestion

A modular Python monolith (a single FastAPI process); Neo4j is the only external persistent dependency. Ingestion is a strictly staged pipeline — scan -> parse -> source-validate -> map to canonical model -> canonical-validate -> reconcile/diff -> transactional graph write — where a service's import either fully succeeds or is entirely discarded, never left partial. Source adapters never write to Neo4j directly; they all map into one shared Canonical Model first. Full details, including the graph/evidence model and every API route: docs/architecture.md.

Deterministic analyses

Five fixed, parameterized Cypher analyses over declared architecture (queue senders/consumers, orphan queues, mixed-architecture blast radius) plus five over declared-vs-observed runtime data (what was actually observed, what's confirmed, what's observed-only, what's declared-only, and per-service telemetry coverage). None of these involve the LLM — see docs/analyses.md for the full list and what each one answers.

Core Capabilities

• Evidence-qualified service dependencies and architecture drift, via five read-only MCP tools
• OpenAPI, AsyncAPI and OpenTelemetry evidence, reconciled into one graph
• Queue and source-independent Pub/Sub semantics. Topic fan-out is expressed only through explicitly declared Subscriptions, and a Kafka consumer group is never treated as a Subscription.
• Snapshot-bound provenance — every claim traces back to the spec file, manifest, or observation window that produced it
• Deterministic declared-vs-observed reconciliation, with cross-batch OTel correlation
• Conservative handling of missing evidence and unresolved identity — never guessed, never silently dropped
• Neo4j-backed architecture model with an optional Service Explorer UI

See the architecture and capability documentation → · Correlation modes →

Example

The bundled examples/ fixture is a small, fully synthetic four-service landscape:

unused-q (a sender with no consumer) and unknown-producer-q (a consumer with no known sender) are included specifically to exercise the orphan-queue analyses. POST /api/import loads all of it in one call.

Evaluation

AIP is evaluated against independently authored ground truth — never against expectations generated from AIP's own output — with deterministic PASS/FAIL:

• 10 deterministic scenarios over declared/observed relation facts
• 23 ArchitectureAnswer scenarios across all three MCP tools
• Two clean ArchitectureAnswer runs are semantically identical; the hero demo's structuredContent is byte-identical across repeated clean runs
• Real-system validation against Quarkus Super Heroes and Apache Airflow

uv run python -m evaluation run       # ten relation-fact scenarios
uv run python -m evaluation answers   # 23 ArchitectureAnswer scenarios

No LLM provider key is required — neither suite touches the natural-language query layer. See evaluation/README.md for the full scenario lists, ground-truth formats, and failure-report examples.

Tested against real systems

AIP's model was also challenged against two systems it wasn't designed for: Quarkus Super Heroes and Apache Airflow. The important result wasn't that AIP "discovered everything" — it was that unsupported and unresolved cases stayed explicit instead of being converted into plausible architecture facts. See docs/real-world-validation/README.md for the ground-truth independence rule, dossier structure, and per-system findings. To explore the Quarkus system yourself, run the Quarkus Super Heroes demo.

Runtime Evidence with OpenTelemetry

AIP consumes OTLP traces as an additional telemetry consumer, not a replacement for your observability backend. It must never be the only thing an OTel Collector forwards to, and its own availability must never affect an application's normal observability:

The bundled runtime demo generates continuous synthetic traffic and shows CONFIRMED, OBSERVED_ONLY and NOT_OBSERVED_IN_WINDOW relationships fill in live, in both the API and the Service Explorer:

OpenTelemetry integration → · Runtime demo walkthrough →

Optional human query interface

POST /api/query also answers plain-language questions for interactive exploration — routed to an existing deterministic analysis where possible, or otherwise answered with LLM-generated Cypher that must pass a strict read-only allowlist validator before it ever touches Neo4j. The LLM never holds write credentials and its Cypher is always shown back for traceability. Entirely optional — the platform works with no LLM provider configured, and no MCP tool depends on it. See docs/semantic-validation.md.

Boundaries

What the MCP tools return, and what they deliberately don't. The original three tools share the ArchitectureAnswer envelope below; the fourth adds the separately versioned locality contract and the fifth the separately versioned API consumer usage contract.

One envelope. The original three tools return the same ArchitectureAnswer (schema_version, producer, tool, outcome, snapshot, observation_context, data, claims, evidence_refs, limitations), validated against a closed, published JSON Schema. Dependency and drift answers populate claims/evidence_refs, while get_evidence resolves evidence records into data and intentionally leaves those top-level arrays empty.

Current state, not history. Every answer is bound to one stable graph snapshot identity — a fingerprint of the current graph state, so two related answers can be proven to refer to the same identified graph state. There is no historical or point-in-time query surface, and a snapshot_id that is no longer the current one is refused with a SNAPSHOT_NOT_AVAILABLE limitation rather than answered from stale data.

Explicit observation context. The runtime-sensitive dependency and drift tools carry an environment and time window on every answer, while get_evidence is intentionally observation-context-free and requires an explicit snapshot_id.

Direct dependencies only. One hop — no transitive traversal, and no generic Cypher or graph query surface behind the tools.

Declared Pub/Sub only. Topics and Subscriptions come only from declared AsyncAPI (or configured mappings). Runtime telemetry can confirm them but never invents them, and AIP has no live broker discovery for Kafka, Azure Service Bus, Google Pub/Sub or RabbitMQ (see docs/ingestion.md).

One path, one connection mode. /mcp serves standard negotiated MCP only (see docs/mcp.md); the v0.4.x direct envelope is retired, and a request that is not valid negotiated MCP traffic is rejected.

Local or trusted network. As with the rest of AIP, /mcp is built for a local or trusted-network posture; it is not hardened for direct public-internet exposure — see docs/security-model.md.

Documentation

• docs/mcp.md — the five read-only MCP tools for AI agents, and a runnable hero-demo walkthrough
• docs/architecture.md — pipeline, API surface
• docs/canonical-model.md — entities and deterministic ids
• docs/graph-model.md — relations, fact/evidence invariants, observed PROVIDES
• docs/evidence.md — provenance, the Evidence node, correlation modes
• docs/ingestion.md — the three declared source adapters
• docs/analyses.md — A1-A5 and O1-O5
• docs/semantic-validation.md — the NL query pipeline
• — runtime observation, attribute allowlist, coverage

Contributing

See CONTRIBUTING.md for development setup, test/lint/format commands, and the adapter contribution guide. Questions and ideas go in Discussions; bugs and feature requests use the issue templates. Security vulnerabilities should never be reported as public issues — see SECURITY.md. This project follows the Contributor Covenant.

Project Status

Latest release: v0.7.0 — API-Aware Current State.

Pre-1.0: the REST/MCP surface, Graph Schema, Canonical Model, Adapter SPI and configuration format may still change on a minor version bump. Every release ships a published-artifact verification — docs/release-validation/v0.7.0-post-release-verification.md is the most recent. See CHANGELOG.md for what shipped in each release and ROADMAP.md for what's next.

License

Licensed under the Apache License, Version 2.0. See LICENSE. Third-party dependency licenses: THIRD_PARTY_LICENSES.md.