# mustafaahmed007/adaptiverag-x architecture

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

- Interactive diagram: https://gitdiagram.com/mustafaahmed007/adaptiverag-x
- Repository: https://github.com/mustafaahmed007/adaptiverag-x

## Overview

AdaptiveRAG-X is a local-first adaptive RAG platform. A user submits a query through the HTTP API; security checks and planning guide retrieval, evidence evaluation and bounded rewrites, then grounded generation returns an answer with citations and trace metadata. Separate capabilities handle document ingestion, multi-aspect research, durable storage, and operational evaluation. The pipeline and core retriever implementations are excerpted; several other relationships and the API’s internal routing are supported only by README or source-index references, so those links are limited accordingly.

Main entry points: [`adaptive_rag/pipeline.py`](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/pipeline.py) (Adaptive pipeline), [`adaptive_rag/api.py`](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/api.py) (HTTP API), [`adaptive_rag/retrieval/hybrid.py`](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/hybrid.py) (Hybrid retrieval), [`adaptive_rag/services.py`](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/services.py) (Ingestion and chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and access"]
  node_api["HTTP API<br/>[api.py]"]
  node_middleware["API middleware<br/>[middleware.py]"]
end

subgraph group_orchestration["Query orchestration"]
  node_contracts["Domain contracts<br/>[models.py]"]
  node_pipeline["Adaptive pipeline<br/>[pipeline.py]"]
  node_security["Security gate<br/>[security.py]"]
  node_planner["Query planner<br/>[planner.py]"]
  node_query["Rewrite and citations<br/>[query.py]"]
  node_generator["Answer generation<br/>[providers.py]"]
end

subgraph group_retrieval["Evidence retrieval"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_memory["Local retrieval<br/>[memory.py]"]
  node_sparse["BM25 retrieval<br/>[sparse.py]"]
  node_graph["Graph retrieval<br/>[graph.py]"]
  node_web["Web retrieval<br/>[web.py]"]
  node_reranker["Evidence reranker<br/>[rerank.py]"]
  node_qdrant["Qdrant adapter<br/>[qdrant.py]"]
  node_embeddings["Embedding providers<br/>[embeddings.py]"]
end

subgraph group_content["Content and research"]
  node_ingestion["Ingestion and chunking<br/>[services.py]"]
  node_storage[("Document storage<br/>[storage.py]")]
  node_research["Multi-aspect research<br/>[research.py]"]
end

subgraph group_operations["Quality and operations"]
  node_evaluation["Evidence evaluation<br/>[evaluation.py]"]
  node_observability["Trace and costs<br/>[observability.py]"]
  node_evaluator["Quality metrics<br/>[evaluation.py]"]
end

node_user(("User"))

node_user -->|"submits query"| node_api
node_api -->|"uses access controls"| node_middleware
node_api -->|"routes queries"| node_pipeline
node_api -->|"routes research"| node_research
node_api -->|"uses ingestion"| node_ingestion
node_pipeline -->|"checks query"| node_security
node_pipeline -->|"builds plan"| node_planner
node_pipeline -->|"rewrites and cites"| node_query
node_pipeline -->|"generates answer"| node_generator
node_pipeline -->|"retrieves evidence"| node_hybrid
node_pipeline -->|"retrieves multi-hop"| node_graph
node_pipeline -->|"retrieves fresh evidence"| node_web
node_pipeline -->|"reranks evidence"| node_reranker
node_pipeline -->|"evaluates evidence"| node_evaluation
node_pipeline -->|"records trace"| node_observability
node_hybrid -->|"queries dense side"| node_memory
node_hybrid -->|"queries sparse side"| node_sparse
node_ingestion -->|"creates documents"| node_contracts
node_research -->|"ingests report sources"| node_ingestion
node_qdrant -->|"embeds content"| node_embeddings
node_pipeline -.->|"may use adapter"| node_qdrant
node_pipeline -.->|"may persist documents"| node_storage
node_pipeline -->|"returns response"| node_contracts
node_api -->|"uses request models"| node_contracts

click node_api "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/api.py"
click node_middleware "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/middleware.py"
click node_contracts "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/models.py"
click node_pipeline "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/pipeline.py"
click node_security "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/security.py"
click node_planner "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/planner.py"
click node_query "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/query.py"
click node_generator "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/providers.py"
click node_hybrid "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/hybrid.py"
click node_memory "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/memory.py"
click node_sparse "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/sparse.py"
click node_graph "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/graph.py"
click node_web "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/web.py"
click node_reranker "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/rerank.py"
click node_qdrant "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/qdrant.py"
click node_embeddings "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/embeddings.py"
click node_ingestion "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/services.py"
click node_storage "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/storage.py"
click node_research "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/research.py"
click node_evaluation "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/evaluation.py"
click node_observability "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/observability.py"
click node_evaluator "https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/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_middleware,node_user toneBlue
class node_contracts,node_pipeline,node_security,node_planner,node_query,node_generator toneAmber
class node_hybrid,node_memory,node_sparse,node_graph,node_web,node_reranker,node_qdrant,node_embeddings toneMint
class node_ingestion,node_storage,node_research toneRose
class node_evaluation,node_observability,node_evaluator toneIndigo
```

## Components

### API and access

- [HTTP API](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/api.py): `adaptive_rag/api.py`
- [API middleware](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/middleware.py): `adaptive_rag/middleware.py`

### Query orchestration

- [Domain contracts](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/models.py): `adaptive_rag/models.py`
- [Adaptive pipeline](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/pipeline.py): `adaptive_rag/pipeline.py`
- [Security gate](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/security.py): `adaptive_rag/security.py`
- [Query planner](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/planner.py): `adaptive_rag/planner.py`
- [Rewrite and citations](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/query.py): `adaptive_rag/query.py`
- [Answer generation](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/providers.py): `adaptive_rag/providers.py`

### Evidence retrieval

- [Hybrid retrieval](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/hybrid.py): `adaptive_rag/retrieval/hybrid.py`
- [Local retrieval](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/memory.py): `adaptive_rag/retrieval/memory.py`
- [BM25 retrieval](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/sparse.py): `adaptive_rag/retrieval/sparse.py`
- [Graph retrieval](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/graph.py): `adaptive_rag/retrieval/graph.py`
- [Web retrieval](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/web.py): `adaptive_rag/retrieval/web.py`
- [Evidence reranker](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/rerank.py): `adaptive_rag/retrieval/rerank.py`
- [Qdrant adapter](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/retrieval/qdrant.py): `adaptive_rag/retrieval/qdrant.py`
- [Embedding providers](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/embeddings.py): `adaptive_rag/embeddings.py`

### Content and research

- [Ingestion and chunking](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/services.py): `adaptive_rag/services.py`
- [Document storage](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/storage.py): `adaptive_rag/storage.py`
- [Multi-aspect research](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/research.py): `adaptive_rag/research.py`

### Quality and operations

- [Evidence evaluation](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/evaluation.py): `adaptive_rag/evaluation.py`
- [Trace and costs](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/observability.py): `adaptive_rag/observability.py`
- [Quality metrics](https://github.com/mustafaahmed007/adaptiverag-x/blob/main/adaptive_rag/evaluation.py): `adaptive_rag/evaluation.py`

### Other components

- **User**

## Connections

- User → HTTP API: submits query (evidence: `README.md`)
- HTTP API → API middleware: uses access controls (evidence: `adaptive_rag/api.py`)
- HTTP API → Adaptive pipeline: routes queries (evidence: `adaptive_rag/api.py`)
- HTTP API → Multi-aspect research: routes research (evidence: `adaptive_rag/api.py`)
- HTTP API → Ingestion and chunking: uses ingestion (evidence: `adaptive_rag/api.py`)
- Adaptive pipeline → Security gate: checks query (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Query planner: builds plan (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Rewrite and citations: rewrites and cites (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Answer generation: generates answer (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Hybrid retrieval: retrieves evidence (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Graph retrieval: retrieves multi-hop (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Web retrieval: retrieves fresh evidence (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Evidence reranker: reranks evidence (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Evidence evaluation: evaluates evidence (evidence: `adaptive_rag/pipeline.py`)
- Adaptive pipeline → Trace and costs: records trace (evidence: `adaptive_rag/pipeline.py`)
- Hybrid retrieval → Local retrieval: queries dense side (evidence: `adaptive_rag/pipeline.py`)
- Hybrid retrieval → BM25 retrieval: queries sparse side (evidence: `adaptive_rag/pipeline.py`)
- Ingestion and chunking → Domain contracts: creates documents (evidence: `adaptive_rag/services.py`)
- Multi-aspect research → Ingestion and chunking: ingests report sources (evidence: `adaptive_rag/research.py`)
- Qdrant adapter → Embedding providers: embeds content (evidence: `adaptive_rag/retrieval/qdrant.py`)
- Adaptive pipeline → Qdrant adapter: may use adapter (evidence: `README.md`)
- Adaptive pipeline → Document storage: may persist documents (evidence: `README.md`)
- Adaptive pipeline → Domain contracts: returns response (evidence: `adaptive_rag/pipeline.py`)
- HTTP API → Domain contracts: uses request models (evidence: `adaptive_rag/api.py`)
