# abhinavalwala/enterprise-ai-search architecture

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

- Interactive diagram: https://gitdiagram.com/abhinavalwala/enterprise-ai-search
- Repository: https://github.com/abhinavalwala/enterprise-ai-search

## Overview

This is an evaluated retrieval and RAG platform. The serving workflow runs from an HTTP request through the API/service boundary, permission-aware hybrid retrieval, reranking, and either search results or evidence-grounded generation with citation checks; request tracing and bounded metrics observe requests. A separate privileged CLI supports corpus preparation and scientific comparisons, including claim verification. The graph preserves the documented evaluation and safety branches. Some service/API and evaluation internals are unsampled; those connections rely on the README or SOURCE INDEX references, not inspection of the full modules.

Main entry points: [`src/enterprise_ai_search/service.py`](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/service.py) (Search service), [`src/enterprise_ai_search/cli.py`](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/cli.py) (Scientific CLI), [`src/enterprise_ai_search/rag.py`](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/rag.py) (RAG and citations), [`src/enterprise_ai_search/bm25.py`](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/bm25.py) (BM25 index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Serving"]
  node_api["FastAPI<br/>[api.py]"]
  node_service["Search service<br/>[service.py]"]
end

subgraph group_retrieval["Retrieval"]
  node_text["Chunking and text<br/>[text.py]"]
  node_models["Document models<br/>[models.py]"]
  node_bm25["BM25 index<br/>[bm25.py]"]
  node_dense["Dense index<br/>[dense.py]"]
  node_hybrid["Hybrid fusion<br/>[hybrid.py]"]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
end

subgraph group_rag["RAG and verification"]
  node_rag["RAG and citations<br/>[rag.py]"]
  node_generator["HTTP generator<br/>[generation.py]"]
  node_claimverify["Claim verification"]
end

subgraph group_data["Corpus and evaluation"]
  node_corpus["Corpus loader<br/>[dataset.py]"]
  node_cli["Scientific CLI<br/>[cli.py]"]
  node_evaluation["Retrieval evaluation<br/>[evaluation.py]"]
  node_comparison["Method comparison<br/>[comparison.py]"]
  node_hybrid_eval["Hybrid evaluation"]
  node_claim_eval["Claim evaluation"]
end

subgraph group_ops["Policy and observability"]
  node_authorization["Authorization policy<br/>[authorization.py]"]
  node_observability["Request observability<br/>[observability.py]"]
end

node_client(("HTTP client"))
node_llm{{"Generation endpoint"}}

node_client -->|"sends requests"| node_api
node_api -->|"dispatches to"| node_service
node_api -->|"records requests"| node_observability
node_service -->|"loads corpus"| node_corpus
node_service -->|"chunks documents"| node_text
node_service -->|"builds index"| node_bm25
node_service -->|"prepares embeddings"| node_dense
node_service -->|"builds index"| node_hybrid
node_service -->|"loads model"| node_reranker
node_service -->|"checks access"| node_authorization
node_service -->|"answers questions"| node_rag
node_service -->|"configures generator"| node_generator
node_service -->|"logs events"| node_observability
node_text -->|"creates chunks"| node_models
node_bm25 -->|"tokenizes text"| node_text
node_bm25 -->|"returns results"| node_models
node_dense -->|"normalizes text"| node_text
node_dense -->|"returns results"| node_models
node_hybrid -->|"retrieves candidates"| node_bm25
node_hybrid -->|"retrieves candidates"| node_dense
node_rag -->|"retrieves evidence"| node_hybrid
node_rag -->|"reranks candidates"| node_reranker
node_rag -->|"sends evidence"| node_generator
node_generator -->|"sends prompt"| node_llm
node_claim_eval -->|"evaluates claims"| node_claimverify
node_claimverify -->|"uses evidence flow"| node_rag
node_claimverify -->|"requests verdict"| node_generator
node_cli -->|"loads datasets"| node_corpus
node_cli -->|"runs evaluation"| node_evaluation
node_cli -->|"compares methods"| node_comparison
node_cli -->|"runs evaluation"| node_hybrid_eval
node_cli -->|"runs evaluation"| node_claim_eval
node_comparison -->|"uses metrics"| node_evaluation
node_hybrid_eval -->|"uses metrics"| node_evaluation
node_claim_eval -->|"loads claims"| node_corpus

click node_api "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/api.py"
click node_service "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/service.py"
click node_corpus "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/dataset.py"
click node_text "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/text.py"
click node_models "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/models.py"
click node_bm25 "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/bm25.py"
click node_dense "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/dense.py"
click node_hybrid "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/hybrid.py"
click node_reranker "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/reranker.py"
click node_authorization "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/authorization.py"
click node_rag "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/rag.py"
click node_generator "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/generation.py"
click node_claimverify "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/claim_verification.py"
click node_observability "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/observability.py"
click node_cli "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/cli.py"
click node_evaluation "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/evaluation.py"
click node_comparison "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/comparison.py"
click node_hybrid_eval "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/hybrid_evaluation.py"
click node_claim_eval "https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/claim_evaluation.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_api,node_service,node_client toneBlue
class node_text,node_models,node_bm25,node_dense,node_hybrid,node_reranker toneAmber
class node_rag,node_generator,node_claimverify toneMint
class node_corpus,node_cli,node_evaluation,node_comparison,node_hybrid_eval,node_claim_eval toneRose
class node_authorization,node_observability,node_llm toneIndigo
```

## Components

### Serving

- [FastAPI](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/api.py): `src/enterprise_ai_search/api.py`
- [Search service](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/service.py): `src/enterprise_ai_search/service.py`

### Retrieval

- [Chunking and text](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/text.py): `src/enterprise_ai_search/text.py`
- [Document models](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/models.py): `src/enterprise_ai_search/models.py`
- [BM25 index](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/bm25.py): `src/enterprise_ai_search/bm25.py`
- [Dense index](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/dense.py): `src/enterprise_ai_search/dense.py`
- [Hybrid fusion](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/hybrid.py): `src/enterprise_ai_search/hybrid.py`
- [Cross-encoder reranker](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/reranker.py): `src/enterprise_ai_search/reranker.py`

### RAG and verification

- [RAG and citations](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/rag.py): `src/enterprise_ai_search/rag.py`
- [HTTP generator](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/generation.py): `src/enterprise_ai_search/generation.py`
- [Claim verification](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/claim_verification.py): `src/enterprise_ai_search/claim_verification.py`

### Corpus and evaluation

- [Corpus loader](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/dataset.py): `src/enterprise_ai_search/dataset.py`
- [Scientific CLI](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/cli.py): `src/enterprise_ai_search/cli.py`
- [Retrieval evaluation](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/evaluation.py): `src/enterprise_ai_search/evaluation.py`
- [Method comparison](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/comparison.py): `src/enterprise_ai_search/comparison.py`
- [Hybrid evaluation](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/hybrid_evaluation.py): `src/enterprise_ai_search/hybrid_evaluation.py`
- [Claim evaluation](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/claim_evaluation.py): `src/enterprise_ai_search/claim_evaluation.py`

### Policy and observability

- [Authorization policy](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/authorization.py): `src/enterprise_ai_search/authorization.py`
- [Request observability](https://github.com/abhinavalwala/enterprise-ai-search/blob/main/src/enterprise_ai_search/observability.py): `src/enterprise_ai_search/observability.py`

### Other components

- **HTTP client**
- **Generation endpoint**

## Connections

- HTTP client → FastAPI: sends requests (evidence: `README.md`)
- FastAPI → Search service: dispatches to (evidence: `src/enterprise_ai_search/api.py`)
- FastAPI → Request observability: records requests (evidence: `src/enterprise_ai_search/api.py`)
- Search service → Corpus loader: loads corpus (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Chunking and text: chunks documents (evidence: `src/enterprise_ai_search/service.py`)
- Search service → BM25 index: builds index (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Dense index: prepares embeddings (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Hybrid fusion: builds index (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Cross-encoder reranker: loads model (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Authorization policy: checks access (evidence: `src/enterprise_ai_search/service.py`)
- Search service → RAG and citations: answers questions (evidence: `src/enterprise_ai_search/service.py`)
- Search service → HTTP generator: configures generator (evidence: `src/enterprise_ai_search/service.py`)
- Search service → Request observability: logs events (evidence: `src/enterprise_ai_search/service.py`)
- Chunking and text → Document models: creates chunks (evidence: `src/enterprise_ai_search/text.py`)
- BM25 index → Chunking and text: tokenizes text (evidence: `src/enterprise_ai_search/bm25.py`)
- BM25 index → Document models: returns results (evidence: `src/enterprise_ai_search/bm25.py`)
- Dense index → Chunking and text: normalizes text (evidence: `src/enterprise_ai_search/dense.py`)
- Dense index → Document models: returns results (evidence: `src/enterprise_ai_search/dense.py`)
- Hybrid fusion → BM25 index: retrieves candidates (evidence: `src/enterprise_ai_search/hybrid.py`)
- Hybrid fusion → Dense index: retrieves candidates (evidence: `src/enterprise_ai_search/hybrid.py`)
- RAG and citations → Hybrid fusion: retrieves evidence (evidence: `src/enterprise_ai_search/rag.py`)
- RAG and citations → Cross-encoder reranker: reranks candidates (evidence: `src/enterprise_ai_search/rag.py`)
- RAG and citations → HTTP generator: sends evidence (evidence: `src/enterprise_ai_search/rag.py`)
- HTTP generator → Generation endpoint: sends prompt (evidence: `src/enterprise_ai_search/generation.py`)
- Claim evaluation → Claim verification: evaluates claims (evidence: `src/enterprise_ai_search/claim_evaluation.py`)
- Claim verification → RAG and citations: uses evidence flow (evidence: `src/enterprise_ai_search/claim_verification.py`)
- Claim verification → HTTP generator: requests verdict (evidence: `src/enterprise_ai_search/claim_verification.py`)
- Scientific CLI → Corpus loader: loads datasets (evidence: `src/enterprise_ai_search/cli.py`)
- Scientific CLI → Retrieval evaluation: runs evaluation (evidence: `src/enterprise_ai_search/cli.py`)
- Scientific CLI → Method comparison: compares methods (evidence: `src/enterprise_ai_search/cli.py`)
- Scientific CLI → Hybrid evaluation: runs evaluation (evidence: `src/enterprise_ai_search/cli.py`)
- Scientific CLI → Claim evaluation: runs evaluation (evidence: `src/enterprise_ai_search/cli.py`)
- Method comparison → Retrieval evaluation: uses metrics (evidence: `src/enterprise_ai_search/comparison.py`)
- Hybrid evaluation → Retrieval evaluation: uses metrics (evidence: `src/enterprise_ai_search/hybrid_evaluation.py`)
- Claim evaluation → Corpus loader: loads claims (evidence: `src/enterprise_ai_search/claim_evaluation.py`)
