# danniel-jame/k4-l3b-multiagent-mcp-a2a architecture

> Architecture diagram of the GitHub repository danniel-jame/k4-l3b-multiagent-mcp-a2a, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danniel-jame/k4-l3b-multiagent-mcp-a2a
- Repository: https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a

## Overview

This is a Python starter kit for investigating e-commerce complaints through a multi-agent workflow, querying audited MCP evidence, and producing validated case outputs and a submission package. The documented investigation spans entity resolution, customer context, order/product, shipment, payment/refund, policy/source conflicts, and verification. The CLI loads cases, connects the evidence gateway, invokes the solver, and writes outputs and traces. Important limitation: `solve_case` is intentionally unimplemented, so the documented investigation stages are shown as capabilities, not as a verified agent pipeline or set of tool calls.

Main entry points: [`src/student_agent/cli.py`](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/cli.py) (CLI runner), [`src/student_agent/submission.py`](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/submission.py) (Submission packager), [`src/student_agent/contracts.py`](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/contracts.py) (Contract validator), [`src/student_agent/mcp_gateway.py`](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/mcp_gateway.py) (Evidence gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Run and cases"]
  node_cli["CLI runner<br/>[cli.py]"]
  node_settings["Settings<br/>[config.py]"]
  node_cases["Case loader<br/>[cases.py]"]
  node_casefiles["Case inputs"]
end

subgraph group_investigation["Investigation workflow"]
  node_solver["Case solver<br/>[workflow.py]"]
  node_entity["Entity resolution<br/>[workflow.py]"]
  node_customer["Customer context<br/>[workflow.py]"]
  node_orderproduct["Order and product<br/>[workflow.py]"]
  node_shipment["Shipment analysis<br/>[workflow.py]"]
  node_payment["Payment and refund<br/>[workflow.py]"]
  node_conflict["Policy and conflict<br/>[workflow.py]"]
  node_verifier["Result verification<br/>[workflow.py]"]
end

subgraph group_evidence["Evidence and trace"]
  node_gateway["Evidence gateway<br/>[mcp_gateway.py]"]
  node_contracts["Contract validator<br/>[contracts.py]"]
  node_schemas["JSON schemas"]
  node_trace["Trace writer<br/>[trace.py]"]
end

subgraph group_artifacts["Outputs and submission"]
  node_tracefile["Trace artifact"]
  node_outputfiles["Case outputs"]
  node_submission["Submission packager<br/>[submission.py]"]
  node_archive["Submission ZIP"]
end

node_user(("Operator"))
node_mcp["MCP Gateway"]

node_user -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"loads cases"| node_cases
node_cases -->|"reads"| node_casefiles
node_cli -->|"creates validator"| node_contracts
node_cli -->|"connects"| node_gateway
node_gateway -->|"discovers and calls"| node_mcp
node_gateway -->|"validates evidence"| node_contracts
node_contracts -->|"loads schemas"| node_schemas
node_cli -->|"creates writer"| node_trace
node_trace -->|"validates events"| node_contracts
node_trace -->|"appends events"| node_tracefile
node_cli -->|"invokes per case"| node_solver
node_cli -->|"validates outputs"| node_contracts
node_cli -->|"writes outputs"| node_outputfiles
node_user -->|"requests packaging"| node_submission
node_submission -->|"loads case set"| node_cases
node_submission -->|"validates artifacts"| node_contracts
node_submission -->|"reads"| node_outputfiles
node_submission -->|"reads"| node_tracefile
node_submission -->|"creates"| node_archive

click node_cli "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/cli.py"
click node_settings "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/config.py"
click node_cases "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/cases.py"
click node_casefiles "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/inputs"
click node_solver "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_entity "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_customer "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_orderproduct "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_shipment "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_payment "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_conflict "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_verifier "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py"
click node_gateway "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/mcp_gateway.py"
click node_contracts "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/contracts.py"
click node_schemas "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/contracts/schemas"
click node_trace "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/trace.py"
click node_tracefile "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/traces"
click node_outputfiles "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/outputs"
click node_submission "https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/submission.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_settings,node_cases,node_casefiles toneBlue
class node_solver,node_entity,node_customer,node_orderproduct,node_shipment,node_payment,node_conflict,node_verifier toneAmber
class node_gateway,node_contracts,node_schemas,node_trace toneMint
class node_tracefile,node_outputfiles,node_submission,node_archive toneRose
class node_user,node_mcp toneIndigo
```

## Components

### Run and cases

- [CLI runner](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/cli.py): `src/student_agent/cli.py`
- [Settings](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/config.py): `src/student_agent/config.py`
- [Case loader](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/cases.py): `src/student_agent/cases.py`
- [Case inputs](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/inputs): `inputs`

### Investigation workflow

- [Case solver](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Entity resolution](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Customer context](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Order and product](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Shipment analysis](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Payment and refund](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Policy and conflict](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`
- [Result verification](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/workflow.py): `src/student_agent/workflow.py`

### Evidence and trace

- [Evidence gateway](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/mcp_gateway.py): `src/student_agent/mcp_gateway.py`
- [Contract validator](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/contracts.py): `src/student_agent/contracts.py`
- [JSON schemas](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/contracts/schemas): `contracts/schemas`
- [Trace writer](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/trace.py): `src/student_agent/trace.py`

### Outputs and submission

- [Trace artifact](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/traces): `traces`
- [Case outputs](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/tree/main/outputs): `outputs`
- [Submission packager](https://github.com/danniel-jame/k4-l3b-multiagent-mcp-a2a/blob/main/src/student_agent/submission.py): `src/student_agent/submission.py`
- **Submission ZIP**

### Other components

- **Operator**
- **MCP Gateway**

## Connections

- Operator → CLI runner: runs commands
- CLI runner → Settings: loads settings
- CLI runner → Case loader: loads cases
- Case loader → Case inputs: reads
- CLI runner → Contract validator: creates validator
- CLI runner → Evidence gateway: connects
- Evidence gateway → MCP Gateway: discovers and calls
- Evidence gateway → Contract validator: validates evidence
- Contract validator → JSON schemas: loads schemas
- CLI runner → Trace writer: creates writer
- Trace writer → Contract validator: validates events
- Trace writer → Trace artifact: appends events
- CLI runner → Case solver: invokes per case
- CLI runner → Contract validator: validates outputs
- CLI runner → Case outputs: writes outputs
- Operator → Submission packager: requests packaging
- Submission packager → Case loader: loads case set
- Submission packager → Contract validator: validates artifacts
- Submission packager → Case outputs: reads
- Submission packager → Trace artifact: reads
- Submission packager → Submission ZIP: creates