How danny-avila/rag_api works
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: factory.py Vector Factory · main.py main · document_routes.py Documents · document_loader.py Loader
Components 19
Delivery
HTTP entrypoint, routes, and request policy
- main · Builds and starts the API application.
main.py - Middleware · Cross-cutting request handling such as auth and logging.
app/middleware.py - Documents · Document lifecycle and file-scoped ingest/query/delete endpoints.
app/routes/document_routes.py - PGVector · pgvector-specific and database/debug routes when enabled.
app/routes/pgvector_routes.py - Client · Uploads documents and issues file-scoped retrieval requests.
Core
Shared config, models, and document processing
- Config · Environment-driven runtime configuration and feature switches.
app/config.py - Models · Shared request, response, and internal data models.
app/models.py - Constants · Common defaults and domain constants used across layers.
app/constants.py - Loader · Parses files, chunks content, and prepares embeddings input.
app/utils/document_loader.py
Storage
Database and vector-store adapters
- Postgres · PostgreSQL connection and persistence helpers.
app/services/database.py - Mongo Client · MongoDB/Atlas connectivity wrapper.
app/services/mongo_client.py - Vector Factory · Selects the active vector-store implementation at runtime.
app/services/vector_store/factory.py - Async PGVector · Primary async PostgreSQL/pgvector implementation.
app/services/vector_store/async_pg_vector.py - PG Extensions · pgvector-specific extensions and higher-level behavior.
app/services/vector_store/extended_pg_vector.py - Atlas Vector · Atlas MongoDB vector-search implementation.
app/services/vector_store/atlas_mongo_vector.py - PostgreSQL · Primary relational store, often with pgvector enabled.
- MongoDB · Alternate vector-search and document store backend.
Ops
Health and deployment surface
- Health · Dependency and readiness checks for external services.
app/utils/health.py - Embeddings · Configured embedding provider used during ingest and query.
Connections 24
- 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.