# ashindian-coder/mira architecture

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

- Interactive diagram: https://gitdiagram.com/ashindian-coder/mira
- Repository: https://github.com/ashindian-coder/mira

## Overview

MIRA is a CPSE material-identity harmonization application: users upload source material masters, MIRA parses and standardizes records, generates and scores cross-CPSE match candidates, and sends uncertain or high-confidence recommendations to people for review. Approved groups can be mapped to traceable Common National Material Codes, with audit and analytics available afterward. The graph combines documented workflow capabilities with source-index evidence; several route implementations are unsampled, so their internal calls are shown only where the README documents them.

Main entry points: [`backend/app/main.py`](https://github.com/ashindian-coder/mira/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/api/v1/matching.py`](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/matching.py) (Matching API), [`backend/app/store.py`](https://github.com/ashindian-coder/mira/blob/main/backend/app/store.py) (Persistent application stores), [`frontend/src/lib/api.ts`](https://github.com/ashindian-coder/mira/blob/main/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interface"]
  node_frontend["Web application<br/>[App.tsx]"]
  node_auth["Authentication context<br/>[AuthContext.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
  node_materials_ui["Materials workspace<br/>[Materials.tsx]"]
  node_review_ui["Match review<br/>[MatchReview.tsx]"]
  node_mapping_ui["Mappings workspace<br/>[Mappings.tsx]"]
  node_analytics_ui["Analytics and audit<br/>[Analytics.tsx]"]
end

subgraph group_api["API and access"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_materials_api["Materials API<br/>[materials.py]"]
  node_matching_api["Matching API<br/>[matching.py]"]
  node_review_api["Review API<br/>[review.py]"]
  node_mappings_api["Mappings API<br/>[mappings.py]"]
  node_audit_api["Audit and analytics APIs<br/>[audit.py]"]
end

subgraph group_ingest["Material ingestion"]
  node_ingest_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_parser["Specification parser<br/>[service.py]"]
  node_normalizer["Material normalization<br/>[service.py]"]
end

subgraph group_match["Matching and resolution"]
  node_blocker["Candidate blocking<br/>[service.py]"]
  node_vector_search["Vector search<br/>[milvus_client.py]"]
  node_classifier["Hybrid scoring and gates<br/>[classifier.py]"]
  node_harmonizer["Canonical harmonization<br/>[service.py]"]
  node_cnmc["CNMC registry service<br/>[service.py]"]
end

subgraph group_records["Persistence and governance"]
  node_stores[("Persistent application stores<br/>[store.py]")]
  node_database[("PostgreSQL<br/>[database.py]")]
end

node_operator(("MIRA user"))

node_operator -->|"uses"| node_frontend
node_frontend -->|"provides auth"| node_auth
node_auth -->|"calls auth APIs"| node_api_client
node_materials_ui -->|"uploads materials"| node_api_client
node_review_ui -->|"requests review"| node_api_client
node_mapping_ui -->|"manages mappings"| node_api_client
node_analytics_ui -->|"requests reports"| node_api_client
node_frontend -->|"API requests"| node_backend
node_backend -->|"routes requests"| node_materials_api
node_backend -->|"routes requests"| node_matching_api
node_backend -->|"routes requests"| node_review_api
node_backend -->|"routes requests"| node_mappings_api
node_backend -->|"routes requests"| node_audit_api
node_materials_api -.->|"ingests uploads"| node_ingest_pipeline
node_ingest_pipeline -.->|"extracts specifications"| node_parser
node_ingest_pipeline -.->|"normalizes records"| node_normalizer
node_materials_api -.->|"persists materials"| node_stores
node_matching_api -.->|"generates candidates"| node_blocker
node_matching_api -.->|"adds vector candidates"| node_vector_search
node_matching_api -.->|"scores candidates"| node_classifier
node_matching_api -.->|"persists candidates"| node_stores
node_review_api -.->|"records decisions"| node_stores
node_mappings_api -->|"builds canonical records"| node_harmonizer
node_mappings_api -->|"generates codes"| node_cnmc
node_harmonizer -.->|"registers identity"| node_cnmc
node_mappings_api -->|"records mapping events"| node_audit_api
node_audit_api -.->|"reads audit data"| node_stores
node_stores -->|"persists records"| node_database

click node_frontend "https://github.com/ashindian-coder/mira/blob/main/frontend/src/app/App.tsx"
click node_auth "https://github.com/ashindian-coder/mira/blob/main/frontend/src/context/AuthContext.tsx"
click node_api_client "https://github.com/ashindian-coder/mira/blob/main/frontend/src/lib/api.ts"
click node_materials_ui "https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Materials/Materials.tsx"
click node_review_ui "https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/MatchReview/MatchReview.tsx"
click node_mapping_ui "https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Mappings/Mappings.tsx"
click node_analytics_ui "https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Analytics/Analytics.tsx"
click node_backend "https://github.com/ashindian-coder/mira/blob/main/backend/app/main.py"
click node_materials_api "https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/materials.py"
click node_matching_api "https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/matching.py"
click node_review_api "https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/review.py"
click node_mappings_api "https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/mappings.py"
click node_audit_api "https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/audit.py"
click node_ingest_pipeline "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/ingestion/pipeline.py"
click node_parser "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/parsing/service.py"
click node_normalizer "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/normalization/service.py"
click node_blocker "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/blocking/service.py"
click node_vector_search "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/matching/milvus_client.py"
click node_classifier "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/matching/classifier.py"
click node_harmonizer "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/harmonization/service.py"
click node_cnmc "https://github.com/ashindian-coder/mira/blob/main/backend/app/services/cnmc/service.py"
click node_stores "https://github.com/ashindian-coder/mira/blob/main/backend/app/store.py"
click node_database "https://github.com/ashindian-coder/mira/blob/main/backend/app/core/database.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_frontend,node_auth,node_api_client,node_materials_ui,node_review_ui,node_mapping_ui,node_analytics_ui,node_operator toneBlue
class node_backend,node_materials_api,node_matching_api,node_review_api,node_mappings_api,node_audit_api toneAmber
class node_ingest_pipeline,node_parser,node_normalizer toneMint
class node_blocker,node_vector_search,node_classifier,node_harmonizer,node_cnmc toneRose
class node_stores,node_database toneIndigo
```

## Components

### User interface

- [Web application](https://github.com/ashindian-coder/mira/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [Authentication context](https://github.com/ashindian-coder/mira/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [API client](https://github.com/ashindian-coder/mira/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Materials workspace](https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Materials/Materials.tsx): `frontend/src/pages/Materials/Materials.tsx`
- [Match review](https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/MatchReview/MatchReview.tsx): `frontend/src/pages/MatchReview/MatchReview.tsx`
- [Mappings workspace](https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Mappings/Mappings.tsx): `frontend/src/pages/Mappings/Mappings.tsx`
- [Analytics and audit](https://github.com/ashindian-coder/mira/blob/main/frontend/src/pages/Analytics/Analytics.tsx): `frontend/src/pages/Analytics/Analytics.tsx`

### API and access

- [FastAPI application](https://github.com/ashindian-coder/mira/blob/main/backend/app/main.py): `backend/app/main.py`
- [Materials API](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/materials.py): `backend/app/api/v1/materials.py`
- [Matching API](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/matching.py): `backend/app/api/v1/matching.py`
- [Review API](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/review.py): `backend/app/api/v1/review.py`
- [Mappings API](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/mappings.py): `backend/app/api/v1/mappings.py`
- [Audit and analytics APIs](https://github.com/ashindian-coder/mira/blob/main/backend/app/api/v1/audit.py): `backend/app/api/v1/audit.py`

### Material ingestion

- [Ingestion pipeline](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/ingestion/pipeline.py): `backend/app/services/ingestion/pipeline.py`
- [Specification parser](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/parsing/service.py): `backend/app/services/parsing/service.py`
- [Material normalization](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/normalization/service.py): `backend/app/services/normalization/service.py`

### Matching and resolution

- [Candidate blocking](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/blocking/service.py): `backend/app/services/blocking/service.py`
- [Vector search](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/matching/milvus_client.py): `backend/app/services/matching/milvus_client.py`
- [Hybrid scoring and gates](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/matching/classifier.py): `backend/app/services/matching/classifier.py`
- [Canonical harmonization](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/harmonization/service.py): `backend/app/services/harmonization/service.py`
- [CNMC registry service](https://github.com/ashindian-coder/mira/blob/main/backend/app/services/cnmc/service.py): `backend/app/services/cnmc/service.py`

### Persistence and governance

- [Persistent application stores](https://github.com/ashindian-coder/mira/blob/main/backend/app/store.py): `backend/app/store.py`
- [PostgreSQL](https://github.com/ashindian-coder/mira/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **MIRA user**

## Connections

- MIRA user → Web application: uses
- Web application → Authentication context: provides auth (evidence: `frontend/src/app/App.tsx`)
- Authentication context → API client: calls auth APIs (evidence: `frontend/src/context/AuthContext.tsx`)
- Materials workspace → API client: uploads materials (evidence: `frontend/src/lib/api.ts`)
- Match review → API client: requests review (evidence: `frontend/src/pages/MatchReview/MatchReview.tsx`)
- Mappings workspace → API client: manages mappings (evidence: `frontend/src/pages/Mappings/Mappings.tsx`)
- Analytics and audit → API client: requests reports
- Web application → FastAPI application: API requests
- FastAPI application → Materials API: routes requests
- FastAPI application → Matching API: routes requests
- FastAPI application → Review API: routes requests
- FastAPI application → Mappings API: routes requests
- FastAPI application → Audit and analytics APIs: routes requests
- Materials API → Ingestion pipeline: ingests uploads
- Ingestion pipeline → Specification parser: extracts specifications
- Ingestion pipeline → Material normalization: normalizes records
- Materials API → Persistent application stores: persists materials
- Matching API → Candidate blocking: generates candidates
- Matching API → Vector search: adds vector candidates
- Matching API → Hybrid scoring and gates: scores candidates
- Matching API → Persistent application stores: persists candidates
- Review API → Persistent application stores: records decisions (evidence: `backend/app/api/v1/review.py`)
- Mappings API → Canonical harmonization: builds canonical records (evidence: `backend/app/api/v1/mappings.py`)
- Mappings API → CNMC registry service: generates codes (evidence: `backend/app/api/v1/mappings.py`)
- Canonical harmonization → CNMC registry service: registers identity
- Mappings API → Audit and analytics APIs: records mapping events (evidence: `backend/app/api/v1/mappings.py`)
- Audit and analytics APIs → Persistent application stores: reads audit data
- Persistent application stores → PostgreSQL: persists records (evidence: `backend/app/store.py`)
