# mazleon/omni-rag architecture

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

- Interactive diagram: https://gitdiagram.com/mazleon/omni-rag
- Repository: https://github.com/mazleon/omni-rag

## Overview

OmniRAG is a monorepo for a production RAG platform, organized around a few clear runtime boundaries: an HTTP API, background workers, a web frontend, and shared service/domain code. The repository is mostly scaffolded here, but the directory layout and README describe the intended system architecture clearly.

1. **Top-level shape: a multi-app monorepo**
   The repo separates deployable surfaces under `apps/`, shared business capabilities under `services/`, shared contracts under `core/`, and environment-specific concerns under `infra/`. That suggests the architecture is split by runtime role rather than by framework layer.

2. **User-facing application**
   `apps/frontend` is the Next.js 15 frontend. It is the interactive client for document upload, query/answer flows, and likely evaluation or admin views. Because the README emphasizes SSE streaming and grounded answers, the frontend is not just a static UI; it is expected to consume streaming responses from the backend API.

3. **API boundary**
   `apps/api` is the FastAPI service, the main synchronous entry point for the system. It likely handles authentication, document upload, query execution, and orchestration endpoints. The `apps/api/routers` folder indicates a router-based API surface, which is the main integration boundary for the frontend and any external clients.

4. **Background execution**
   `apps/worker` is the asynchronous processing tier. The README says ingestion uses Arq worker fleets via Redis Streams, so this app is where long-running tasks are executed: document processing, chunking, embedding, indexing, and possibly evaluation jobs. This keeps heavy ingestion work off the request path.

5. **Service decomposition**
   The `services/` directory is split into `ingestion`, `retrieval`, `orchestrator`, and `evaluation`. This is the clearest indication of the core domain boundaries:
   - `ingestion` handles turning raw uploaded files into structured, chunked content.
   - `retrieval` handles dense/sparse search, structured filtering, and reranking.
   - `orchestrator` likely coordinates the agent/tool loop and query execution pipeline.
   - `evaluation` contains offline quality checks and the golden dataset used by CI gates.

6. **Shared schemas and contracts**
   `core/schemas` is the shared contract layer. In a system like this, that is typically where request/response models, document schemas, chunk representations, retrieval result shapes, and evaluation artifacts live. This layer is important because it keeps the API, worker, and service modules aligned on the same data model.

7. **Ingestion data flow**
   The ingestion pipeline described in the README is: upload document → async task queued → extract structure from PDFs/spreadsheets/images/slides → semantic chunking with overlap → embeddings → persistence/indexing. The key architectural point is that ingestion is asynchronous and idempotent, which allows large volumes of heterogeneous documents to be processed safely and repeatedly.

8. **Retrieval and answer generation flow**
   Query-time processing is a multi-stage pipeline: dense retrieval from Qdrant, sparse BM25 lookup, structured filtering, fusion via RRF, reranking with Cohere rerank-v3.5, then answer generation via Claude/GPT-4o through OpenRouter. This is the core online path and explains why retrieval, orchestration, and model access are separated into distinct service layers.

9. **Multi-tenancy boundary**
   The README explicitly calls out Postgres RLS and per-organization Qdrant collections. That means tenant isolation is enforced at both the transactional metadata layer and the vector-store layer. This is an important architectural boundary for any diagram: org context is not just an application concern, it is part of storage layout and query filtering.

10. **Persistence and external systems**
   The system uses PostgreSQL 17 for OLTP/state, Qdrant for vector search, Redis Streams for task coordination, and Supabase Storage for raw files and derived artifacts. These services are the main infrastructure dependencies and define the durable data flow:
   raw assets in object storage, metadata in Postgres, embeddings/chunks in Qdrant, and async work through Redis.

11. **Observability and evaluation**
   OpenTelemetry, Langfuse, and ClickHouse are listed for observability, which implies tracing/metrics/logging are first-class across API, workers, and model calls. Evaluation is also first-class: `services/evaluation`, `tests/eval`, and `.github/workflows/eval-gate.yml` indicate offline RAGAS-style quality checks are part of the release process, not an afterthought.

12. **Infrastructure and deployment**
   `docker-compose.yml`, `infra/docker`, `infra/migrations`, and `infra/fly` show three infrastructure layers: local dev composition, schema migrations, and Fly.io deployment. This suggests the repo is designed to run locally in a full stack, evolve via migrations, and eventually deploy to managed hosting.

13. **CI/CD and quality gates**
   The GitHub workflows in `.github/workflows/ci.yml` and `eval-gate.yml` indicate two separate gates: general test/build checks and evaluation-specific merge protection. That is consistent with an RAG system where functional correctness alone is insufficient; retrieval/answer quality must also be validated before merging to main.

14. **Repository maturity note**
   Many directories contain only `.gitkeep` files, so this repo is currently more of an architecture scaffold than a fully populated implementation. Still, the layout is explicit enough to infer the intended runtime graph: frontend and API at the edge, worker tier behind Redis, domain services in the middle, and Postgres/Qdrant/object storage as the durable backend.

Main entry points: [`apps/api`](https://github.com/mazleon/omni-rag/tree/main/apps/api) (API), [`infra/fly`](https://github.com/mazleon/omni-rag/tree/main/infra/fly) (Deploy), [`apps/worker`](https://github.com/mazleon/omni-rag/tree/main/apps/worker) (Worker), [`services/ingestion`](https://github.com/mazleon/omni-rag/tree/main/services/ingestion) (Ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apps["Apps"]
  node_frontend["Frontend<br/>Next.js UI"]
  node_api["API"]
  node_worker["Worker<br/>async jobs"]
end

subgraph group_services["Services"]
  node_ingestion{{"Ingestion<br/>pipeline"}}
  node_retrieval{{"Retrieval<br/>search pipeline"}}
  node_orchestrator{{"Orchestrator<br/>query flow"}}
  node_evaluation{{"Evaluation<br/>quality checks"}}
end

subgraph group_core["Core"]
  node_schemas["Schemas<br/>shared contracts"]
end

subgraph group_infra["Infra"]
  node_postgres[("Postgres<br/>state store")]
  node_qdrant[("Qdrant<br/>vector index")]
  node_redis["Redis<br/>task queue"]
  node_object_storage[("Object Store<br/>file storage")]
  node_observability(("Observability<br/>telemetry"))
  node_deploy["Deploy<br/>fly infra"]
end

subgraph group_quality["Quality"]
  node_ci["CI<br/>workflow gates<br/>[ci.yml]"]
  node_eval_gate["Eval Gate<br/>merge gate<br/>[eval-gate.yml]"]
  node_integration_tests["Integration Tests"]
  node_unit_tests["Unit Tests"]
end

node_frontend -->|"HTTP/SSE"| node_api
node_api -->|"uses"| node_schemas
node_worker -->|"uses"| node_schemas
node_api -->|"enqueue"| node_redis
node_redis -->|"dispatch"| node_worker
node_worker -->|"runs"| node_ingestion
node_ingestion -->|"read/write"| node_object_storage
node_ingestion -->|"metadata"| node_postgres
node_ingestion -->|"index"| node_qdrant
node_api -->|"query flow"| node_orchestrator
node_orchestrator -->|"retrieve"| node_retrieval
node_retrieval -->|"dense search"| node_qdrant
node_retrieval -->|"filters"| node_postgres
node_orchestrator -->|"state"| node_postgres
node_api -->|"serve files"| node_object_storage
node_api -->|"telemetry"| node_observability
node_worker -->|"telemetry"| node_observability
node_orchestrator -->|"telemetry"| node_observability
node_evaluation -->|"uses"| node_schemas
node_evaluation -->|"gates"| node_ci
node_evaluation -->|"protects"| node_eval_gate
node_ci -->|"runs"| node_integration_tests
node_ci -->|"runs"| node_unit_tests
node_deploy -->|"migrate"| node_postgres
node_deploy -->|"provision"| node_redis
node_deploy -->|"provision"| node_qdrant
node_deploy -->|"provision"| node_object_storage

click node_frontend "https://github.com/mazleon/omni-rag/tree/main/apps/frontend"
click node_api "https://github.com/mazleon/omni-rag/tree/main/apps/api"
click node_worker "https://github.com/mazleon/omni-rag/tree/main/apps/worker"
click node_ingestion "https://github.com/mazleon/omni-rag/tree/main/services/ingestion"
click node_retrieval "https://github.com/mazleon/omni-rag/tree/main/services/retrieval"
click node_orchestrator "https://github.com/mazleon/omni-rag/tree/main/services/orchestrator"
click node_evaluation "https://github.com/mazleon/omni-rag/tree/main/services/evaluation"
click node_schemas "https://github.com/mazleon/omni-rag/tree/main/core/schemas"
click node_postgres "https://github.com/mazleon/omni-rag/tree/main/infra/migrations"
click node_deploy "https://github.com/mazleon/omni-rag/tree/main/infra/fly"
click node_ci "https://github.com/mazleon/omni-rag/blob/main/.github/workflows/ci.yml"
click node_eval_gate "https://github.com/mazleon/omni-rag/blob/main/.github/workflows/eval-gate.yml"
click node_integration_tests "https://github.com/mazleon/omni-rag/tree/main/tests/integration"
click node_unit_tests "https://github.com/mazleon/omni-rag/tree/main/tests/unit"

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_frontend,node_api,node_worker toneBlue
class node_ingestion,node_retrieval,node_orchestrator,node_evaluation toneAmber
class node_schemas toneMint
class node_postgres,node_qdrant,node_redis,node_object_storage,node_observability,node_deploy toneRose
class node_ci,node_eval_gate,node_integration_tests,node_unit_tests toneIndigo
```

## Components

### Apps

Deployable user-facing and background runtimes.

- [Frontend](https://github.com/mazleon/omni-rag/tree/main/apps/frontend): Next.js UI · Interactive web client for uploads, querying, and streamed answers. · `apps/frontend`
- [API](https://github.com/mazleon/omni-rag/tree/main/apps/api): FastAPI service · Main HTTP boundary for orchestration, uploads, and query requests. · `apps/api`
- [Worker](https://github.com/mazleon/omni-rag/tree/main/apps/worker): async jobs · Background runtime for ingestion and other long-running tasks. · `apps/worker`

### Services

Shared domain capabilities and pipelines.

- [Ingestion](https://github.com/mazleon/omni-rag/tree/main/services/ingestion): pipeline · Turns raw documents into structured chunks and embeddings. · `services/ingestion`
- [Retrieval](https://github.com/mazleon/omni-rag/tree/main/services/retrieval): search pipeline · Performs dense/sparse retrieval, filtering, fusion, and reranking. · `services/retrieval`
- [Orchestrator](https://github.com/mazleon/omni-rag/tree/main/services/orchestrator): query flow · Coordinates model/tool execution and answer generation. · `services/orchestrator`
- [Evaluation](https://github.com/mazleon/omni-rag/tree/main/services/evaluation): quality checks · Offline scoring, golden datasets, and release-time assessment. · `services/evaluation`

### Core

Shared contracts and schemas.

- [Schemas](https://github.com/mazleon/omni-rag/tree/main/core/schemas): shared contracts · Common request, response, and domain data models. · `core/schemas`

### Infra

Runtime infrastructure, deployment, and persistence concerns.

- [Postgres](https://github.com/mazleon/omni-rag/tree/main/infra/migrations): state store · Primary transactional database and tenant-aware metadata store. · `infra/migrations`
- **Qdrant**: vector index · Per-tenant vector collections for semantic search.
- **Redis**: task queue · Stream-based coordination for asynchronous worker jobs.
- **Object Store**: file storage · Raw uploads and derived artifacts kept in external storage.
- **Observability**: telemetry · Tracing, logging, and operational analytics across runtimes.
- [Deploy](https://github.com/mazleon/omni-rag/tree/main/infra/fly): fly infra · Docker, migrations, and Fly.io deployment assets. · `infra/fly`

### Quality

Testing and evaluation gates.

- [CI](https://github.com/mazleon/omni-rag/blob/main/.github/workflows/ci.yml): workflow gates · Build/test automation and evaluation gate workflows. · `.github/workflows/ci.yml`
- [Eval Gate](https://github.com/mazleon/omni-rag/blob/main/.github/workflows/eval-gate.yml): merge gate · Quality gate for retrieval and answer quality regression checks. · `.github/workflows/eval-gate.yml`
- [Integration Tests](https://github.com/mazleon/omni-rag/tree/main/tests/integration): tests · Cross-component validation for service and runtime boundaries. · `tests/integration`
- [Unit Tests](https://github.com/mazleon/omni-rag/tree/main/tests/unit): tests · Focused component and domain-level verification. · `tests/unit`

## Connections

- Frontend → API: HTTP/SSE · Browser requests and streamed responses flow through the API.
- API → Schemas: uses · API requests and responses are typed by shared contracts.
- Worker → Schemas: uses · Jobs and persisted records share the same models.
- API → Redis: enqueue · Requests hand off long-running work to the async queue.
- Redis → Worker: dispatch · Queued jobs are delivered to background workers.
- Worker → Ingestion: runs · Workers execute the document processing pipeline.
- Ingestion → Object Store: read/write · Raw files and derived artifacts are persisted externally.
- Ingestion → Postgres: metadata · Ingestion persists document state and processing records.
- Ingestion → Qdrant: index · Embeddings and chunks are written to the vector store.
- API → Orchestrator: query flow · Online requests are handed to the answer orchestration layer.
- Orchestrator → Retrieval: retrieve · The orchestrator asks retrieval for candidate context.
- Retrieval → Qdrant: dense search · Semantic retrieval reads from vector collections.
- Retrieval → Postgres: filters · Structured metadata and tenant constraints come from Postgres.
- Orchestrator → Postgres: state · Query/session state and tenancy checks are stored centrally.
- API → Object Store: serve files · Uploads and derived assets are exposed through storage.
- API → Observability: telemetry · Request traces and metrics are emitted from the API.
- Worker → Observability: telemetry · Background jobs emit traces and operational signals.
- Orchestrator → Observability: telemetry · Model and retrieval spans are traced across the query path.
- Evaluation → Schemas: uses · Evaluation artifacts are defined against shared domain models.
- Evaluation → CI: gates · Quality checks are wired into automated CI workflows.
- Evaluation → Eval Gate: protects · Model and retrieval quality gates block regressions.
- CI → Integration Tests: runs · Continuous integration executes cross-system tests.
- CI → Unit Tests: runs · Continuous integration executes focused unit tests.
- Deploy → Postgres: migrate · Deployment includes schema evolution for the database.
- Deploy → Redis: provision · Infrastructure supports async coordination services.
- Deploy → Qdrant: provision · Infrastructure includes the vector search backend.
- Deploy → Object Store: provision · Infrastructure depends on external file storage.
