# mizcausevic-dev/fintech-regulatory-knowledge-graph architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/fintech-regulatory-knowledge-graph, 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/fintech-regulatory-knowledge-graph
- Repository: https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph

## Overview

Purpose and principal workflow: This application serves a seeded fintech regulatory knowledge graph through FastAPI. A browser user or HTTP API client initiates the main workflow by requesting a page or API route; the application reads graph data to summarize entities, explain relationship paths, or produce a JSON-LD export. The dataset is constructed locally at startup, not ingested from an external source.

Components

**HTTP callers** — **Path: null.** Browser users request the HTML overview, graph board, and evidence pages; API clients can request graph summaries, filtered entities, paths, and JSON-LD.

**FastAPI routes and page rendering** — `app/main.py`. Defines the FastAPI application, HTTP endpoints, and HTML page handlers; page handlers assemble views from graph-service results, while API handlers return service results and translate unknown path entities to 404 responses.

**Graph query and export logic** — `app/services/graph_service.py`. Builds an in-memory node index and outbound-edge index from the loaded dataset, then computes summaries, filtered entity lists, breadth-first relationship paths, and JSON-LD output.

**Seed graph data** — `app/data/sample_graph.py`. Creates the local graph of regulators, rules, firms, products, obligations, controls, disclosures, and their rationale-bearing relationships.

**Graph and response models** — `app/models.py`. Defines Pydantic types and validation for graph nodes and edges, datasets, path steps, summaries, and JSON-LD results.

**Downstream consumers** — **Path: null.** The README identifies downstream AI systems and internal compliance tooling as consumers of the machine-readable JSON-LD export; no consumer implementation is present in the tree.

Relationships

- HTTP callers -> FastAPI routes and page rendering: send requests to the documented HTML and API routes.
- FastAPI routes and page rendering -> Graph query and export logic: call summary, entity, path, lead-path, and JSON-LD methods; source: `app/main.py`.
- Graph query and export logic -> Seed graph data: calls `load_sample_graph()` when constructing the service singleton; source: `app/services/graph_service.py`.
- Seed graph data -> Graph and response models: constructs typed nodes, edges, and a dataset; source: `app/data/sample_graph.py`.
- Graph query and export logic -> Graph and response models: returns typed summaries, paths, and JSON-LD results; source: `app/services/graph_service.py`.
- Graph query and export logic -> Graph query and export logic: reads its in-memory dataset and indexes to answer queries and build exports; source: `app/services/graph_service.py`.
- FastAPI routes and page rendering -> Downstream consumers: exposes the JSON-LD data through `/api/export/jsonld` and the evidence page.
- Downstream consumers -> HTTP callers: consumers can request the documented export endpoint; the repository does not establish a particular deployed consumer or invocation.

Coverage limits: The sampled source omits parts of `app/main.py`, including application startup details and portions of the page handlers. The repository documents a local run command, but the excerpts do not establish deployment topology, persistent storage, external data ingestion, or an actual downstream AI client.

Main entry points: [`app/services/graph_service.py`](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/services/graph_service.py) (Graph query service), [`app/main.py`](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/main.py) (FastAPI routes), [`app/data/sample_graph.py`](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/data/sample_graph.py) (Seed graph data), [`app/models.py`](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/models.py) (Graph response models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External actors"]
  node_http_callers(("HTTP callers<br/>External actor"))
  node_downstream_consumers(("Downstream consumers<br/>External consumer"))
end

subgraph group_application["Application"]
  node_fastapi_routes["FastAPI routes<br/>HTTP application"]
end

subgraph group_graph["Graph services and data"]
  node_graph_service["Graph query service<br/>Query and export service"]
  node_seed_graph["Seed graph data<br/>Local dataset"]
  node_graph_models["Graph response models<br/>Pydantic models"]
end

node_http_callers -->|"send requests"| node_fastapi_routes
node_fastapi_routes -->|"call queries"| node_graph_service
node_graph_service -->|"load dataset"| node_seed_graph
node_seed_graph -->|"construct typed data"| node_graph_models
node_graph_service -->|"return typed results"| node_graph_models
node_graph_service -->|"query indexes"| node_graph_service
node_fastapi_routes -->|"expose exports"| node_downstream_consumers
node_downstream_consumers -->|"request exports"| node_http_callers

click node_fastapi_routes "https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/main.py"
click node_graph_service "https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/services/graph_service.py"
click node_seed_graph "https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/data/sample_graph.py"
click node_graph_models "https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/models.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_http_callers,node_downstream_consumers toneBlue
class node_fastapi_routes toneAmber
class node_graph_service,node_seed_graph,node_graph_models toneMint
```

## Components

### External actors

- **HTTP callers**: External actor · Browser users and API clients.
- **Downstream consumers**: External consumer · AI systems and compliance tools consuming machine-readable exports.

### Application

- [FastAPI routes](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/main.py): HTTP application · Routes requests to API results and rendered pages. · `app/main.py`

### Graph services and data

- [Graph query service](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/services/graph_service.py): Query and export service · Builds in-memory indexes and answers graph queries. · `app/services/graph_service.py`
- [Seed graph data](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/data/sample_graph.py): Local dataset · Constructs the regulatory knowledge graph at startup. · `app/data/sample_graph.py`
- [Graph response models](https://github.com/mizcausevic-dev/fintech-regulatory-knowledge-graph/blob/main/app/models.py): Pydantic models · `app/models.py`

## Connections

- HTTP callers → FastAPI routes: send requests · Requests documented HTML and API routes.
- FastAPI routes → Graph query service: call queries · Requests summaries, entities, paths, lead paths, and JSON-LD.
- Graph query service → Seed graph data: load dataset · Calls load_sample_graph() when constructing the service singleton.
- Seed graph data → Graph response models: construct typed data · Creates typed nodes, edges, and a dataset.
- Graph query service → Graph response models: return typed results · Returns summaries, paths, and JSON-LD results.
- Graph query service → Graph query service: query indexes · Reads its in-memory dataset and indexes for queries and exports.
- FastAPI routes → Downstream consumers: expose exports · Exposes JSON-LD through the export route and evidence page.
- Downstream consumers → HTTP callers: request exports · Consumers can request the documented export endpoint.