# mizcausevic-dev/analytics-semantic-layer-publisher architecture

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

## Overview

Purpose and principal workflow: Analytics Semantic Layer Publisher turns a dbt-style YAML semantic layer into browsable catalog pages, metric APIs, and Schema.org JSON-LD. An external HTTP client—such as a human’s browser or an AI/search consumer—initiates the main workflow by requesting a page or API route; the FastAPI application serves it using the semantic service and the YAML source.

Components

**HTTP interface**
- **External HTTP client** — `null` path; a browser, AI/search consumer, or other HTTP client requests publisher pages, metric data, or semantic exports.
- **FastAPI application and routes** — `app/main.py`; defines the FastAPI entry point and HTML, summary, catalog, metric, sample, JSON-LD, and OpenAPI routes, delegating page rendering and semantic data operations to their respective modules.

**Human-readable proof surfaces**
- **Page renderer** — `app/render.py`; builds the overview, catalog, evidence, and API-summary HTML, obtaining semantic content through `build_service()`.

**Semantic publishing**
- **Semantic layer service** — `app/services/semantic_service.py`; reads the YAML source, assembles catalog statistics and summaries, looks up metrics, and constructs `DataCatalog` and `DefinedTerm` JSON-LD.
- **Sample semantic-layer source** — `app/data/sample_semantic_layer.yml`; supplies the catalog, semantic models, and metric definitions used by the service.

Relationships
- **External HTTP client -> FastAPI application and routes**: requests a page or data endpoint; the routes are defined in `app/main.py`.
- **FastAPI application and routes -> Page renderer**: calls the relevant renderer for HTML routes; the calls are in `app/main.py`.
- **Page renderer -> Semantic layer service**: builds a service and requests catalog, summary, or JSON-LD data while rendering; these calls are in `app/render.py`.
- **FastAPI application and routes -> Semantic layer service**: calls service methods for API responses and semantic exports; these calls are in `app/main.py`.
- **Semantic layer service -> Sample semantic-layer source**: reads and parses the YAML file when loading data; `load()` uses `Path.read_text()` and `yaml.safe_load()`.
- **FastAPI application and routes -> External HTTP client**: returns rendered HTML or JSON responses, including JSON-LD; route response types and handlers are in `app/main.py`.

Coverage limits: The sampled files establish a local YAML-backed implementation and its HTTP interfaces; they do not establish an external dbt connection, persistent database, or runtime consumers beyond the documented use cases. The renderer excerpt is partial, so its omitted implementation details are not mapped.

Main entry points: [`app/main.py`](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/main.py) (FastAPI routes), [`app/services/semantic_service.py`](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/services/semantic_service.py) (Semantic layer service), [`app/render.py`](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/render.py) (Page renderer), [`app/data/sample_semantic_layer.yml`](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/data/sample_semantic_layer.yml) (Sample semantic layer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP interface"]
  node_client(("External HTTP client"))
  node_app["FastAPI routes<br/>Web application"]
end

subgraph group_proof["Human-readable proof surfaces"]
  node_renderer["Page renderer<br/>HTML renderer"]
end

subgraph group_semantic["Semantic publishing"]
  node_service["Semantic layer service<br/>Semantic service"]
  node_yaml["Sample semantic layer<br/>YAML source"]
end

node_client -->|"requests"| node_app
node_app -->|"renders HTML"| node_renderer
node_renderer -->|"requests semantic data"| node_service
node_app -->|"requests API data"| node_service
node_service -->|"loads YAML"| node_yaml
node_app -->|"returns responses"| node_client

click node_app "https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/main.py"
click node_renderer "https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/render.py"
click node_service "https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/services/semantic_service.py"
click node_yaml "https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/data/sample_semantic_layer.yml"

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_client,node_app toneBlue
class node_renderer toneAmber
class node_service,node_yaml toneMint
```

## Components

### HTTP interface

- **External HTTP client**: HTTP client
- [FastAPI routes](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/main.py): Web application · `app/main.py`

### Human-readable proof surfaces

- [Page renderer](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/render.py): HTML renderer · `app/render.py`

### Semantic publishing

- [Semantic layer service](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/services/semantic_service.py): Semantic service · `app/services/semantic_service.py`
- [Sample semantic layer](https://github.com/mizcausevic-dev/analytics-semantic-layer-publisher/blob/main/app/data/sample_semantic_layer.yml): YAML source · `app/data/sample_semantic_layer.yml`

## Connections

- External HTTP client → FastAPI routes: requests
- FastAPI routes → Page renderer: renders HTML
- Page renderer → Semantic layer service: requests semantic data
- FastAPI routes → Semantic layer service: requests API data
- Semantic layer service → Sample semantic layer: loads YAML
- FastAPI routes → External HTTP client: returns responses