# mizcausevic-dev/semantic-metrics-catalog architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/semantic-metrics-catalog, 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/semantic-metrics-catalog
- Repository: https://github.com/mizcausevic-dev/semantic-metrics-catalog

## Overview

Semantic Metrics Catalog is a FastAPI application for governing metric definitions: it loads sample contracts, derives catalog, ownership, freshness, and review views, and publishes both operator-facing pages and a JSON-LD catalog. The central workflow runs from HTTP requests through route handlers to the semantic service and YAML source; the service also builds contract, owner, summary, and export payloads. README documents these capabilities, while sampled code confirms the service and route wiring. The rendering excerpt is partial, so page-to-service details beyond visible calls are kept at module level.

Main entry points: [`app/services/semantic_service.py`](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py) (Catalog service), [`app/main.py`](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/main.py) (FastAPI routes), [`app/render.py`](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/render.py) (Page renderer), [`app/data/sample_metrics_catalog.yml`](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/data/sample_metrics_catalog.yml) (Metric contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP interface"]
  node_fastapi["FastAPI routes<br/>[main.py]"]
  node_api_payload["Sample API payload"]
  node_api_responses["API responses<br/>[main.py]"]
end

subgraph group_governance["Metric governance"]
  node_catalog_service["Catalog service"]
  node_metric_contracts["Metric contracts"]
  node_catalog["Catalog &amp; stats"]
  node_contract_board["Contract board"]
  node_owner_lanes["Owner lanes"]
  node_dashboard["Dashboard summary"]
  node_metric_lookup["Metric lookup"]
end

subgraph group_presentation["Operator surfaces"]
  node_page_renderer["Page renderer<br/>[render.py]"]
  node_operator_pages["Governance pages<br/>[render.py]"]
end

subgraph group_publication["Semantic publication"]
  node_jsonld["JSON-LD export"]
end

node_operator(("Operator"))
node_api_consumer(("API consumer"))
node_ai_consumer(("AI / retrieval"))

node_operator -->|"requests pages"| node_fastapi
node_api_consumer -->|"requests data"| node_fastapi
node_ai_consumer -->|"requests export"| node_fastapi
node_fastapi -->|"renders pages"| node_page_renderer
node_page_renderer -->|"queries data"| node_catalog_service
node_fastapi -->|"dispatches requests"| node_catalog_service
node_catalog_service -->|"builds catalog"| node_catalog
node_catalog -->|"reads YAML"| node_metric_contracts
node_catalog -->|"derives owners"| node_owner_lanes
node_catalog_service -->|"builds board"| node_contract_board
node_contract_board -->|"reads catalog"| node_catalog
node_catalog_service -->|"builds lanes"| node_owner_lanes
node_owner_lanes -->|"reads catalog"| node_catalog
node_catalog_service -->|"builds summary"| node_dashboard
node_dashboard -->|"reads catalog"| node_catalog
node_catalog_service -->|"looks up metric"| node_metric_lookup
node_metric_lookup -->|"searches catalog"| node_catalog
node_catalog_service -->|"assembles sample"| node_api_payload
node_api_payload -->|"includes summary"| node_dashboard
node_api_payload -->|"includes board"| node_contract_board
node_api_payload -->|"includes lanes"| node_owner_lanes
node_catalog_service -->|"builds export"| node_jsonld
node_jsonld -->|"reads catalog"| node_catalog
node_page_renderer -->|"renders surfaces"| node_operator_pages
node_fastapi -->|"returns payloads"| node_api_responses
node_api_responses -->|"sends data"| node_api_consumer
node_jsonld -->|"publishes catalog"| node_ai_consumer

click node_fastapi "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/main.py"
click node_page_renderer "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/render.py"
click node_catalog_service "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_metric_contracts "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/data/sample_metrics_catalog.yml"
click node_catalog "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_contract_board "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_owner_lanes "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_dashboard "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_metric_lookup "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_api_payload "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_jsonld "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py"
click node_operator_pages "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/render.py"
click node_api_responses "https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/main.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_fastapi,node_api_payload,node_api_responses toneBlue
class node_catalog_service,node_metric_contracts,node_catalog,node_contract_board,node_owner_lanes,node_dashboard,node_metric_lookup toneAmber
class node_page_renderer,node_operator_pages,node_api_consumer toneMint
class node_jsonld toneRose
class node_operator,node_ai_consumer toneIndigo
```

## Components

### HTTP interface

- [FastAPI routes](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/main.py): `app/main.py`
- [Sample API payload](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [API responses](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/main.py): `app/main.py`

### Metric governance

- [Catalog service](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [Metric contracts](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/data/sample_metrics_catalog.yml): `app/data/sample_metrics_catalog.yml`
- [Catalog & stats](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [Contract board](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [Owner lanes](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [Dashboard summary](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`
- [Metric lookup](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`

### Operator surfaces

- [Page renderer](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/render.py): `app/render.py`
- [Governance pages](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/render.py): `app/render.py`

### Semantic publication

- [JSON-LD export](https://github.com/mizcausevic-dev/semantic-metrics-catalog/blob/main/app/services/semantic_service.py): `app/services/semantic_service.py`

### Other components

- **Operator**
- **API consumer**
- **AI / retrieval**

## Connections

- Operator → FastAPI routes: requests pages
- API consumer → FastAPI routes: requests data
- AI / retrieval → FastAPI routes: requests export
- FastAPI routes → Page renderer: renders pages
- Page renderer → Catalog service: queries data
- FastAPI routes → Catalog service: dispatches requests
- Catalog service → Catalog & stats: builds catalog
- Catalog & stats → Metric contracts: reads YAML
- Catalog & stats → Owner lanes: derives owners
- Catalog service → Contract board: builds board
- Contract board → Catalog & stats: reads catalog
- Catalog service → Owner lanes: builds lanes
- Owner lanes → Catalog & stats: reads catalog
- Catalog service → Dashboard summary: builds summary
- Dashboard summary → Catalog & stats: reads catalog
- Catalog service → Metric lookup: looks up metric
- Metric lookup → Catalog & stats: searches catalog
- Catalog service → Sample API payload: assembles sample
- Sample API payload → Dashboard summary: includes summary
- Sample API payload → Contract board: includes board
- Sample API payload → Owner lanes: includes lanes
- Catalog service → JSON-LD export: builds export
- JSON-LD export → Catalog & stats: reads catalog
- Page renderer → Governance pages: renders surfaces
- FastAPI routes → API responses: returns payloads
- API responses → API consumer: sends data
- JSON-LD export → AI / retrieval: publishes catalog