# kalvaharshith/org-brain architecture

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

- Interactive diagram: https://gitdiagram.com/kalvaharshith/org-brain
- Repository: https://github.com/kalvaharshith/org-brain

## Overview

Organizational Brain is a FastAPI knowledge service for indexing organizational documents and answering questions from them. The main workflow is document upload, parsing and chunking, local embedding, and persistence; chat uses hybrid vector/keyword retrieval, builds cited context, and asks Groq to generate an answer. Project, knowledge-search, and feedback endpoints expose supporting capabilities. The sampled code supports ingestion and retrieval details; chat and feedback route internals are not included, so those connections are limited to the apparent API entry points.

Main entry points: [`backend/app/main.py`](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/services/rag.py`](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/rag.py) (RAG orchestration), [`backend/app/database.py`](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/database.py) (Database session), [`backend/app/services/ingestion.py`](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/ingestion.py) (Document ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API surface"]
  node_app["FastAPI app<br/>[main.py]"]
  node_documents["Documents API<br/>[documents.py]"]
  node_chat["Chat API<br/>[chat.py]"]
  node_knowledge["Knowledge API<br/>[knowledge.py]"]
  node_projects["Projects API<br/>[projects.py]"]
  node_feedback["Feedback API<br/>[feedback.py]"]
end

subgraph group_index["Knowledge indexing"]
  node_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
end

subgraph group_answer["Question answering"]
  node_rag["RAG orchestration<br/>[rag.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_data["Persistence"]
  node_models["Domain models<br/>[models.py]"]
  node_database[("Database session<br/>[database.py]")]
end

node_user(("API client"))
node_groq["Groq API"]

node_user -->|"sends requests"| node_app
node_app -->|"dispatches"| node_documents
node_app -->|"dispatches"| node_chat
node_app -->|"dispatches"| node_knowledge
node_app -->|"dispatches"| node_projects
node_app -->|"dispatches"| node_feedback
node_documents -->|"uploads for indexing"| node_ingestion
node_ingestion -->|"embeds chunks"| node_embeddings
node_ingestion -->|"persists records"| node_database
node_ingestion -->|"creates records"| node_models
node_chat -->|"requests answers"| node_rag
node_knowledge -->|"requests search"| node_rag
node_rag -->|"embeds query"| node_embeddings
node_rag -->|"retrieves and stores"| node_database
node_rag -->|"reads and writes"| node_models
node_rag -->|"requests generation"| node_llm
node_llm -->|"calls"| node_groq
node_documents -->|"reads records"| node_database
node_knowledge -->|"reads records"| node_database
node_projects -->|"reads records"| node_database
node_feedback -->|"accesses records"| node_database

click node_app "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/main.py"
click node_documents "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/documents.py"
click node_chat "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/chat.py"
click node_knowledge "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/knowledge.py"
click node_projects "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/projects.py"
click node_feedback "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/feedback.py"
click node_ingestion "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/ingestion.py"
click node_embeddings "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/embeddings.py"
click node_rag "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/rag.py"
click node_llm "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/llm.py"
click node_models "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/models.py"
click node_database "https://github.com/kalvaharshith/org-brain/blob/main/backend/app/database.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_app,node_documents,node_chat,node_knowledge,node_projects,node_feedback,node_user toneBlue
class node_ingestion,node_embeddings toneAmber
class node_rag,node_llm,node_groq toneMint
class node_models,node_database toneRose
```

## Components

### API surface

- [FastAPI app](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/main.py): `backend/app/main.py`
- [Documents API](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/documents.py): `backend/app/api/documents.py`
- [Chat API](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/chat.py): `backend/app/api/chat.py`
- [Knowledge API](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/knowledge.py): `backend/app/api/knowledge.py`
- [Projects API](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Feedback API](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/api/feedback.py): `backend/app/api/feedback.py`

### Knowledge indexing

- [Document ingestion](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/ingestion.py): `backend/app/services/ingestion.py`
- [Embeddings](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`

### Question answering

- [RAG orchestration](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/rag.py): `backend/app/services/rag.py`
- [LLM client](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/services/llm.py): `backend/app/services/llm.py`

### Persistence

- [Domain models](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/models.py): `backend/app/models.py`
- [Database session](https://github.com/kalvaharshith/org-brain/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **API client**
- **Groq API**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → Documents API: dispatches
- FastAPI app → Chat API: dispatches
- FastAPI app → Knowledge API: dispatches
- FastAPI app → Projects API: dispatches
- FastAPI app → Feedback API: dispatches
- Documents API → Document ingestion: uploads for indexing
- Document ingestion → Embeddings: embeds chunks
- Document ingestion → Database session: persists records
- Document ingestion → Domain models: creates records
- Chat API → RAG orchestration: requests answers
- Knowledge API → RAG orchestration: requests search
- RAG orchestration → Embeddings: embeds query
- RAG orchestration → Database session: retrieves and stores
- RAG orchestration → Domain models: reads and writes
- RAG orchestration → LLM client: requests generation
- LLM client → Groq API: calls
- Documents API → Database session: reads records
- Knowledge API → Database session: reads records
- Projects API → Database session: reads records
- Feedback API → Database session: accesses records