# danny-avila/rag_api architecture

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

- Interactive diagram: https://gitdiagram.com/danny-avila/rag_api
- Repository: https://github.com/danny-avila/rag_api

## Overview

1. This repository is a FastAPI-based RAG API focused on file-scoped retrieval. The key architectural idea is that embeddings are organized by `file_id`, so all ingest, query, and delete operations are isolated per document/file rather than treating the corpus as one global index.

2. The main runtime entrypoint is `main.py`, which builds the FastAPI application from the `app/` package. Configuration is environment-driven via `app/config.py`, so deployment behavior changes substantially depending on variables like `VECTOR_DB_TYPE`, embedding provider settings, and database connection values.

3. The API layer is split into route modules: `app/routes/document_routes.py` handles document lifecycle actions, while `app/routes/pgvector_routes.py` exposes pgvector-specific operations and debugging-oriented database routes when enabled. This separation reflects two concerns: user-facing document management and backend/vector-store-specific capabilities.

4. Request cross-cutting concerns live in `app/middleware.py`. Based on the README, authentication is optional and JWT-based when enabled, so the middleware boundary is likely where request verification, logging, or similar policy checks happen before routes reach the service layer.

5. The service layer is where persistence is abstracted. `app/services/database.py` manages PostgreSQL access, `app/services/mongo_client.py` manages MongoDB/Atlas connectivity, and `app/services/vector_store/factory.py` selects the active vector backend at runtime. This factory is the main backend boundary in the system.

6. There are multiple vector-store implementations under `app/services/vector_store/`. `async_pg_vector.py` is the primary async PostgreSQL/pgvector implementation, `extended_pg_vector.py` appears to add pgvector-specific behavior beyond the base class, and `atlas_mongo_vector.py` provides the alternate Atlas MongoDB vector-search path. The architecture is intentionally pluggable so the same API can target different vector databases.

7. The ingest pipeline is centered on document loading and chunking in `app/utils/document_loader.py`. Documents are parsed, split into chunks using the configured chunk size/overlap, embedded through the configured provider, and then written to the chosen vector store with `file_id` metadata attached. This is the key data flow from uploaded file to retrievable vector records.

8. Large-file ingestion is designed to be memory-aware. The README’s batch-processing settings (`EMBEDDING_BATCH_SIZE`, `EMBEDDING_MAX_QUEUE_SIZE`) indicate that document chunks can be embedded and inserted in bounded batches rather than all at once, which is an important architectural feature for scaling and for container-constrained deployments.

9. Retrieval is vector-search driven and filtered by file identity and metadata. With pgvector, search results can optionally be distance-threshold filtered; with Atlas MongoDB, the search index uses similarity semantics instead. This means query behavior differs by backend even though the API surface remains similar.

10. `app/models.py` defines the request/response and internal data models used across routes and services. `app/constants.py` holds shared values, keeping route/service code aligned on collection names, defaults, and other domain constants.

11. `app/utils/health.py` provides operational health checks, which are important because this API depends on external stateful systems: PostgreSQL with the pgvector extension, or Atlas MongoDB Search, plus the configured embeddings provider. Startup also appears to validate extension/schema requirements and fail fast when prerequisites are missing.

12. Deployment is container-first. The repo includes Dockerfiles, compose files for the API and database, and GitHub Actions workflows for CI and image publishing. This means the architecture supports both local split deployment and containerized deployment, with the DB often running as a separate infrastructure component.

13. The test suite mirrors the architecture boundaries: unit tests cover config, middleware, models, and utility behavior; service tests cover vector-store and database abstractions; integration tests cover pgvector filtering, batch processing, and upload isolation. That test structure is a good guide to the system’s real seams.

14. In short, the repository is organized around a thin HTTP/API layer, a backend-agnostic vector-store service layer, and a file-scoped ingestion/retrieval pipeline. The most important diagram boundaries are: client/API, auth/middleware, document processing, vector-store abstraction, and external persistence/embedding services.

Main entry points: [`app/services/vector_store/factory.py`](https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/factory.py) (Vector Factory), [`main.py`](https://github.com/danny-avila/rag_api/blob/main/main.py) (main), [`app/routes/document_routes.py`](https://github.com/danny-avila/rag_api/blob/main/app/routes/document_routes.py) (Documents), [`app/utils/document_loader.py`](https://github.com/danny-avila/rag_api/blob/main/app/utils/document_loader.py) (Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_main["main<br/>FastAPI entrypoint<br/>[main.py]"]
  node_middleware["Middleware<br/>request policy<br/>[middleware.py]"]
  node_document_routes["Documents<br/>API routes<br/>[document_routes.py]"]
  node_pgvector_routes["PGVector<br/>API routes<br/>[pgvector_routes.py]"]
  node_client(("Client<br/>API consumer"))
end

subgraph group_core["Core"]
  node_config["Config<br/>[config.py]"]
  node_models["Models<br/>[models.py]"]
  node_constants["Constants<br/>shared values<br/>[constants.py]"]
  node_document_loader["Loader<br/>ingest pipeline<br/>[document_loader.py]"]
end

subgraph group_storage["Storage"]
  node_database[("Postgres<br/>db service<br/>[database.py]")]
  node_mongo_client[("Mongo Client<br/>db client<br/>[mongo_client.py]")]
  node_vector_factory["Vector Factory<br/>backend selector<br/>[factory.py]"]
  node_async_pg_vector[("Async PGVector<br/>vector backend<br/>[async_pg_vector.py]")]
  node_extended_pg_vector[("PG Extensions<br/>vector backend")]
  node_atlas_mongo_vector[("Atlas Vector<br/>vector backend")]
  node_postgres[("PostgreSQL<br/>external db")]
  node_mongodb[("MongoDB<br/>external db")]
end

subgraph group_ops["Ops"]
  node_health["Health<br/>ops checks<br/>[health.py]"]
  node_embedding(("Embeddings<br/>external service"))
end

node_client -->|"HTTP"| node_main
node_main -->|"loads"| node_config
node_main -->|"wraps"| node_middleware
node_main -->|"mounts"| node_document_routes
node_main -->|"mounts"| node_pgvector_routes
node_document_routes -->|"uses"| node_models
node_document_routes -->|"ingests"| node_document_loader
node_document_routes -->|"stores"| node_vector_factory
node_pgvector_routes -->|"queries"| node_database
node_vector_factory -->|"selects"| node_async_pg_vector
node_vector_factory -->|"selects"| node_extended_pg_vector
node_vector_factory -->|"selects"| node_atlas_mongo_vector
node_async_pg_vector -->|"persists"| node_database
node_extended_pg_vector -->|"extends"| node_database
node_atlas_mongo_vector -->|"persists"| node_mongo_client
node_document_loader -->|"embeds"| node_embedding
node_document_loader -->|"writes"| node_vector_factory
node_health -->|"checks"| node_database
node_health -->|"checks"| node_mongo_client
node_health -->|"checks"| node_embedding
node_config -->|"configures"| node_vector_factory
node_config -->|"configures"| node_document_loader
node_constants -->|"shared"| node_document_routes
node_constants -->|"shared"| node_vector_factory

click node_main "https://github.com/danny-avila/rag_api/blob/main/main.py"
click node_config "https://github.com/danny-avila/rag_api/blob/main/app/config.py"
click node_middleware "https://github.com/danny-avila/rag_api/blob/main/app/middleware.py"
click node_document_routes "https://github.com/danny-avila/rag_api/blob/main/app/routes/document_routes.py"
click node_pgvector_routes "https://github.com/danny-avila/rag_api/blob/main/app/routes/pgvector_routes.py"
click node_models "https://github.com/danny-avila/rag_api/blob/main/app/models.py"
click node_constants "https://github.com/danny-avila/rag_api/blob/main/app/constants.py"
click node_document_loader "https://github.com/danny-avila/rag_api/blob/main/app/utils/document_loader.py"
click node_health "https://github.com/danny-avila/rag_api/blob/main/app/utils/health.py"
click node_database "https://github.com/danny-avila/rag_api/blob/main/app/services/database.py"
click node_mongo_client "https://github.com/danny-avila/rag_api/blob/main/app/services/mongo_client.py"
click node_vector_factory "https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/factory.py"
click node_async_pg_vector "https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/async_pg_vector.py"
click node_extended_pg_vector "https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/extended_pg_vector.py"
click node_atlas_mongo_vector "https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/atlas_mongo_vector.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_main,node_middleware,node_document_routes,node_pgvector_routes,node_client toneBlue
class node_config,node_models,node_constants,node_document_loader toneAmber
class node_database,node_mongo_client,node_vector_factory,node_async_pg_vector,node_extended_pg_vector,node_atlas_mongo_vector,node_postgres,node_mongodb toneMint
class node_health,node_embedding toneRose
```

## Components

### Delivery

HTTP entrypoint, routes, and request policy

- [main](https://github.com/danny-avila/rag_api/blob/main/main.py): FastAPI entrypoint · Builds and starts the API application. · `main.py`
- [Middleware](https://github.com/danny-avila/rag_api/blob/main/app/middleware.py): request policy · Cross-cutting request handling such as auth and logging. · `app/middleware.py`
- [Documents](https://github.com/danny-avila/rag_api/blob/main/app/routes/document_routes.py): API routes · Document lifecycle and file-scoped ingest/query/delete endpoints. · `app/routes/document_routes.py`
- [PGVector](https://github.com/danny-avila/rag_api/blob/main/app/routes/pgvector_routes.py): API routes · pgvector-specific and database/debug routes when enabled. · `app/routes/pgvector_routes.py`
- **Client**: API consumer · Uploads documents and issues file-scoped retrieval requests.

### Core

Shared config, models, and document processing

- [Config](https://github.com/danny-avila/rag_api/blob/main/app/config.py): env config · Environment-driven runtime configuration and feature switches. · `app/config.py`
- [Models](https://github.com/danny-avila/rag_api/blob/main/app/models.py): schema models · Shared request, response, and internal data models. · `app/models.py`
- [Constants](https://github.com/danny-avila/rag_api/blob/main/app/constants.py): shared values · Common defaults and domain constants used across layers. · `app/constants.py`
- [Loader](https://github.com/danny-avila/rag_api/blob/main/app/utils/document_loader.py): ingest pipeline · Parses files, chunks content, and prepares embeddings input. · `app/utils/document_loader.py`

### Storage

Database and vector-store adapters

- [Postgres](https://github.com/danny-avila/rag_api/blob/main/app/services/database.py): db service · PostgreSQL connection and persistence helpers. · `app/services/database.py`
- [Mongo Client](https://github.com/danny-avila/rag_api/blob/main/app/services/mongo_client.py): db client · MongoDB/Atlas connectivity wrapper. · `app/services/mongo_client.py`
- [Vector Factory](https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/factory.py): backend selector · Selects the active vector-store implementation at runtime. · `app/services/vector_store/factory.py`
- [Async PGVector](https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/async_pg_vector.py): vector backend · Primary async PostgreSQL/pgvector implementation. · `app/services/vector_store/async_pg_vector.py`
- [PG Extensions](https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/extended_pg_vector.py): vector backend · pgvector-specific extensions and higher-level behavior. · `app/services/vector_store/extended_pg_vector.py`
- [Atlas Vector](https://github.com/danny-avila/rag_api/blob/main/app/services/vector_store/atlas_mongo_vector.py): vector backend · Atlas MongoDB vector-search implementation. · `app/services/vector_store/atlas_mongo_vector.py`
- **PostgreSQL**: external db · Primary relational store, often with pgvector enabled.
- **MongoDB**: external db · Alternate vector-search and document store backend.

### Ops

Health and deployment surface

- [Health](https://github.com/danny-avila/rag_api/blob/main/app/utils/health.py): ops checks · Dependency and readiness checks for external services. · `app/utils/health.py`
- **Embeddings**: external service · Configured embedding provider used during ingest and query.

## Connections

- Client → main: HTTP · Clients call the API entrypoint.
- main → Config: loads · Startup behavior is driven by environment configuration.
- main → Middleware: wraps · Application middleware is installed before routes.
- main → Documents: mounts · Document endpoints are registered on the app.
- main → PGVector: mounts · Optional pgvector-specific routes are registered.
- Documents → Models: uses · Routes serialize and validate payloads with shared models.
- Documents → Loader: ingests · Uploaded files are parsed and chunked for retrieval.
- Documents → Vector Factory: stores · Ingest and retrieval are routed to the selected vector backend.
- PGVector → Postgres: queries · Backend/debug endpoints inspect PostgreSQL state.
- Vector Factory → Async PGVector: selects · Chooses the async pgvector implementation when configured.
- Vector Factory → PG Extensions: selects · Can route to pgvector extensions when needed.
- Vector Factory → Atlas Vector: selects · Can route to Atlas MongoDB vector search.
- Async PGVector → Postgres: persists · Uses PostgreSQL for vector and metadata storage.
- PG Extensions → Postgres: extends · Builds on PostgreSQL storage and pgvector behavior.
- Atlas Vector → Mongo Client: persists · Uses MongoDB/Atlas connectivity for vector search.
- Loader → Embeddings: embeds · Chunks are converted using the configured embedding provider.
- Loader → Vector Factory: writes · Prepared chunks are inserted into the active vector backend.
- Health → Postgres: checks · Verifies PostgreSQL availability and readiness.
- Health → Mongo Client: checks · Verifies MongoDB/Atlas availability when relevant.
- Health → Embeddings: checks · Confirms the embedding provider is reachable.
- Config → Vector Factory: configures · Backend choice and thresholds come from environment settings.
- Config → Loader: configures · Chunk size, overlap, and batch limits are configured here.
- Constants → Documents: shared · Routes rely on common names and defaults.
- Constants → Vector Factory: shared · Vector-store implementations share domain constants.
