# bavenraj08/quintelligence architecture

> Architecture diagram of the GitHub repository bavenraj08/quintelligence, 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/bavenraj08/quintelligence
- Repository: https://github.com/bavenraj08/quintelligence

## Overview

This is a FastAPI service that generates role-specific multiple-choice assessment questions. A request resolves a role’s skills and linked courses from Excel catalogs, retrieves reference-data process material from Chroma, builds generation instructions, and sends them with the request to an Azure chat-completions model; the API returns the model’s JSON output. The repository also contains a document-embedding path for Excel and PDF sources. No README was provided, so capabilities and wiring are based on the sampled source and tree.

Main entry points: [`main.py`](https://github.com/bavenraj08/quintelligence/blob/main/main.py) (Assessment API), [`model.py`](https://github.com/bavenraj08/quintelligence/blob/main/model.py) (Chat model adapter), [`data_embedding.py`](https://github.com/bavenraj08/quintelligence/blob/main/data_embedding.py) (Document embedding), [`dataset.py`](https://github.com/bavenraj08/quintelligence/blob/main/dataset.py) (Role and course lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Request API"]
  node_fastapi["Assessment API<br/>[main.py]"]
end

subgraph group_assessment["Assessment Setup"]
  node_catalog["Role and course lookup<br/>[dataset.py]"]
  node_reference_xlsx[("Reference catalog")]
  node_finance_xlsx[("Finance catalog<br/>[finance.xlsx]")]
end

subgraph group_knowledge["Knowledge Retrieval"]
  node_prompt_builder["Retrieval prompt builder"]
  node_chroma[("Reference Chroma store")]
  node_embedding["Document embedding<br/>[data_embedding.py]"]
  node_reference_docs["Reference source files"]
  node_finance_docs["Finance source files"]
end

subgraph group_generation["Question Generation"]
  node_retrieval_instruction["Question instructions<br/>[instruction.py]"]
  node_model_adapter["Chat model adapter<br/>[model.py]"]
end

node_user(("Assessment requester"))
node_azure{{"Azure chat service"}}

node_user -->|"submits request"| node_fastapi
node_fastapi -->|"looks up role"| node_catalog
node_catalog -->|"reads catalog"| node_reference_xlsx
node_catalog -->|"reads catalog"| node_finance_xlsx
node_fastapi -->|"builds instructions"| node_prompt_builder
node_prompt_builder -->|"queries passages"| node_chroma
node_prompt_builder -->|"adds retrieved context"| node_retrieval_instruction
node_embedding -->|"loads documents"| node_reference_docs
node_embedding -->|"loads documents"| node_finance_docs
node_embedding -->|"upserts chunks"| node_chroma
node_fastapi -->|"invokes generation"| node_model_adapter
node_model_adapter -->|"requests completion"| node_azure
node_azure -->|"returns completion"| node_model_adapter
node_model_adapter -->|"returns text"| node_fastapi
node_fastapi -->|"returns JSON"| node_user

click node_fastapi "https://github.com/bavenraj08/quintelligence/blob/main/main.py"
click node_catalog "https://github.com/bavenraj08/quintelligence/blob/main/dataset.py"
click node_reference_xlsx "https://github.com/bavenraj08/quintelligence/blob/main/knowledge_source/reference_data/excel/reference_data.xlsx"
click node_finance_xlsx "https://github.com/bavenraj08/quintelligence/blob/main/knowledge_source/finance/excel/finance.xlsx"
click node_prompt_builder "https://github.com/bavenraj08/quintelligence/blob/main/model_instruction.py"
click node_retrieval_instruction "https://github.com/bavenraj08/quintelligence/blob/main/instruction.py"
click node_chroma "https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/reference_data/chroma_db"
click node_embedding "https://github.com/bavenraj08/quintelligence/blob/main/data_embedding.py"
click node_reference_docs "https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/reference_data"
click node_finance_docs "https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/finance"
click node_model_adapter "https://github.com/bavenraj08/quintelligence/blob/main/model.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 toneBlue
class node_catalog,node_reference_xlsx,node_finance_xlsx toneAmber
class node_prompt_builder,node_chroma,node_embedding,node_reference_docs,node_finance_docs,node_user toneMint
class node_retrieval_instruction,node_model_adapter toneRose
class node_azure toneIndigo
```

## Components

### Request API

- [Assessment API](https://github.com/bavenraj08/quintelligence/blob/main/main.py): `main.py`

### Assessment Setup

- [Role and course lookup](https://github.com/bavenraj08/quintelligence/blob/main/dataset.py): `dataset.py`
- [Reference catalog](https://github.com/bavenraj08/quintelligence/blob/main/knowledge_source/reference_data/excel/reference_data.xlsx): `knowledge_source/reference_data/excel/reference_data.xlsx`
- [Finance catalog](https://github.com/bavenraj08/quintelligence/blob/main/knowledge_source/finance/excel/finance.xlsx): `knowledge_source/finance/excel/finance.xlsx`

### Knowledge Retrieval

- [Retrieval prompt builder](https://github.com/bavenraj08/quintelligence/blob/main/model_instruction.py): `model_instruction.py`
- [Reference Chroma store](https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/reference_data/chroma_db): `knowledge_source/reference_data/chroma_db`
- [Document embedding](https://github.com/bavenraj08/quintelligence/blob/main/data_embedding.py): `data_embedding.py`
- [Reference source files](https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/reference_data): `knowledge_source/reference_data`
- [Finance source files](https://github.com/bavenraj08/quintelligence/tree/main/knowledge_source/finance): `knowledge_source/finance`

### Question Generation

- [Question instructions](https://github.com/bavenraj08/quintelligence/blob/main/instruction.py): `instruction.py`
- [Chat model adapter](https://github.com/bavenraj08/quintelligence/blob/main/model.py): `model.py`

### Other components

- **Assessment requester**
- **Azure chat service**

## Connections

- Assessment requester → Assessment API: submits request
- Assessment API → Role and course lookup: looks up role
- Role and course lookup → Reference catalog: reads catalog
- Role and course lookup → Finance catalog: reads catalog
- Assessment API → Retrieval prompt builder: builds instructions
- Retrieval prompt builder → Reference Chroma store: queries passages
- Retrieval prompt builder → Question instructions: adds retrieved context
- Document embedding → Reference source files: loads documents
- Document embedding → Finance source files: loads documents
- Document embedding → Reference Chroma store: upserts chunks
- Assessment API → Chat model adapter: invokes generation
- Chat model adapter → Azure chat service: requests completion
- Azure chat service → Chat model adapter: returns completion
- Chat model adapter → Assessment API: returns text
- Assessment API → Assessment requester: returns JSON