architecture-intelligence-platform

# Architecture Intelligence Platform

[![CI](https://github.com/michaelegner/architecture-intelligence-platform/actions/workflows/ci.yml/badge.svg)](https://github.com/michaelegner/architecture-intelligence-platform/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)

## 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](docs/release-validation/v0.4.2-client-qualification.md). That
qualification has not been repeated since.

**[Run the 5-Minute Demo](#see-it-in-five-minutes) · [Realistic Demo: Quarkus Super Heroes](#quarkus-super-heroes-understand-the-fight-service-before-changing-it) · [MCP Tools](#mcp-tools) · [How It Works](#how-aip-works)**

**MCP Registry:** [`io.github.michaelegner/architecture-intelligence-platform`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.michaelegner/architecture-intelligence-platform)

![Architecture Intelligence Platform demo: get_architecture_drift finds an undocumented LegacyPricingService dependency, then get_evidence traces it to the real OpenTelemetry observation that proves it — both real MCP tool calls, no mockups.](video/readme-demo/output/aip-readme-demo.webp)

**`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](https://www.linkedin.com/feed/update/urn:li:activity:7503338966553882625/) ·
[Evaluation](#evaluation) · [Boundaries](#boundaries) · [Documentation](#documentation) ·
[Research Landscape](docs/landscape.md)**

## See It in Five Minutes

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

```bash
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:

```json
{
  "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:

```json
[
  {
    "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`](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](https://github.com/quarkusio/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:

```bash
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](examples/quarkus-super-heroes-demo/README.md) ·
[question-by-question walkthrough](examples/quarkus-super-heroes-demo/walkthrough.md) ·
[where dependencies are established](docs/real-world-validation/v0.6.0/locality-walkthrough.md) ·
[recorded Claude Code conversation](examples/quarkus-super-heroes-demo/conversation-claude-code.md)

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

A second real system, [Pitstop](https://github.com/EdwinVW/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:

```bash
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 instance is operated by the demo owner and
reached over a token-gated MCP URL). 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](examples/pitstop-demo/README.md) ·
[question-by-question walkthrough](examples/pitstop-demo/walkthrough.md) ·
[input provenance](examples/pitstop-demo/PROVENANCE.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:

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

AIP is now available at `http://localhost:8000/mcp`. Configure a coding-agent