mizcausevic-dev/analytics-semantic-layer-publisher

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.