# abdulhaq6920/fikra-ai architecture

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

- Interactive diagram: https://gitdiagram.com/abdulhaq6920/fikra-ai
- Repository: https://github.com/abdulhaq6920/fikra-ai

## Overview

FIKRA AI is a multi-tenant RAG chatbot: organization members upload documents for asynchronous indexing, then ask questions and receive answers grounded in retrieved passages with validated citations. The map also includes authentication, administration, analytics, and the ingestion and retrieval layers. The README documents the end-to-end worker and infrastructure flow; source excerpts clarify key service calls. Some route and frontend internals were not sampled, so those links are limited to documented relationships.

Main entry points: [`backend/app/api/router.py`](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/router.py) (API router), [`backend/app/workers/document_tasks.py`](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/workers/document_tasks.py) (Document worker), [`frontend/src/app/layout.tsx`](https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/layout.tsx) (Next.js application), [`backend/app/db/session.py`](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/db/session.py) (PostgreSQL and pgvector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web application"]
  node_web["Next.js application<br/>[layout.tsx]"]
  node_chatui["Chat interface<br/>[page.tsx]"]
  node_docsui["Documents interface<br/>[page.tsx]"]
  node_adminui["Admin and analytics<br/>[page.tsx]"]
end

subgraph group_api["API and identity"]
  node_router["API router<br/>[router.py]"]
  node_auth["Authentication routes<br/>[auth.py]"]
  node_authservice["Auth service<br/>[auth_service.py]"]
  node_dependencies["Auth dependencies<br/>[dependencies.py]"]
  node_documents["Document routes<br/>[documents.py]"]
  node_chat["Chat routes<br/>[chat.py]"]
  node_adminroutes["Admin and analytics routes<br/>[admin.py]"]
  node_insightroutes["Insights routes<br/>[admin_insights.py]"]
  node_insights["Insights service"]
end

subgraph group_ingestion["Document ingestion"]
  node_worker["Document worker<br/>[document_tasks.py]"]
  node_ingestionservice["Extraction and chunking"]
  node_storage["Local file storage<br/>[local_storage.py]"]
end

subgraph group_rag["Grounded answers"]
  node_ragservice["RAG orchestration<br/>[rag_service.py]"]
  node_retrieval["Hybrid retrieval"]
end

subgraph group_infra["Data and providers"]
  node_db[("PostgreSQL and pgvector<br/>[session.py]")]
  node_embeddings["Embedding provider<br/>[embeddings.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_llm["LLM provider interface<br/>[llm.py]"]
end

node_members(("Organization members"))
node_groq["Groq API"]
node_ollama["Ollama service"]
node_redis["Redis and Celery queue"]

node_members -->|"uses"| node_web
node_web -->|"calls API"| node_router
node_router -->|"registers"| node_auth
node_router -->|"registers"| node_chat
node_router -->|"registers"| node_documents
node_router -->|"registers"| node_adminroutes
node_router -->|"registers"| node_insightroutes
node_auth -->|"calls"| node_authservice
node_chat -->|"calls"| node_ragservice
node_insightroutes -->|"calls"| node_insights
node_adminroutes -->|"queries"| node_db
node_documents -.->|"queues ingestion"| node_redis
node_redis -->|"dispatches tasks"| node_worker
node_worker -->|"calls"| node_ingestionservice
node_worker -->|"uses"| node_storage
node_worker -->|"embeds chunks"| node_embeddings
node_worker -->|"persists index"| node_db
node_chatui -.->|"renders in"| node_web
node_docsui -.->|"renders in"| node_web
node_adminui -.->|"renders in"| node_web
node_ragservice -->|"retrieves passages"| node_retrieval
node_retrieval -->|"embeds query"| node_embeddings
node_retrieval -->|"reranks results"| node_reranker
node_retrieval -->|"searches passages"| node_db
node_ragservice -->|"generates answer"| node_llm
node_llm -.->|"uses when configured"| node_groq
node_llm -.->|"uses when configured"| node_ollama
node_ragservice -->|"loads conversation"| node_db
node_auth -->|"uses dependencies"| node_dependencies
node_chat -->|"uses dependencies"| node_dependencies
node_insightroutes -->|"queries"| node_db

click node_web "https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/layout.tsx"
click node_chatui "https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/chat/page.tsx"
click node_docsui "https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/documents/page.tsx"
click node_adminui "https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/admin/page.tsx"
click node_router "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/router.py"
click node_auth "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/auth.py"
click node_authservice "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/auth_service.py"
click node_dependencies "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/dependencies.py"
click node_documents "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/documents.py"
click node_chat "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/chat.py"
click node_adminroutes "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/admin.py"
click node_insightroutes "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/admin_insights.py"
click node_insights "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/insights_service.py"
click node_worker "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/workers/document_tasks.py"
click node_ingestionservice "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/ingestion_service.py"
click node_storage "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/storage/local_storage.py"
click node_ragservice "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/rag_service.py"
click node_retrieval "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/retrieval_service.py"
click node_db "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/db/session.py"
click node_embeddings "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/embeddings.py"
click node_reranker "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/reranker.py"
click node_llm "https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/llm.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_web,node_chatui,node_docsui,node_adminui toneBlue
class node_router,node_auth,node_authservice,node_dependencies,node_documents,node_chat,node_adminroutes,node_insightroutes,node_insights,node_redis toneAmber
class node_worker,node_ingestionservice,node_storage,node_groq toneMint
class node_ragservice,node_retrieval toneRose
class node_db,node_embeddings,node_reranker,node_llm,node_members,node_ollama toneIndigo
```

## Components

### Web application

- [Next.js application](https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/layout.tsx): `frontend/src/app/layout.tsx`
- [Chat interface](https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/chat/page.tsx): `frontend/src/app/(protected)/chat/page.tsx`
- [Documents interface](https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/documents/page.tsx): `frontend/src/app/(protected)/documents/page.tsx`
- [Admin and analytics](https://github.com/abdulhaq6920/fikra-ai/blob/main/frontend/src/app/(protected)/admin/page.tsx): `frontend/src/app/(protected)/admin/page.tsx`

### API and identity

- [API router](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Authentication routes](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [Auth service](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/auth_service.py): `backend/app/services/auth_service.py`
- [Auth dependencies](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/dependencies.py): `backend/app/api/dependencies.py`
- [Document routes](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/documents.py): `backend/app/api/v1/documents.py`
- [Chat routes](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [Admin and analytics routes](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/admin.py): `backend/app/api/v1/admin.py`
- [Insights routes](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/api/v1/admin_insights.py): `backend/app/api/v1/admin_insights.py`
- [Insights service](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/insights_service.py): `backend/app/services/insights_service.py`

### Document ingestion

- [Document worker](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/workers/document_tasks.py): `backend/app/workers/document_tasks.py`
- [Extraction and chunking](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/ingestion_service.py): `backend/app/services/ingestion_service.py`
- [Local file storage](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/storage/local_storage.py): `backend/app/storage/local_storage.py`

### Grounded answers

- [RAG orchestration](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/rag_service.py): `backend/app/services/rag_service.py`
- [Hybrid retrieval](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`

### Data and providers

- [PostgreSQL and pgvector](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/db/session.py): `backend/app/db/session.py`
- [Embedding provider](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/embeddings.py): `backend/app/providers/embeddings.py`
- [Cross-encoder reranker](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/reranker.py): `backend/app/providers/reranker.py`
- [LLM provider interface](https://github.com/abdulhaq6920/fikra-ai/blob/main/backend/app/providers/llm.py): `backend/app/providers/llm.py`

### Other components

- **Organization members**
- **Groq API**
- **Ollama service**
- **Redis and Celery queue**

## Connections

- Organization members → Next.js application: uses (evidence: `README.md`)
- Next.js application → API router: calls API (evidence: `README.md`)
- API router → Authentication routes: registers (evidence: `backend/app/api/router.py`)
- API router → Chat routes: registers (evidence: `backend/app/api/router.py`)
- API router → Document routes: registers (evidence: `backend/app/api/router.py`)
- API router → Admin and analytics routes: registers (evidence: `backend/app/api/router.py`)
- API router → Insights routes: registers (evidence: `backend/app/api/router.py`)
- Authentication routes → Auth service: calls (evidence: `backend/app/api/v1/auth.py`)
- Chat routes → RAG orchestration: calls (evidence: `backend/app/api/v1/chat.py`)
- Insights routes → Insights service: calls (evidence: `backend/app/api/v1/admin_insights.py`)
- Admin and analytics routes → PostgreSQL and pgvector: queries (evidence: `backend/app/api/v1/admin.py`)
- Document routes → Redis and Celery queue: queues ingestion (evidence: `README.md`)
- Redis and Celery queue → Document worker: dispatches tasks (evidence: `README.md`)
- Document worker → Extraction and chunking: calls (evidence: `backend/app/workers/document_tasks.py`)
- Document worker → Local file storage: uses (evidence: `backend/app/workers/document_tasks.py`)
- Document worker → Embedding provider: embeds chunks (evidence: `backend/app/workers/document_tasks.py`)
- Document worker → PostgreSQL and pgvector: persists index (evidence: `README.md`)
- Chat interface → Next.js application: renders in
- Documents interface → Next.js application: renders in
- Admin and analytics → Next.js application: renders in
- RAG orchestration → Hybrid retrieval: retrieves passages (evidence: `backend/app/services/rag_service.py`)
- Hybrid retrieval → Embedding provider: embeds query (evidence: `backend/app/services/retrieval_service.py`)
- Hybrid retrieval → Cross-encoder reranker: reranks results (evidence: `backend/app/services/retrieval_service.py`)
- Hybrid retrieval → PostgreSQL and pgvector: searches passages (evidence: `backend/app/services/retrieval_service.py`)
- RAG orchestration → LLM provider interface: generates answer (evidence: `backend/app/services/rag_service.py`)
- LLM provider interface → Groq API: uses when configured (evidence: `README.md`)
- LLM provider interface → Ollama service: uses when configured (evidence: `README.md`)
- RAG orchestration → PostgreSQL and pgvector: loads conversation (evidence: `backend/app/services/rag_service.py`)
- Authentication routes → Auth dependencies: uses dependencies (evidence: `backend/app/api/v1/auth.py`)
- Chat routes → Auth dependencies: uses dependencies (evidence: `backend/app/api/v1/chat.py`)
- Insights routes → PostgreSQL and pgvector: queries (evidence: `backend/app/api/v1/admin_insights.py`)