# gramosoftai/gsearchai architecture

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

- Interactive diagram: https://gitdiagram.com/gramosoftai/gsearchai
- Repository: https://github.com/gramosoftai/gsearchai

## Overview

GRAG is a self-hosted, multi-tenant enterprise search and Graph RAG platform. Its documented workflow takes unstructured content through ontology-aware ingestion and triplet/vector preparation into Neo4j and PostgreSQL, then performs hybrid retrieval and grounded answer generation. The graph also preserves documented table analytics, ontology, and tenant-isolation capabilities. Source excerpts and the SOURCE INDEX support several implementation links; other branches are included from README claims with documented edges. Some subsystem internals were not sampled, so their implementation-level connections are not inferred.

Main entry points: [`app/modules/knowledge_bases/service.py`](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/service.py) (Ingestion Service), [`app/modules/rag/pipeline.py`](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/pipeline.py) (Hybrid Retrieval), [`app/core/database.py`](https://github.com/gramosoftai/gsearchai/blob/main/app/core/database.py) (PostgreSQL), [`app/core/neo4j_repository.py`](https://github.com/gramosoftai/gsearchai/blob/main/app/core/neo4j_repository.py) (Tenant Graph Repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Knowledge Ingestion"]
  node_kb_api["Knowledge Base API<br/>[routes.py]"]
  node_kb_service["Ingestion Service<br/>[service.py]"]
  node_pdf["PDF Extraction<br/>[pdf_extractor.py]"]
  node_excel["Spreadsheet Ingestion"]
  node_scraper["Web Scraping<br/>[scraper_service.py]"]
  node_connectors["Content Connectors"]
end

subgraph group_knowledge["Knowledge Layer"]
  node_triplets["Triplet Extraction"]
  node_ontology["Ontology Service<br/>[service.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_pg[("PostgreSQL<br/>[database.py]")]
  node_neo_repo["Tenant Graph Repository"]
  node_neo4j[("Neo4j<br/>[neo4j.py]")]
end

subgraph group_search["Search And Answers"]
  node_query_api["Chat API<br/>[routes.py]"]
  node_chat_service["Chat Service<br/>[service.py]"]
  node_query_router["Query Router<br/>[query_router.py]"]
  node_rag["Hybrid Retrieval<br/>[pipeline.py]"]
  node_llm["Answer Generation<br/>[deepinfra_llm.py]"]
  node_analytics["Table Analytics<br/>[pandas_engine.py]"]
end

subgraph group_platform["Platform Services"]
  node_auth["Authentication<br/>[routes.py]"]
  node_tenant["Tenant Isolation<br/>[database.py]"]
  node_frontend["Web Dashboard<br/>[page.tsx]"]
end

node_user(("Enterprise User"))

node_user -->|"submits content"| node_kb_api
node_kb_api -->|"invokes"| node_kb_service
node_kb_service -->|"extracts documents"| node_pdf
node_kb_service -->|"extracts facts"| node_triplets
node_kb_service -->|"creates vectors"| node_embeddings
node_kb_service -->|"writes graph"| node_neo_repo
node_excel -->|"maps schema"| node_ontology
node_kb_service -->|"uses scraper"| node_scraper
node_kb_service -->|"stores metadata"| node_pg
node_neo_repo -->|"executes queries"| node_neo4j
node_kb_service -->|"persists records"| node_pg
node_pg -.->|"stores vectors"| node_rag
node_neo4j -->|"provides graph data"| node_rag
node_user -->|"asks question"| node_query_api
node_query_api -->|"routes request"| node_chat_service
node_chat_service -->|"requests retrieval"| node_rag
node_rag -->|"routes query"| node_query_router
node_rag -->|"retrieves graph"| node_neo_repo
node_rag -->|"searches vectors"| node_embeddings
node_rag -->|"generates answer"| node_llm
node_rag -->|"handles tabular queries"| node_analytics
node_user -.->|"authenticates"| node_auth
node_tenant -->|"enforces RLS"| node_pg
node_frontend -.->|"sends chat"| node_query_api

click node_kb_api "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/routes.py"
click node_kb_service "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/service.py"
click node_pdf "https://github.com/gramosoftai/gsearchai/blob/main/app/core/pdf_extractor.py"
click node_excel "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/services/excel_ingestion_service.py"
click node_scraper "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/services/scraper_service.py"
click node_connectors "https://github.com/gramosoftai/gsearchai/tree/main/app/modules/connectors"
click node_triplets "https://github.com/gramosoftai/gsearchai/blob/main/app/core/triplet_extractor.py"
click node_ontology "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/ontology/service.py"
click node_embeddings "https://github.com/gramosoftai/gsearchai/blob/main/app/core/embeddings.py"
click node_pg "https://github.com/gramosoftai/gsearchai/blob/main/app/core/database.py"
click node_neo_repo "https://github.com/gramosoftai/gsearchai/blob/main/app/core/neo4j_repository.py"
click node_neo4j "https://github.com/gramosoftai/gsearchai/blob/main/app/core/neo4j.py"
click node_query_api "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/chats/routes.py"
click node_chat_service "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/chats/service.py"
click node_query_router "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/query_router.py"
click node_rag "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/pipeline.py"
click node_llm "https://github.com/gramosoftai/gsearchai/blob/main/app/core/llm/deepinfra_llm.py"
click node_analytics "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/pandas_engine.py"
click node_auth "https://github.com/gramosoftai/gsearchai/blob/main/app/modules/auth/routes.py"
click node_tenant "https://github.com/gramosoftai/gsearchai/blob/main/app/core/database.py"
click node_frontend "https://github.com/gramosoftai/gsearchai/blob/main/frontend/Grag-g-soft/app/dashboard/conversation/page.tsx"

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_kb_api,node_kb_service,node_pdf,node_excel,node_scraper,node_connectors,node_user toneBlue
class node_triplets,node_ontology,node_embeddings,node_pg,node_neo_repo,node_neo4j toneAmber
class node_query_api,node_chat_service,node_query_router,node_rag,node_llm,node_analytics toneMint
class node_auth,node_tenant,node_frontend toneRose
```

## Components

### Knowledge Ingestion

- [Knowledge Base API](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/routes.py): `app/modules/knowledge_bases/routes.py`
- [Ingestion Service](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/service.py): `app/modules/knowledge_bases/service.py`
- [PDF Extraction](https://github.com/gramosoftai/gsearchai/blob/main/app/core/pdf_extractor.py): `app/core/pdf_extractor.py`
- [Spreadsheet Ingestion](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/services/excel_ingestion_service.py): `app/modules/knowledge_bases/services/excel_ingestion_service.py`
- [Web Scraping](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/knowledge_bases/services/scraper_service.py): `app/modules/knowledge_bases/services/scraper_service.py`
- [Content Connectors](https://github.com/gramosoftai/gsearchai/tree/main/app/modules/connectors): `app/modules/connectors`

### Knowledge Layer

- [Triplet Extraction](https://github.com/gramosoftai/gsearchai/blob/main/app/core/triplet_extractor.py): `app/core/triplet_extractor.py`
- [Ontology Service](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/ontology/service.py): `app/modules/ontology/service.py`
- [Embeddings](https://github.com/gramosoftai/gsearchai/blob/main/app/core/embeddings.py): `app/core/embeddings.py`
- [PostgreSQL](https://github.com/gramosoftai/gsearchai/blob/main/app/core/database.py): `app/core/database.py`
- [Tenant Graph Repository](https://github.com/gramosoftai/gsearchai/blob/main/app/core/neo4j_repository.py): `app/core/neo4j_repository.py`
- [Neo4j](https://github.com/gramosoftai/gsearchai/blob/main/app/core/neo4j.py): `app/core/neo4j.py`

### Search And Answers

- [Chat API](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/chats/routes.py): `app/modules/chats/routes.py`
- [Chat Service](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/chats/service.py): `app/modules/chats/service.py`
- [Query Router](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/query_router.py): `app/modules/rag/query_router.py`
- [Hybrid Retrieval](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/pipeline.py): `app/modules/rag/pipeline.py`
- [Answer Generation](https://github.com/gramosoftai/gsearchai/blob/main/app/core/llm/deepinfra_llm.py): `app/core/llm/deepinfra_llm.py`
- [Table Analytics](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/rag/pandas_engine.py): `app/modules/rag/pandas_engine.py`

### Platform Services

- [Authentication](https://github.com/gramosoftai/gsearchai/blob/main/app/modules/auth/routes.py): `app/modules/auth/routes.py`
- [Tenant Isolation](https://github.com/gramosoftai/gsearchai/blob/main/app/core/database.py): `app/core/database.py`
- [Web Dashboard](https://github.com/gramosoftai/gsearchai/blob/main/frontend/Grag-g-soft/app/dashboard/conversation/page.tsx): `frontend/Grag-g-soft/app/dashboard/conversation/page.tsx`

### Other components

- **Enterprise User**

## Connections

- Enterprise User → Knowledge Base API: submits content (evidence: `README.md`)
- Knowledge Base API → Ingestion Service: invokes (evidence: `app/modules/knowledge_bases/routes.py`)
- Ingestion Service → PDF Extraction: extracts documents (evidence: `app/modules/knowledge_bases/service.py`)
- Ingestion Service → Triplet Extraction: extracts facts (evidence: `app/modules/knowledge_bases/service.py`)
- Ingestion Service → Embeddings: creates vectors (evidence: `app/modules/knowledge_bases/service.py`)
- Ingestion Service → Tenant Graph Repository: writes graph (evidence: `app/modules/knowledge_bases/service.py`)
- Spreadsheet Ingestion → Ontology Service: maps schema (evidence: `app/modules/knowledge_bases/services/excel_ingestion_service.py`)
- Ingestion Service → Web Scraping: uses scraper (evidence: `app/modules/knowledge_bases/service.py`)
- Ingestion Service → PostgreSQL: stores metadata (evidence: `app/modules/knowledge_bases/service.py`)
- Tenant Graph Repository → Neo4j: executes queries (evidence: `app/core/neo4j_repository.py`)
- Ingestion Service → PostgreSQL: persists records (evidence: `app/modules/knowledge_bases/service.py`)
- PostgreSQL → Hybrid Retrieval: stores vectors (evidence: `README.md`)
- Neo4j → Hybrid Retrieval: provides graph data (evidence: `README.md`)
- Enterprise User → Chat API: asks question (evidence: `README.md`)
- Chat API → Chat Service: routes request (evidence: `app/modules/chats/routes.py`)
- Chat Service → Hybrid Retrieval: requests retrieval (evidence: `app/modules/chats/service.py`)
- Hybrid Retrieval → Query Router: routes query (evidence: `app/modules/rag/pipeline.py`)
- Hybrid Retrieval → Tenant Graph Repository: retrieves graph (evidence: `app/modules/rag/pipeline.py`)
- Hybrid Retrieval → Embeddings: searches vectors (evidence: `app/modules/rag/pipeline.py`)
- Hybrid Retrieval → Answer Generation: generates answer (evidence: `app/modules/rag/pipeline.py`)
- Hybrid Retrieval → Table Analytics: handles tabular queries (evidence: `app/modules/rag/pipeline.py`)
- Enterprise User → Authentication: authenticates (evidence: `README.md`)
- Tenant Isolation → PostgreSQL: enforces RLS (evidence: `app/core/database.py`)
- Web Dashboard → Chat API: sends chat
