# vitellaro-matteo/cdm-rag architecture

> Architecture diagram of the GitHub repository vitellaro-matteo/cdm-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vitellaro-matteo/cdm-rag
- Repository: https://github.com/vitellaro-matteo/cdm-rag

## Overview

cdm-rag is a FastAPI question-answering service over the CDM banking schema. Its principal workflow routes a question to exact graph-based lookups, vector retrieval, or both, then generates a context-grounded answer; a separate entity endpoint returns resolved schema details without an LLM. The graph is built from schema documents after resolving inheritance and relationships, and also supplies retrieval chunks for the vector index. The README documents these major stages; some runtime wiring is described there but not present in the sampled implementation excerpts.

Main entry points: [`cdm_rag/api.py`](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/api.py) (FastAPI endpoints), [`cdm_rag/router.py`](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/router.py) (Question router), [`cdm_rag/graph.py`](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/graph.py) (Entity graph), [`cdm_rag/store.py`](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/store.py) (Chroma index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_api["FastAPI endpoints<br/>[api.py]"]
end

subgraph group_schema["Schema Modeling"]
  node_corpus["CDM corpus"]
  node_inheritance["Inheritance resolver<br/>[inheritance.py]"]
  node_relationships["Relationship parser<br/>[relationships.py]"]
  node_graph["Entity graph<br/>[graph.py]"]
end

subgraph group_retrieval["Context Retrieval"]
  node_chunks["Retrieval chunks<br/>[chunks.py]"]
  node_embeddings["Text embeddings<br/>[embeddings.py]"]
  node_store[("Chroma index<br/>[store.py]")]
end

subgraph group_answers["Answer Generation"]
  node_router["Question router<br/>[router.py]"]
  node_generate["Grounded generation<br/>[generate.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

node_user(("Questioner"))
node_groq["Groq service"]

node_user -->|"asks via"| node_api
node_corpus -->|"provides schema"| node_inheritance
node_corpus -->|"provides schema"| node_relationships
node_inheritance -->|"resolves attributes"| node_graph
node_relationships -->|"supplies edges"| node_graph
node_graph -->|"builds chunks"| node_chunks
node_chunks -->|"indexes text"| node_store
node_chunks -->|"supplies text"| node_embeddings
node_embeddings -->|"writes vectors"| node_store
node_api -->|"entity lookup"| node_graph
node_api -->|"routes question"| node_router
node_api -->|"loads index"| node_store
node_router -->|"looks up structure"| node_graph
node_router -->|"searches chunks"| node_store
node_router -->|"embeds query"| node_embeddings
node_router -->|"passes context"| node_generate
node_generate -->|"requests answer"| node_llm
node_llm -->|"calls provider"| node_groq
node_api -->|"returns result"| node_user

click node_api "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/api.py"
click node_corpus "https://github.com/vitellaro-matteo/cdm-rag/tree/main/corpus_subset"
click node_inheritance "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/inheritance.py"
click node_relationships "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/relationships.py"
click node_graph "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/graph.py"
click node_chunks "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/chunks.py"
click node_embeddings "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/embeddings.py"
click node_store "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/store.py"
click node_router "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/router.py"
click node_generate "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/generate.py"
click node_llm "https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/llm_client.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_api toneBlue
class node_corpus,node_inheritance,node_relationships,node_graph toneAmber
class node_chunks,node_embeddings,node_store toneMint
class node_router,node_generate,node_llm toneRose
class node_user,node_groq toneIndigo
```

## Components

### HTTP API

- [FastAPI endpoints](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/api.py): `cdm_rag/api.py`

### Schema Modeling

- [CDM corpus](https://github.com/vitellaro-matteo/cdm-rag/tree/main/corpus_subset): `corpus_subset`
- [Inheritance resolver](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/inheritance.py): `cdm_rag/inheritance.py`
- [Relationship parser](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/relationships.py): `cdm_rag/relationships.py`
- [Entity graph](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/graph.py): `cdm_rag/graph.py`

### Context Retrieval

- [Retrieval chunks](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/chunks.py): `cdm_rag/chunks.py`
- [Text embeddings](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/embeddings.py): `cdm_rag/embeddings.py`
- [Chroma index](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/store.py): `cdm_rag/store.py`

### Answer Generation

- [Question router](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/router.py): `cdm_rag/router.py`
- [Grounded generation](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/generate.py): `cdm_rag/generate.py`
- [LLM client](https://github.com/vitellaro-matteo/cdm-rag/blob/main/cdm_rag/llm_client.py): `cdm_rag/llm_client.py`

### Other components

- **Questioner**
- **Groq service**

## Connections

- Questioner → FastAPI endpoints: asks via
- CDM corpus → Inheritance resolver: provides schema
- CDM corpus → Relationship parser: provides schema
- Inheritance resolver → Entity graph: resolves attributes
- Relationship parser → Entity graph: supplies edges
- Entity graph → Retrieval chunks: builds chunks
- Retrieval chunks → Chroma index: indexes text
- Retrieval chunks → Text embeddings: supplies text
- Text embeddings → Chroma index: writes vectors
- FastAPI endpoints → Entity graph: entity lookup
- FastAPI endpoints → Question router: routes question
- FastAPI endpoints → Chroma index: loads index
- Question router → Entity graph: looks up structure
- Question router → Chroma index: searches chunks
- Question router → Text embeddings: embeds query
- Question router → Grounded generation: passes context
- Grounded generation → LLM client: requests answer
- LLM client → Groq service: calls provider
- FastAPI endpoints → Questioner: returns result