# hermes-erm/polyvault-rag architecture

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

- Interactive diagram: https://gitdiagram.com/hermes-erm/polyvault-rag
- Repository: https://github.com/hermes-erm/polyvault-rag

## Overview

#### Purpose and entry points
Poly-vault is a multimodal retrieval-augmented generation (RAG) service: it ingests supported files, converts and semantically chunks content, indexes embeddings, then answers questions only from retrieved context. The FastAPI application starts from `src/app/main.py`; HTTP routes live in `src/app/api.py`; its minimal browser client is `src/app/static/index.html`.

#### API and application boundary
`src/app/main.py` creates the FastAPI app, mounts static content, and registers API routing. `src/app/api.py` exposes upload, document listing/deletion, vector reset, retrieval, and answer-generation endpoints. `src/dependencies.py` is the composition boundary that creates/reuses pipeline services and database sessions; model selection is centralized here.

#### Ingestion pipeline
Uploads enter through `src/app/api.py` and are handled asynchronously by `src/rag_system/document_processor.py`. The processor persists source/intermediate files under `pipeline/staging/` and records lifecycle state—staging, embedding, indexed, or failed—through `src/rag_system/model.py`. It uses Docling to normalize PDF, DOCX, images, CSV, XLSX, and Markdown into Markdown; BlingFire sentence segmentation and semantic grouping produce chunks.

#### Persistence and indexing
`src/rag_system/model.py` owns the SQLAlchemy/SQLite document-pipeline metadata model and repository operations. `src/rag_system/retriever.py` owns ChromaDB collection operations: chunk embedding, metadata association, similarity lookup, per-document vector deletion, and full reset. The SQLite row and Chroma vectors must remain coordinated: document deletion and reset remove both metadata and embeddings.

#### Retrieval and answer generation
For `/query/search`, `src/app/api.py` delegates query embedding and candidate retrieval to `src/rag_system/retriever.py`. Retrieved chunks are reranked by Cohere before being passed to `src/rag_system/generator.py`. The generator calls Gemini with a RAG prompt that constrains answers to supplied context. `/query/retrieve` exposes the retrieval stage without answer generation.

#### Runtime dependencies and external services
The Python/FastAPI runtime packages services in `Dockerfile` and dependencies in `requirements.txt`. Core local persistence is SQLite plus persistent ChromaDB storage; staging/processed pipeline directories are `pipeline/staging/` and `pipeline/processed/`. External model/service dependencies are Docling, BlingFire, MiniLM embeddings, Cohere reranking, and Gemini generation; Cohere and Gemini credentials come from environment variables.

#### Deployment control flow
`.github/workflows/aws-ecs-deploy.yml` runs on pushes to `main`, builds the `Dockerfile` image, pushes it to Amazon ECR, renders an ECS task definition, and deploys it to ECS. The deployed task is reached through an AWS Network Load Balancer and stable Elastic IP; deployment routing depends on target health checks. The service currently has no API authentication, so network exposure is the primary protection boundary.

Main entry points: [`src/rag_system/document_processor.py`](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/document_processor.py) (Document processor), [`src/app/api.py`](https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/api.py) (HTTP API), [`src/rag_system/retriever.py`](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/retriever.py) (Vector retriever), [`src/app/main.py`](https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_browser["Browser client<br/>static client<br/>[index.html]"]
  node_fastapi_main["FastAPI app<br/>application entrypoint<br/>[main.py]"]
  node_api["HTTP API<br/>route layer<br/>[api.py]"]
  node_dependencies["Service composition<br/>dependency boundary<br/>[dependencies.py]"]
end

subgraph group_ingestion["Ingestion pipeline"]
  node_processor["Document processor<br/>async ingestion service"]
  node_staging[("Staging files<br/>pipeline storage")]
  node_processed[("Processed files<br/>pipeline storage")]
end

subgraph group_storage["Persistence &amp; retrieval"]
  node_metadata_model["Document metadata<br/>SQLAlchemy repository<br/>[model.py]"]
  node_sqlite[("SQLite<br/>metadata database")]
  node_retriever["Vector retriever<br/>index and search service<br/>[retriever.py]"]
  node_chromadb[("ChromaDB<br/>persistent vector store")]
end

subgraph group_models["Model services"]
  node_docling{{"Docling<br/>normalization service"}}
  node_blingfire{{"BlingFire<br/>segmentation service"}}
  node_minilm{{"MiniLM embeddings<br/>embedding model"}}
  node_cohere{{"Cohere reranker<br/>external ranking service"}}
  node_generator["RAG generator<br/>answer service<br/>[generator.py]"]
  node_gemini{{"Gemini<br/>external generation service"}}
end

subgraph group_deployment["Deployment"]
  node_workflow["ECS deploy workflow<br/>CI/CD pipeline<br/>[aws-ecs-deploy.yml]"]
  node_dockerfile["Container image<br/>runtime package"]
  node_aws_delivery["ECR → ECS → NLB<br/>AWS deployment path"]
end

node_browser -->|"HTTP"| node_fastapi_main
node_fastapi_main -->|"registers routes"| node_api
node_fastapi_main -->|"mounts static client"| node_browser
node_api -->|"resolves services"| node_dependencies
node_api -->|"upload"| node_processor
node_processor -->|"persists source files"| node_staging
node_processor -->|"writes intermediates"| node_processed
node_processor -->|"normalizes content"| node_docling
node_processor -->|"segments and groups"| node_blingfire
node_processor -->|"updates lifecycle"| node_metadata_model
node_metadata_model -->|"stores records"| node_sqlite
node_processor -->|"indexes chunks"| node_retriever
node_retriever -->|"embeds chunks and queries"| node_minilm
node_retriever -->|"stores and searches vectors"| node_chromadb
node_api -->|"retrieve/search"| node_retriever
node_retriever -->|"reranks candidates"| node_cohere
node_api -->|"answer request"| node_generator
node_retriever -->|"retrieved context"| node_generator
node_generator -->|"RAG prompt"| node_gemini
node_api -->|"list/delete/reset"| node_metadata_model
node_workflow -->|"builds image"| node_dockerfile
node_workflow -->|"pushes and deploys"| node_aws_delivery
node_aws_delivery -.->|"runs container"| node_fastapi_main

click node_browser "https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/static/index.html"
click node_fastapi_main "https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/main.py"
click node_api "https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/api.py"
click node_dependencies "https://github.com/hermes-erm/polyvault-rag/blob/main/src/dependencies.py"
click node_processor "https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/document_processor.py"
click node_metadata_model "https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/model.py"
click node_retriever "https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/retriever.py"
click node_generator "https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/generator.py"
click node_workflow "https://github.com/hermes-erm/polyvault-rag/blob/main/.github/workflows/aws-ecs-deploy.yml"
click node_dockerfile "https://github.com/hermes-erm/polyvault-rag/blob/main/Dockerfile"

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_browser,node_fastapi_main,node_api,node_dependencies toneBlue
class node_processor,node_staging,node_processed toneAmber
class node_metadata_model,node_sqlite,node_retriever,node_chromadb toneMint
class node_docling,node_blingfire,node_minilm,node_cohere,node_generator,node_gemini toneRose
class node_workflow,node_dockerfile,node_aws_delivery toneIndigo
```

## Components

### Application

- [Browser client](https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/static/index.html): static client · `src/app/static/index.html`
- [FastAPI app](https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/main.py): application entrypoint · `src/app/main.py`
- [HTTP API](https://github.com/hermes-erm/polyvault-rag/blob/main/src/app/api.py): route layer · Upload, document, reset, retrieval, and answer endpoints. · `src/app/api.py`
- [Service composition](https://github.com/hermes-erm/polyvault-rag/blob/main/src/dependencies.py): dependency boundary · Creates shared services, sessions, and selected models. · `src/dependencies.py`

### Ingestion pipeline

- [Document processor](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/document_processor.py): async ingestion service · Normalizes uploads and produces semantic chunks. · `src/rag_system/document_processor.py`
- **Staging files**: pipeline storage
- **Processed files**: pipeline storage

### Persistence & retrieval

- [Document metadata](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/model.py): SQLAlchemy repository · Tracks pipeline lifecycle and document records. · `src/rag_system/model.py`
- **SQLite**: metadata database
- [Vector retriever](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/retriever.py): index and search service · Embeds chunks, manages vectors, and performs similarity lookup. · `src/rag_system/retriever.py`
- **ChromaDB**: persistent vector store

### Model services

- **Docling**: normalization service · Converts supported source formats to Markdown.
- **BlingFire**: segmentation service
- **MiniLM embeddings**: embedding model
- **Cohere reranker**: external ranking service · Credentials are supplied through environment variables.
- [RAG generator](https://github.com/hermes-erm/polyvault-rag/blob/main/src/rag_system/generator.py): answer service · Builds a context-constrained prompt. · `src/rag_system/generator.py`
- **Gemini**: external generation service · Credentials are supplied through environment variables.

### Deployment

- [ECS deploy workflow](https://github.com/hermes-erm/polyvault-rag/blob/main/.github/workflows/aws-ecs-deploy.yml): CI/CD pipeline · Builds, publishes, renders, and deploys on pushes to main. · `.github/workflows/aws-ecs-deploy.yml`
- [Container image](https://github.com/hermes-erm/polyvault-rag/blob/main/Dockerfile): runtime package · `Dockerfile`
- **ECR → ECS → NLB**: AWS deployment path · Health-checked ECS tasks are exposed through the Network Load Balancer and Elastic IP.

## Connections

- Browser client → FastAPI app: HTTP
- FastAPI app → HTTP API: registers routes
- FastAPI app → Browser client: mounts static client
- HTTP API → Service composition: resolves services
- HTTP API → Document processor: upload
- Document processor → Staging files: persists source files
- Document processor → Processed files: writes intermediates
- Document processor → Docling: normalizes content
- Document processor → BlingFire: segments and groups
- Document processor → Document metadata: updates lifecycle
- Document metadata → SQLite: stores records
- Document processor → Vector retriever: indexes chunks
- Vector retriever → MiniLM embeddings: embeds chunks and queries
- Vector retriever → ChromaDB: stores and searches vectors
- HTTP API → Vector retriever: retrieve/search
- Vector retriever → Cohere reranker: reranks candidates
- HTTP API → RAG generator: answer request
- Vector retriever → RAG generator: retrieved context
- RAG generator → Gemini: RAG prompt
- HTTP API → Document metadata: list/delete/reset · Deletion and reset coordinate metadata with vectors.
- ECS deploy workflow → Container image: builds image
- ECS deploy workflow → ECR → ECS → NLB: pushes and deploys
- ECR → ECS → NLB → FastAPI app: runs container