# mizcausevic-dev/mcp-policy-lab architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/mcp-policy-lab, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/mcp-policy-lab
- Repository: https://github.com/mizcausevic-dev/mcp-policy-lab

## Overview

#### Purpose and principal workflow

MCP Policy Lab is a FastAPI control surface that scores a sample inventory of MCP servers and tools, classifies server posture as `stable`, `review`, or `contain`, and presents operator-facing summaries and review queues. The main workflow begins when an operator or API client makes an HTTP request: FastAPI routes either request a rendered HTML view or obtain policy results and return JSON. The sample inventory is loaded from a local JSON file; the sampled code does not connect to live MCP servers or persist operator decisions.

#### Components

##### HTTP entry and API
- **FastAPI routes** — `app/main.py`: Defines the application and HTML and JSON endpoints; initializes a `PolicyService` instance and delegates page rendering and API responses.

##### Operator presentation
- **HTML review surfaces** — `app/render.py`: Builds the overview, policy queue, tool matrix, audit, and API-summary pages from policy data, including operator-oriented risk and coverage displays.

##### Policy evaluation
- **Policy service** — `app/services/policy_service.py`: Loads inventory, evaluates server risk and posture, and derives dashboard summaries, server details, tool matrices, review queues, and sample payloads.

##### Inventory input
- **Sample policy inventory** — `app/data/sample_policy_data.json`: Supplies the local server and tool records used to calculate posture; this is sample input, not evidence of a live MCP connection.

##### External caller
- **Operator or API client** — `null`: External HTTP caller that initiates the documented HTML or JSON request workflow.

#### Relationships

- **Operator or API client -> FastAPI routes**: Sends an HTTP request to an application endpoint; routes are defined in `app/main.py`.
- **FastAPI routes -> HTML review surfaces**: Calls the relevant render function for HTML page requests.
- **FastAPI routes -> Policy service**: Calls service methods to fulfill JSON endpoints, including summary, catalog, detail, tool, evaluation, and sample requests.
- **HTML review surfaces -> Policy service**: Calls service methods to assemble page data; the renderer also builds its own service instance.
- **Policy service -> Sample policy inventory**: Reads and parses the JSON inventory when constructing a service instance.

#### Coverage limits

The source excerpts establish the route, rendering, evaluation, and inventory-loading flow, but do not show every renderer implementation detail. The repository documents SVG proof assets generated from service state, but the sampled asset-generation script is partial, so its complete rendering flow is not mapped here. No sampled code establishes live MCP connectivity, a database, or persistent policy state.

Main entry points: [`app/main.py`](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/main.py) (FastAPI routes), [`app/services/policy_service.py`](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/services/policy_service.py) (Policy service), [`app/render.py`](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/render.py) (HTML review surfaces), [`app/data/sample_policy_data.json`](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/data/sample_policy_data.json) (Sample policy inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http_api["HTTP entry and API"]
  node_routes["FastAPI routes<br/>FastAPI application"]
end

subgraph group_presentation["Operator presentation"]
  node_render["HTML review surfaces<br/>HTML renderer"]
end

subgraph group_policy_evaluation["Policy evaluation"]
  node_service["Policy service<br/>Policy evaluation"]
end

subgraph group_inventory_input["Inventory input"]
  node_inventory["Sample policy inventory<br/>JSON input"]
end

node_caller(("Operator or API client<br/>External caller"))

node_caller -->|"HTTP request"| node_routes
node_routes -->|"renders pages"| node_render
node_routes -->|"calls methods"| node_service
node_render -->|"calls methods"| node_service
node_service -->|"reads JSON"| node_inventory

click node_routes "https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/main.py"
click node_render "https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/render.py"
click node_service "https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/services/policy_service.py"
click node_inventory "https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/data/sample_policy_data.json"

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_routes,node_caller toneBlue
class node_render toneAmber
class node_service toneMint
class node_inventory toneRose
```

## Components

### HTTP entry and API

- [FastAPI routes](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/main.py): FastAPI application · `app/main.py`

### Operator presentation

- [HTML review surfaces](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/render.py): HTML renderer · `app/render.py`

### Policy evaluation

- [Policy service](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/services/policy_service.py): Policy evaluation · `app/services/policy_service.py`

### Inventory input

- [Sample policy inventory](https://github.com/mizcausevic-dev/mcp-policy-lab/blob/main/app/data/sample_policy_data.json): JSON input · Local sample records; not a live MCP connection. · `app/data/sample_policy_data.json`

### Other components

- **Operator or API client**: External caller

## Connections

- Operator or API client → FastAPI routes: HTTP request
- FastAPI routes → HTML review surfaces: renders pages
- FastAPI routes → Policy service: calls methods · Fulfills JSON endpoints.
- HTML review surfaces → Policy service: calls methods · Assembles page data; the renderer also creates its own service instance.
- Policy service → Sample policy inventory: reads JSON · When constructing a service instance.