# guhanavish/mirrormap architecture

> Architecture diagram of the GitHub repository guhanavish/mirrormap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/guhanavish/mirrormap
- Repository: https://github.com/guhanavish/mirrormap

## Overview

MirrorMap is a read-only project intelligence and spec-drift auditing tool. Its main workflow takes requirements, a repository inventory, and optional reviewed verification evidence; it compares those inputs, classifies findings, and produces reports and a human-review remediation plan. The offline atlas presents the results, while JUnit import, route discovery, agent-skill access, and MCP provide distinct supporting capabilities. The sampled source shows key module references; other capability links rely on the README, and unsampled internals are not inferred.

Main entry points: [`projectmirror/experience.py`](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/experience.py) (Audit Workflow), [`projectmirror/core.py`](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py) (Evidence Comparison), [`projectmirror/evidence.py`](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/evidence.py) (Test Observations), [`references/data-model.md`](https://github.com/guhanavish/mirrormap/blob/main/references/data-model.md) (Approved Requirements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Audit Inputs"]
  node_requirements["Approved Requirements<br/>[data-model.md]"]
  node_target["Target Repository"]
  node_observations["Test Observations<br/>[evidence.py]"]
end

subgraph group_engine["Audit Engine"]
  node_audit["Audit Workflow<br/>[experience.py]"]
  node_inventory["Source Inventory<br/>[core.py]"]
  node_route_discovery["Route Candidates<br/>[frameworks.py]"]
  node_comparison["Evidence Comparison<br/>[core.py]"]
  node_planning["Review-Only Plan<br/>[core.py]"]
end

subgraph group_results["Results and Evidence"]
  node_junit["JUnit Import<br/>[evidence.py]"]
  node_reports["Audit Reports<br/>[experience.py]"]
  node_atlas["Interactive Atlas<br/>[dashboard.py]"]
end

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI Entry<br/>[__main__.py]"]
end

subgraph group_integrations["Integrations"]
  node_skill["Agent Skill<br/>[SKILL.md]"]
  node_action["GitHub Action<br/>[action.yml]"]
  node_mcp["MCP Server<br/>[mcp.py]"]
end

node_engineer(("Engineer or Agent"))
node_coding_agent(("External Coding Agent"))

node_engineer -->|"runs commands"| node_cli
node_cli -->|"dispatches to"| node_audit
node_engineer -.->|"supplies"| node_requirements
node_engineer -.->|"selects"| node_target
node_audit -.->|"indexes repository"| node_inventory
node_inventory -->|"discovers candidates"| node_route_discovery
node_audit -.->|"compares evidence"| node_comparison
node_requirements -.->|"defines intent"| node_comparison
node_target -.->|"scans source"| node_inventory
node_engineer -.->|"provides evidence"| node_observations
node_audit -->|"imports reports"| node_junit
node_junit -.->|"produces observations"| node_observations
node_observations -.->|"informs findings"| node_comparison
node_comparison -.->|"creates proposals"| node_planning
node_audit -.->|"writes reports"| node_reports
node_audit -->|"renders dashboard"| node_atlas
node_engineer -.->|"installs or uses"| node_skill
node_engineer -.->|"invokes audit"| node_action
node_engineer -.->|"connects through"| node_mcp
node_mcp -->|"invokes audit"| node_audit
node_reports -.->|"guides approved work"| node_coding_agent

click node_requirements "https://github.com/guhanavish/mirrormap/blob/main/references/data-model.md"
click node_observations "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/evidence.py"
click node_cli "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/__main__.py"
click node_audit "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/experience.py"
click node_inventory "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py"
click node_route_discovery "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/frameworks.py"
click node_comparison "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py"
click node_planning "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py"
click node_junit "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/evidence.py"
click node_reports "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/experience.py"
click node_atlas "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/dashboard.py"
click node_skill "https://github.com/guhanavish/mirrormap/blob/main/SKILL.md"
click node_action "https://github.com/guhanavish/mirrormap/blob/main/action.yml"
click node_mcp "https://github.com/guhanavish/mirrormap/blob/main/projectmirror/mcp.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_requirements,node_target,node_observations toneBlue
class node_audit,node_inventory,node_route_discovery,node_comparison,node_planning toneAmber
class node_junit,node_reports,node_atlas toneMint
class node_cli toneRose
class node_skill,node_action,node_mcp,node_engineer,node_coding_agent toneIndigo
```

## Components

### Audit Inputs

- [Approved Requirements](https://github.com/guhanavish/mirrormap/blob/main/references/data-model.md): `references/data-model.md`
- **Target Repository**
- [Test Observations](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/evidence.py): `projectmirror/evidence.py`

### Audit Engine

- [Audit Workflow](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/experience.py): `projectmirror/experience.py`
- [Source Inventory](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py): `projectmirror/core.py`
- [Route Candidates](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/frameworks.py): `projectmirror/frameworks.py`
- [Evidence Comparison](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py): `projectmirror/core.py`
- [Review-Only Plan](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/core.py): `projectmirror/core.py`

### Results and Evidence

- [JUnit Import](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/evidence.py): `projectmirror/evidence.py`
- [Audit Reports](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/experience.py): `projectmirror/experience.py`
- [Interactive Atlas](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/dashboard.py): `projectmirror/dashboard.py`

### User Interfaces

- [CLI Entry](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/__main__.py): `projectmirror/__main__.py`

### Integrations

- [Agent Skill](https://github.com/guhanavish/mirrormap/blob/main/SKILL.md): `SKILL.md`
- [GitHub Action](https://github.com/guhanavish/mirrormap/blob/main/action.yml): `action.yml`
- [MCP Server](https://github.com/guhanavish/mirrormap/blob/main/projectmirror/mcp.py): `projectmirror/mcp.py`

### Other components

- **Engineer or Agent**
- **External Coding Agent**

## Connections

- Engineer or Agent → CLI Entry: runs commands (evidence: `projectmirror/__main__.py`)
- CLI Entry → Audit Workflow: dispatches to (evidence: `projectmirror/__main__.py`)
- Engineer or Agent → Approved Requirements: supplies (evidence: `README.md`)
- Engineer or Agent → Target Repository: selects (evidence: `README.md`)
- Audit Workflow → Source Inventory: indexes repository (evidence: `README.md`)
- Source Inventory → Route Candidates: discovers candidates (evidence: `projectmirror/core.py`)
- Audit Workflow → Evidence Comparison: compares evidence (evidence: `README.md`)
- Approved Requirements → Evidence Comparison: defines intent (evidence: `README.md`)
- Target Repository → Source Inventory: scans source (evidence: `README.md`)
- Engineer or Agent → Test Observations: provides evidence (evidence: `README.md`)
- Audit Workflow → JUnit Import: imports reports (evidence: `projectmirror/experience.py`)
- JUnit Import → Test Observations: produces observations (evidence: `README.md`)
- Test Observations → Evidence Comparison: informs findings (evidence: `README.md`)
- Evidence Comparison → Review-Only Plan: creates proposals (evidence: `README.md`)
- Audit Workflow → Audit Reports: writes reports (evidence: `README.md`)
- Audit Workflow → Interactive Atlas: renders dashboard (evidence: `projectmirror/experience.py`)
- Engineer or Agent → Agent Skill: installs or uses (evidence: `README.md`)
- Engineer or Agent → GitHub Action: invokes audit (evidence: `README.md`)
- Engineer or Agent → MCP Server: connects through (evidence: `README.md`)
- MCP Server → Audit Workflow: invokes audit (evidence: `projectmirror/mcp.py`)
- Audit Reports → External Coding Agent: guides approved work (evidence: `README.md`)