# michelabdelmalek/freightrag architecture

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

- Interactive diagram: https://gitdiagram.com/michelabdelmalek/freightrag
- Repository: https://github.com/michelabdelmalek/freightrag

## Overview

FreightRAG is a multi-tenant logistics-document RAG system; this repository’s implemented product covers document ingestion, tenant-scoped storage, and ranked-chunk search (not answer generation). The main workflow is tenant files → section chunks → Ollama embeddings → Postgres, followed by authenticated API search. The graph also includes document reads, tenant resolution, and migration as a distinct operational capability. Edges use README statements or indexed source references; links to unsampled search internals are marked unverified.

Main entry points: [`src/FreightRag.Core/Application/IngestDocument.cs`](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/IngestDocument.cs) (Ingest handler), [`src/FreightRag.Ingest/FolderIngestor.cs`](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Ingest/FolderIngestor.cs) (Folder ingestor), [`src/FreightRag.Core/Infrastructure/Persistence/FreightRagDbContext.cs`](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/FreightRagDbContext.cs) (EF database context), [`src/FreightRag.Core/Application/Search/SearchChunks.cs`](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Search/SearchChunks.cs) (Chunk search use case)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_folder_ingestor["Folder ingestor<br/>[FolderIngestor.cs]"]
  node_ingest_host["Ingest host<br/>[Program.cs]"]
end

subgraph group_domain["Domain and application"]
  node_ingest_handler["Ingest handler<br/>[IngestDocument.cs]"]
  node_section_chunker["Section chunker<br/>[SectionChunker.cs]"]
  node_freight_document["Document aggregate<br/>[FreightDocument.cs]"]
  node_embedding_port["Embedding port"]
  node_repository_port["Document repository port"]
  node_search_handler["Chunk search use case<br/>[SearchChunks.cs]"]
end

subgraph group_infra["Infrastructure"]
  node_tenant_directory["Tenant directory"]
  node_ollama_embeddings["Ollama embeddings"]
  node_ef_repository["EF document repository"]
  node_db_context["EF database context"]
  node_chunk_search["Chunk search adapter<br/>[EfChunkSearch.cs]"]
  node_document_queries["Document queries"]
  node_migrator["Schema migrator<br/>[Program.cs]"]
  node_db_migrator["Database migrator"]
end

subgraph group_api["HTTP API"]
  node_search_endpoint["Search endpoint<br/>[SearchEndpoints.cs]"]
  node_document_endpoint["Document endpoints"]
  node_api_key_auth["API key authentication"]
  node_api_key_store["API key store<br/>[ApiKeyStore.cs]"]
end

node_file_operator(("Ingest operator"))
node_tenant_files["Tenant text files"]
node_ollama["Ollama model"]
node_postgres[("Postgres + pgvector")]
node_api_user(("API client"))

node_file_operator -->|"starts run"| node_ingest_host
node_tenant_files -->|"reads files"| node_folder_ingestor
node_ingest_host -->|"runs"| node_folder_ingestor
node_folder_ingestor -->|"submits documents"| node_ingest_handler
node_ingest_handler -->|"splits text"| node_section_chunker
node_ingest_handler -->|"creates aggregate"| node_freight_document
node_folder_ingestor -->|"resolves tenant"| node_tenant_directory
node_ingest_handler -->|"resolves tenant"| node_tenant_directory
node_ingest_handler -->|"embeds chunks"| node_embedding_port
node_ollama_embeddings -->|"implements"| node_embedding_port
node_ollama_embeddings -->|"requests vectors"| node_ollama
node_ingest_handler -->|"stores document"| node_repository_port
node_ef_repository -.->|"implements"| node_repository_port
node_ef_repository -.->|"persists records"| node_db_context
node_db_context -->|"reads and writes"| node_postgres
node_api_user -->|"authenticates"| node_api_key_auth
node_api_key_auth -->|"checks key"| node_api_key_store
node_api_user -->|"searches"| node_search_endpoint
node_search_endpoint -->|"dispatches search"| node_search_handler
node_search_handler -.->|"queries chunks"| node_chunk_search
node_search_handler -.->|"embeds query"| node_embedding_port
node_chunk_search -.->|"queries vectors"| node_db_context
node_api_user -->|"manages documents"| node_document_endpoint
node_document_endpoint -->|"uses ingestion"| node_ingest_handler
node_document_endpoint -.->|"reads documents"| node_document_queries
node_document_queries -.->|"reads records"| node_db_context
node_migrator -->|"applies migrations"| node_db_migrator
node_db_migrator -->|"upgrades schema"| node_postgres

click node_folder_ingestor "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Ingest/FolderIngestor.cs"
click node_ingest_host "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Ingest/Program.cs"
click node_ingest_handler "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/IngestDocument.cs"
click node_section_chunker "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Domain/SectionChunker.cs"
click node_freight_document "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Domain/FreightDocument.cs"
click node_tenant_directory "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Tenants/ConfiguredTenantDirectory.cs"
click node_embedding_port "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Ports/IEmbeddingService.cs"
click node_ollama_embeddings "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Embedding/OllamaEmbeddingService.cs"
click node_repository_port "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Ports/IDocumentRepository.cs"
click node_ef_repository "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfDocumentRepository.cs"
click node_db_context "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/FreightRagDbContext.cs"
click node_search_endpoint "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Endpoints/SearchEndpoints.cs"
click node_search_handler "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Search/SearchChunks.cs"
click node_chunk_search "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfChunkSearch.cs"
click node_document_endpoint "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Endpoints/DocumentEndpoints.cs"
click node_document_queries "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfDocumentQueries.cs"
click node_api_key_auth "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Security/ApiKeyAuthenticationHandler.cs"
click node_api_key_store "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Security/ApiKeyStore.cs"
click node_migrator "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Migrator/Program.cs"
click node_db_migrator "https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/DatabaseMigrator.cs"

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_folder_ingestor,node_ingest_host,node_api_user toneBlue
class node_ingest_handler,node_section_chunker,node_freight_document,node_embedding_port,node_repository_port,node_search_handler,node_postgres toneAmber
class node_tenant_directory,node_ollama_embeddings,node_ef_repository,node_db_context,node_chunk_search,node_document_queries,node_migrator,node_db_migrator toneMint
class node_search_endpoint,node_document_endpoint,node_api_key_auth,node_api_key_store toneRose
class node_file_operator,node_tenant_files,node_ollama toneIndigo
```

## Components

### Ingestion

- [Folder ingestor](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Ingest/FolderIngestor.cs): `src/FreightRag.Ingest/FolderIngestor.cs`
- [Ingest host](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Ingest/Program.cs): `src/FreightRag.Ingest/Program.cs`

### Domain and application

- [Ingest handler](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/IngestDocument.cs): `src/FreightRag.Core/Application/IngestDocument.cs`
- [Section chunker](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Domain/SectionChunker.cs): `src/FreightRag.Core/Domain/SectionChunker.cs`
- [Document aggregate](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Domain/FreightDocument.cs): `src/FreightRag.Core/Domain/FreightDocument.cs`
- [Embedding port](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Ports/IEmbeddingService.cs): `src/FreightRag.Core/Application/Ports/IEmbeddingService.cs`
- [Document repository port](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Ports/IDocumentRepository.cs): `src/FreightRag.Core/Application/Ports/IDocumentRepository.cs`
- [Chunk search use case](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Application/Search/SearchChunks.cs): `src/FreightRag.Core/Application/Search/SearchChunks.cs`

### Infrastructure

- [Tenant directory](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Tenants/ConfiguredTenantDirectory.cs): `src/FreightRag.Core/Infrastructure/Tenants/ConfiguredTenantDirectory.cs`
- [Ollama embeddings](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Embedding/OllamaEmbeddingService.cs): `src/FreightRag.Core/Infrastructure/Embedding/OllamaEmbeddingService.cs`
- [EF document repository](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfDocumentRepository.cs): `src/FreightRag.Core/Infrastructure/Persistence/EfDocumentRepository.cs`
- [EF database context](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/FreightRagDbContext.cs): `src/FreightRag.Core/Infrastructure/Persistence/FreightRagDbContext.cs`
- [Chunk search adapter](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfChunkSearch.cs): `src/FreightRag.Core/Infrastructure/Persistence/EfChunkSearch.cs`
- [Document queries](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/EfDocumentQueries.cs): `src/FreightRag.Core/Infrastructure/Persistence/EfDocumentQueries.cs`
- [Schema migrator](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Migrator/Program.cs): `src/FreightRag.Migrator/Program.cs`
- [Database migrator](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Core/Infrastructure/Persistence/DatabaseMigrator.cs): `src/FreightRag.Core/Infrastructure/Persistence/DatabaseMigrator.cs`

### HTTP API

- [Search endpoint](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Endpoints/SearchEndpoints.cs): `src/FreightRag.Api/Endpoints/SearchEndpoints.cs`
- [Document endpoints](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Endpoints/DocumentEndpoints.cs): `src/FreightRag.Api/Endpoints/DocumentEndpoints.cs`
- [API key authentication](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Security/ApiKeyAuthenticationHandler.cs): `src/FreightRag.Api/Security/ApiKeyAuthenticationHandler.cs`
- [API key store](https://github.com/michelabdelmalek/freightrag/blob/main/src/FreightRag.Api/Security/ApiKeyStore.cs): `src/FreightRag.Api/Security/ApiKeyStore.cs`

### Other components

- **Ingest operator**
- **Tenant text files**
- **Ollama model**
- **Postgres + pgvector**
- **API client**

## Connections

- Ingest operator → Ingest host: starts run (evidence: `README.md`)
- Tenant text files → Folder ingestor: reads files (evidence: `src/FreightRag.Ingest/FolderIngestor.cs`)
- Ingest host → Folder ingestor: runs (evidence: `src/FreightRag.Ingest/Program.cs`)
- Folder ingestor → Ingest handler: submits documents (evidence: `src/FreightRag.Ingest/FolderIngestor.cs`)
- Ingest handler → Section chunker: splits text (evidence: `src/FreightRag.Core/Application/IngestDocument.cs`)
- Ingest handler → Document aggregate: creates aggregate (evidence: `src/FreightRag.Core/Application/IngestDocument.cs`)
- Folder ingestor → Tenant directory: resolves tenant (evidence: `src/FreightRag.Ingest/FolderIngestor.cs`)
- Ingest handler → Tenant directory: resolves tenant (evidence: `src/FreightRag.Core/Application/IngestDocument.cs`)
- Ingest handler → Embedding port: embeds chunks (evidence: `src/FreightRag.Core/Application/IngestDocument.cs`)
- Ollama embeddings → Embedding port: implements (evidence: `src/FreightRag.Core/Infrastructure/Embedding/OllamaEmbeddingService.cs`)
- Ollama embeddings → Ollama model: requests vectors (evidence: `src/FreightRag.Core/Infrastructure/Embedding/OllamaEmbeddingService.cs`)
- Ingest handler → Document repository port: stores document (evidence: `src/FreightRag.Core/Application/IngestDocument.cs`)
- EF document repository → Document repository port: implements (evidence: `src/FreightRag.Core/Infrastructure/Persistence/EfDocumentRepository.cs`)
- EF document repository → EF database context: persists records (evidence: `src/FreightRag.Core/Infrastructure/Persistence/EfDocumentRepository.cs`)
- EF database context → Postgres + pgvector: reads and writes (evidence: `README.md`)
- API client → API key authentication: authenticates (evidence: `README.md`)
- API key authentication → API key store: checks key (evidence: `src/FreightRag.Api/Security/ApiKeyAuthenticationHandler.cs`)
- API client → Search endpoint: searches (evidence: `README.md`)
- Search endpoint → Chunk search use case: dispatches search (evidence: `src/FreightRag.Api/Endpoints/SearchEndpoints.cs`)
- Chunk search use case → Chunk search adapter: queries chunks
- Chunk search use case → Embedding port: embeds query
- Chunk search adapter → EF database context: queries vectors
- API client → Document endpoints: manages documents (evidence: `README.md`)
- Document endpoints → Ingest handler: uses ingestion (evidence: `README.md`)
- Document endpoints → Document queries: reads documents
- Document queries → EF database context: reads records
- Schema migrator → Database migrator: applies migrations (evidence: `src/FreightRag.Migrator/Program.cs`)
- Database migrator → Postgres + pgvector: upgrades schema (evidence: `README.md`)
