# shakilahmmed/contextforge architecture

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

- Interactive diagram: https://gitdiagram.com/shakilahmmed/contextforge
- Repository: https://github.com/shakilahmmed/contextforge

## Overview

ContextForge is a multi-tenant RAG platform with a React client and FastAPI backend. Users create a tenant, register and authenticate, upload documents, and chat against indexed content. Uploads are stored and queued; a separate worker extracts text, masks PII, chunks it, and indexes it for retrieval. The API also supports tenant-scoped document listing and chunk visualization. The graph reflects documented architecture and indexed or excerpted references; several frontend API calls and unsampled subsystem details are not verified here.

Main entry points: [`frontend/src/App.tsx`](https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/App.tsx) (Route app), [`app/api/v1.py`](https://github.com/shakilahmmed/contextforge/blob/master/app/api/v1.py) (API router), [`app/services/ingestion_service.py`](https://github.com/shakilahmmed/contextforge/blob/master/app/services/ingestion_service.py) (Ingestion pipeline), [`app/db.py`](https://github.com/shakilahmmed/contextforge/blob/master/app/db.py) (SQL database)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Route app<br/>[App.tsx]"]
  node_authui["Auth pages"]
  node_tenantui["Tenant setup"]
  node_docui["Document pages"]
  node_chatui["Chat page<br/>[ChatPage.tsx]"]
end

subgraph group_api["API and identity"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_router["API router<br/>[v1.py]"]
  node_auth["Authentication<br/>[auth_controller.py]"]
  node_identity["Auth dependencies<br/>[deps.py]"]
  node_tenants["Tenant endpoints"]
end

subgraph group_content["Documents and ingestion"]
  node_documents["Document endpoints"]
  node_docservice["Upload service"]
  node_worker["Ingestion worker<br/>[worker.py]"]
  node_ingest["Ingestion pipeline"]
  node_extract["Text extraction<br/>[text_extraction.py]"]
  node_pii["PII masking<br/>[pii.py]"]
end

subgraph group_rag["Retrieval and chat"]
  node_chat["Chat service<br/>[chat_service.py]"]
  node_vectors["Vector store<br/>[vectorstore.py]"]
  node_llm["Language model<br/>[llm.py]"]
  node_embedding["Embeddings<br/>[embeddings.py]"]
end

subgraph group_platform["Persistence and services"]
  node_db[("SQL database<br/>[db.py]")]
  node_models["Domain models<br/>[document.py]"]
  node_storage["Object storage<br/>[storage.py]"]
  node_queue["Ingestion queue<br/>[queue.py]"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_s3[("S3-compatible store")]
node_sqs["SQS-compatible queue"]
node_qdrant[("Qdrant")]

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_authui
node_webapp -->|"routes to"| node_tenantui
node_webapp -->|"routes to"| node_docui
node_webapp -->|"routes to"| node_chatui
node_webapp -->|"calls API"| node_apiapp
node_apiapp -->|"registers"| node_router
node_router -->|"routes to"| node_auth
node_router -->|"routes to"| node_tenants
node_router -->|"routes to"| node_documents
node_router -->|"routes to"| node_chat
node_auth -->|"uses dependency"| node_identity
node_auth -->|"queries"| node_db
node_tenants -->|"queries"| node_db
node_documents -->|"uploads through"| node_docservice
node_documents -->|"queries"| node_db
node_documents -->|"reads chunks"| node_vectors
node_docservice -->|"stores files"| node_storage
node_docservice -->|"enqueues work"| node_queue
node_worker -->|"consumes"| node_queue
node_worker -->|"invokes"| node_ingest
node_ingest -->|"reads file"| node_storage
node_ingest -->|"extracts text"| node_extract
node_ingest -->|"masks text"| node_pii
node_ingest -->|"indexes chunks"| node_vectors
node_chat -->|"retrieves context"| node_vectors
node_chat -->|"embeds query"| node_embedding
node_chat -->|"generates answer"| node_llm
node_db -->|"connects to"| node_postgres
node_storage -->|"stores objects"| node_s3
node_queue -->|"dispatches messages"| node_sqs
node_vectors -->|"indexes vectors"| node_qdrant
node_db -->|"maps entities"| node_models

click node_webapp "https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/App.tsx"
click node_authui "https://github.com/shakilahmmed/contextforge/tree/master/frontend/src/features/auth"
click node_tenantui "https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/features/tenants/CreateTenantPage.tsx"
click node_docui "https://github.com/shakilahmmed/contextforge/tree/master/frontend/src/features/documents"
click node_chatui "https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/features/chat/ChatPage.tsx"
click node_apiapp "https://github.com/shakilahmmed/contextforge/blob/master/app/main.py"
click node_router "https://github.com/shakilahmmed/contextforge/blob/master/app/api/v1.py"
click node_auth "https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/auth_controller.py"
click node_identity "https://github.com/shakilahmmed/contextforge/blob/master/app/api/deps.py"
click node_tenants "https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/tenant_controller.py"
click node_documents "https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/document_controller.py"
click node_docservice "https://github.com/shakilahmmed/contextforge/blob/master/app/services/document_service.py"
click node_worker "https://github.com/shakilahmmed/contextforge/blob/master/app/worker.py"
click node_ingest "https://github.com/shakilahmmed/contextforge/blob/master/app/services/ingestion_service.py"
click node_extract "https://github.com/shakilahmmed/contextforge/blob/master/app/services/text_extraction.py"
click node_chat "https://github.com/shakilahmmed/contextforge/blob/master/app/services/chat_service.py"
click node_vectors "https://github.com/shakilahmmed/contextforge/blob/master/app/core/vectorstore.py"
click node_llm "https://github.com/shakilahmmed/contextforge/blob/master/app/core/llm.py"
click node_db "https://github.com/shakilahmmed/contextforge/blob/master/app/db.py"
click node_models "https://github.com/shakilahmmed/contextforge/blob/master/app/models/document.py"
click node_storage "https://github.com/shakilahmmed/contextforge/blob/master/app/core/storage.py"
click node_queue "https://github.com/shakilahmmed/contextforge/blob/master/app/core/queue.py"
click node_pii "https://github.com/shakilahmmed/contextforge/blob/master/app/core/pii.py"
click node_embedding "https://github.com/shakilahmmed/contextforge/blob/master/app/core/embeddings.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_webapp,node_authui,node_tenantui,node_docui,node_chatui,node_user toneBlue
class node_apiapp,node_router,node_auth,node_identity,node_tenants,node_postgres,node_s3,node_qdrant toneAmber
class node_documents,node_docservice,node_worker,node_ingest,node_extract,node_pii toneMint
class node_chat,node_vectors,node_llm,node_embedding,node_sqs toneRose
class node_db,node_models,node_storage,node_queue toneIndigo
```

## Components

### Web client

- [Route app](https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth pages](https://github.com/shakilahmmed/contextforge/tree/master/frontend/src/features/auth): `frontend/src/features/auth`
- [Tenant setup](https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/features/tenants/CreateTenantPage.tsx): `frontend/src/features/tenants/CreateTenantPage.tsx`
- [Document pages](https://github.com/shakilahmmed/contextforge/tree/master/frontend/src/features/documents): `frontend/src/features/documents`
- [Chat page](https://github.com/shakilahmmed/contextforge/blob/master/frontend/src/features/chat/ChatPage.tsx): `frontend/src/features/chat/ChatPage.tsx`

### API and identity

- [FastAPI app](https://github.com/shakilahmmed/contextforge/blob/master/app/main.py): `app/main.py`
- [API router](https://github.com/shakilahmmed/contextforge/blob/master/app/api/v1.py): `app/api/v1.py`
- [Authentication](https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/auth_controller.py): `app/controllers/auth_controller.py`
- [Auth dependencies](https://github.com/shakilahmmed/contextforge/blob/master/app/api/deps.py): `app/api/deps.py`
- [Tenant endpoints](https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/tenant_controller.py): `app/controllers/tenant_controller.py`

### Documents and ingestion

- [Document endpoints](https://github.com/shakilahmmed/contextforge/blob/master/app/controllers/document_controller.py): `app/controllers/document_controller.py`
- [Upload service](https://github.com/shakilahmmed/contextforge/blob/master/app/services/document_service.py): `app/services/document_service.py`
- [Ingestion worker](https://github.com/shakilahmmed/contextforge/blob/master/app/worker.py): `app/worker.py`
- [Ingestion pipeline](https://github.com/shakilahmmed/contextforge/blob/master/app/services/ingestion_service.py): `app/services/ingestion_service.py`
- [Text extraction](https://github.com/shakilahmmed/contextforge/blob/master/app/services/text_extraction.py): `app/services/text_extraction.py`
- [PII masking](https://github.com/shakilahmmed/contextforge/blob/master/app/core/pii.py): `app/core/pii.py`

### Retrieval and chat

- [Chat service](https://github.com/shakilahmmed/contextforge/blob/master/app/services/chat_service.py): `app/services/chat_service.py`
- [Vector store](https://github.com/shakilahmmed/contextforge/blob/master/app/core/vectorstore.py): `app/core/vectorstore.py`
- [Language model](https://github.com/shakilahmmed/contextforge/blob/master/app/core/llm.py): `app/core/llm.py`
- [Embeddings](https://github.com/shakilahmmed/contextforge/blob/master/app/core/embeddings.py): `app/core/embeddings.py`

### Persistence and services

- [SQL database](https://github.com/shakilahmmed/contextforge/blob/master/app/db.py): `app/db.py`
- [Domain models](https://github.com/shakilahmmed/contextforge/blob/master/app/models/document.py): `app/models/document.py`
- [Object storage](https://github.com/shakilahmmed/contextforge/blob/master/app/core/storage.py): `app/core/storage.py`
- [Ingestion queue](https://github.com/shakilahmmed/contextforge/blob/master/app/core/queue.py): `app/core/queue.py`

### Other components

- **User**
- **PostgreSQL**
- **S3-compatible store**
- **SQS-compatible queue**
- **Qdrant**

## Connections

- User → Route app: uses (evidence: `README.md`)
- Route app → Auth pages: routes to (evidence: `frontend/src/App.tsx`)
- Route app → Tenant setup: routes to (evidence: `frontend/src/App.tsx`)
- Route app → Document pages: routes to (evidence: `frontend/src/App.tsx`)
- Route app → Chat page: routes to (evidence: `frontend/src/App.tsx`)
- Route app → FastAPI app: calls API (evidence: `README.md`)
- FastAPI app → API router: registers (evidence: `app/main.py`)
- API router → Authentication: routes to (evidence: `app/api/v1.py`)
- API router → Tenant endpoints: routes to (evidence: `app/api/v1.py`)
- API router → Document endpoints: routes to (evidence: `app/api/v1.py`)
- API router → Chat service: routes to (evidence: `app/api/v1.py`)
- Authentication → Auth dependencies: uses dependency (evidence: `app/controllers/auth_controller.py`)
- Authentication → SQL database: queries (evidence: `app/controllers/auth_controller.py`)
- Tenant endpoints → SQL database: queries (evidence: `app/controllers/tenant_controller.py`)
- Document endpoints → Upload service: uploads through (evidence: `app/controllers/document_controller.py`)
- Document endpoints → SQL database: queries (evidence: `app/controllers/document_controller.py`)
- Document endpoints → Vector store: reads chunks (evidence: `app/controllers/document_controller.py`)
- Upload service → Object storage: stores files (evidence: `app/services/document_service.py`)
- Upload service → Ingestion queue: enqueues work (evidence: `app/services/document_service.py`)
- Ingestion worker → Ingestion queue: consumes (evidence: `app/worker.py`)
- Ingestion worker → Ingestion pipeline: invokes (evidence: `app/worker.py`)
- Ingestion pipeline → Object storage: reads file (evidence: `app/services/ingestion_service.py`)
- Ingestion pipeline → Text extraction: extracts text (evidence: `app/services/ingestion_service.py`)
- Ingestion pipeline → PII masking: masks text (evidence: `app/services/ingestion_service.py`)
- Ingestion pipeline → Vector store: indexes chunks (evidence: `app/services/ingestion_service.py`)
- Chat service → Vector store: retrieves context (evidence: `app/services/chat_service.py`)
- Chat service → Embeddings: embeds query (evidence: `app/services/chat_service.py`)
- Chat service → Language model: generates answer (evidence: `app/services/chat_service.py`)
- SQL database → PostgreSQL: connects to (evidence: `README.md`)
- Object storage → S3-compatible store: stores objects (evidence: `app/core/storage.py`)
- Ingestion queue → SQS-compatible queue: dispatches messages (evidence: `README.md`)
- Vector store → Qdrant: indexes vectors (evidence: `README.md`)
- SQL database → Domain models: maps entities (evidence: `app/models/document.py`)