# adarsh-menon/komorebi-semantic-image-search-system architecture

> Architecture diagram of the GitHub repository adarsh-menon/komorebi-semantic-image-search-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/adarsh-menon/komorebi-semantic-image-search-system
- Repository: https://github.com/adarsh-menon/komorebi-semantic-image-search-system

## Overview

1. **What this system is**
   - This repository is a Python-based semantic image search service. Its core job is to ingest images, derive semantic representations from them, store those representations in a vector index, and later answer text/image search requests by retrieving similar images.

2. **Primary runtime shape**
   - The main application lives under `src/api` and is organized like a FastAPI-style service: an app entrypoint, route modules, dependency wiring, request/response schemas, and middleware.
   - The service is packaged for local development, containerized deployment, and Kubernetes rollout.

3. **Request-facing API layer**
   - `src/api/routes` splits the external surface into:
     - `health` for liveness/readiness,
     - `upload` for ingesting images,
     - `indexer` for indexing workflows,
     - `search` for semantic retrieval.
   - `src/api/middleware` adds cross-cutting controls such as authentication and rate limiting, so those concerns are enforced before requests reach the search/indexing logic.

4. **Core image-search pipeline**
   - The main semantic flow appears to be:
     1. image upload or ingestion,
     2. storage of raw assets,
     3. preprocessing,
     4. embedding generation,
     5. optional caption generation,
     6. persistence of vectors and metadata,
     7. query-time retrieval and reranking.
   - The service layer in `src/services` is where this pipeline is decomposed into reusable steps rather than being embedded in the API handlers.

5. **Model subsystem**
   - `src/models` contains wrappers/loaders for the ML backends: CLIP, BLIP, GIT, and sentence-transformer style models.
   - `model_loader.py` suggests a centralized loading/selection boundary so the rest of the system does not depend directly on individual model implementations.
   - This subsystem is the main compute-heavy part of the application and is likely the source of both image embeddings and generated captions used to enrich search quality.

6. **Search-time intelligence**
   - `query_rewriter.py` suggests user queries may be expanded or normalized before retrieval.
   - `reranker_service.py` indicates the system likely performs two-stage search: an initial vector lookup followed by a second-pass relevance refinement.
   - `caption_service.py` implies captions are not only generated for ingestion but may also support ranking or explainability.

7. **Vector and metadata storage boundary**
   - `src/vectorstore` abstracts similarity search backends:
     - `qdrant_store.py` for a persistent vector database,
     - `faiss_store.py` for local/in-process similarity search,
     - `metadata_store.py` for non-vector attributes tied to image records.
   - This is a key architectural boundary: the search layer talks to a vector-store interface, while the implementation can vary between embedded/local and external DB-backed retrieval.

8. **Raw file storage boundary**
   - `src/storage` provides adapters for `local_storage`, `s3_storage`, and `gcs_storage`.
   - This means image binaries are stored separately from embeddings/metadata, and the system can be deployed against local disk or cloud object storage depending on environment.
   - `utils_image.py` likely supports image normalization or file handling around these storage adapters.

9. **Background and batch work**
   - `src/tasks` separates non-request work from the API:
     - `index_task.py` for bulk or asynchronous indexing,
     - `cleanup_task.py` for retention or housekeeping,
     - `workers.py` for task execution orchestration.
   - This suggests the application is not purely synchronous; ingestion/indexing can be offloaded from the request path to improve throughput and reliability.

10. **Configuration and observability**
    - `src/core` contains shared runtime configuration, constants, exceptions, and logging setup.
    - `src/monitoring` adds metrics, tracing, and Sentry logging, indicating the service is instrumented for production diagnostics rather than being a simple prototype.
    - YAML config files under `komorebi_semantic_image_search/config` and environment-based settings imply the runtime is heavily configuration-driven.

11. **Deployment and infrastructure**
    - `infra/Dockerfile` and `infra/docker-compose.yml` support containerized local and production-like environments.
    - `infra/k8s` contains config, secrets, deployment, service, and HPA manifests, so the service is intended to run horizontally in Kubernetes.
    - `infra/nginx/nginx.conf` suggests an edge reverse proxy in front of the app, likely for routing, buffering, or request limits.
    - GitHub Actions CI/CD files show automated build/test/deploy paths.

12. **Validation, experimentation, and quality**
    - `tests` covers API, captioning, embeddings, storage, and vectorstore behavior, reflecting the main subsystem boundaries.
    - `notebooks` indicate offline experimentation and evaluation, including recall-at-k and model comparison, which is important for a semantic search system where retrieval quality is a primary product metric.

13. **Likely end-to-end architecture diagram**
    - A good diagram would show:
      - clients calling the API,
      - middleware handling auth/rate limiting,
      - request handlers invoking services,
      - services calling ML models, storage backends, and vector stores,
      - tasks handling asynchronous indexing/cleanup,
      - monitoring spanning the whole service,
      - deployment behind Nginx in containers/Kubernetes with object storage and vector DB as external dependencies.

14. **Important architectural takeaway**
    - The repo is organized around clear separations between API, ML inference, object storage, vector search, and background processing. That separation is the main design feature and should be preserved in any architecture diagram.

Main entry points: [`komorebi_semantic_image_search/src/services/image_service.py`](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/image_service.py) (Image Flow), [`komorebi_semantic_image_search/src/api/main.py`](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/api/main.py) (API App), [`komorebi_semantic_image_search/src/api/routes`](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/routes) (Routes), [`komorebi_semantic_image_search/src/services/vectorstore_service.py`](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/vectorstore_service.py) (Vector Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_client(("Client<br/>external caller"))
end

subgraph group_api["API Layer"]
  node_api_main["API App<br/>[main.py]"]
  node_api_mw["Middleware<br/>cross-cutting"]
  node_api_routes["Routes<br/>http handlers"]
  node_api_schemas["Schemas<br/>request-response models"]
end

subgraph group_core["Core Services"]
  node_image_service["Image Flow<br/>ingest orchestration<br/>[image_service.py]"]
  node_preprocess["Preprocess<br/>image normalization"]
  node_embed["Embeddings<br/>feature generation"]
  node_caption["Captioning<br/>multimodal generation<br/>[caption_service.py]"]
  node_rewrite["Query Rewrite<br/>query normalization<br/>[query_rewriter.py]"]
  node_rerank["Reranker<br/>ranking stage"]
  node_vstore_service["Vector Service<br/>search facade"]
  node_model_loader["Model Loader<br/>model selection<br/>[model_loader.py]"]
end

subgraph group_data["Data Backends"]
  node_storage[("Object Storage<br/>asset backend")]
  node_vectorstores[("Vector Store<br/>similarity backend")]
end

subgraph group_ops["Operations"]
  node_tasks["Workers<br/>background jobs<br/>[workers.py]"]
  node_monitoring["Monitoring<br/>observability"]
  node_infra["Infra<br/>deployment"]
end

node_client -->|"HTTP requests"| node_api_main
node_api_main -->|"applies"| node_api_mw
node_api_main -->|"registers"| node_api_routes
node_api_routes -->|"validates"| node_api_schemas
node_api_routes -->|"ingest/search"| node_image_service
node_api_routes -->|"retrieve"| node_vstore_service
node_image_service -->|"prepare"| node_preprocess
node_image_service -->|"encode"| node_embed
node_image_service -->|"enrich"| node_caption
node_preprocess -->|"read/write"| node_storage
node_embed -->|"loads models"| node_model_loader
node_caption -->|"loads models"| node_model_loader
node_image_service -->|"persist"| node_vectorstores
node_vstore_service -->|"query"| node_vectorstores
node_vstore_service -->|"normalize"| node_rewrite
node_vstore_service -->|"refine"| node_rerank
node_tasks -->|"batch ingest"| node_image_service
node_tasks -->|"cleanup/index"| node_vectorstores
node_monitoring -->|"instrument"| node_api_main
node_monitoring -->|"instrument"| node_tasks
node_infra -->|"deploys"| node_api_main
node_infra -->|"configures"| node_storage
node_infra -->|"configures"| node_vectorstores

click node_api_main "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/api/main.py"
click node_api_mw "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/middleware"
click node_api_routes "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/routes"
click node_api_schemas "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/schemas"
click node_image_service "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/image_service.py"
click node_preprocess "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/preprocessing_service.py"
click node_embed "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/embedding_service.py"
click node_caption "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/caption_service.py"
click node_rewrite "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/query_rewriter.py"
click node_rerank "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/reranker_service.py"
click node_vstore_service "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/vectorstore_service.py"
click node_model_loader "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/models/model_loader.py"
click node_storage "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/storage"
click node_vectorstores "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/vectorstore"
click node_tasks "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/tasks/workers.py"
click node_monitoring "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/monitoring"
click node_infra "https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/infra"

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_client toneBlue
class node_api_main,node_api_mw,node_api_routes,node_api_schemas toneAmber
class node_image_service,node_preprocess,node_embed,node_caption,node_rewrite,node_rerank,node_vstore_service,node_model_loader toneMint
class node_storage,node_vectorstores toneRose
class node_tasks,node_monitoring,node_infra toneIndigo
```

## Components

### Clients

External request sources and user-facing entry points

- **Client**: external caller · User or application issuing upload and search requests

### API Layer

HTTP service entrypoint, routing, schemas, and middleware

- [API App](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/api/main.py): fastapi app · Service entrypoint and application wiring · `komorebi_semantic_image_search/src/api/main.py`
- [Middleware](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/middleware): cross-cutting · Authentication and rate limiting before request handlers · `komorebi_semantic_image_search/src/api/middleware`
- [Routes](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/routes): http handlers · Health, upload, indexer, and search endpoints · `komorebi_semantic_image_search/src/api/routes`
- [Schemas](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/api/schemas): request-response models · API payload definitions for indexing and search · `komorebi_semantic_image_search/src/api/schemas`

### Core Services

Image processing, ML inference, and search orchestration

- [Image Flow](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/image_service.py): ingest orchestration · Coordinates upload, preprocessing, embedding, captioning, and persistence · `komorebi_semantic_image_search/src/services/image_service.py`
- [Preprocess](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/preprocessing_service.py): image normalization · Transforms raw images into model-ready inputs · `komorebi_semantic_image_search/src/services/preprocessing_service.py`
- [Embeddings](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/embedding_service.py): feature generation · Generates semantic vectors from images or text · `komorebi_semantic_image_search/src/services/embedding_service.py`
- [Captioning](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/caption_service.py): multimodal generation · Produces descriptive captions to enrich retrieval · `komorebi_semantic_image_search/src/services/caption_service.py`
- [Query Rewrite](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/query_rewriter.py): query normalization · Expands or normalizes search queries before retrieval · `komorebi_semantic_image_search/src/services/query_rewriter.py`
- [Reranker](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/reranker_service.py): ranking stage · Refines initial similarity results into a final ordering · `komorebi_semantic_image_search/src/services/reranker_service.py`
- [Vector Service](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/services/vectorstore_service.py): search facade · Abstracts similarity lookup and metadata access · `komorebi_semantic_image_search/src/services/vectorstore_service.py`
- [Model Loader](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/models/model_loader.py): model selection · Centralizes loading of CLIP, BLIP, GIT, and sentence transformers · `komorebi_semantic_image_search/src/models/model_loader.py`

### Data Backends

Object storage and vector/metadata persistence

- [Object Storage](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/storage): asset backend · Stores raw image binaries on local disk or cloud object storage · `komorebi_semantic_image_search/src/storage`
- [Vector Store](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/vectorstore): similarity backend · Persistent or local vector search implementation with metadata support · `komorebi_semantic_image_search/src/vectorstore`

### Operations

Background work, monitoring, and deployment

- [Workers](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/blob/main/komorebi_semantic_image_search/src/tasks/workers.py): background jobs · Asynchronous indexing and cleanup execution · `komorebi_semantic_image_search/src/tasks/workers.py`
- [Monitoring](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/src/monitoring): observability · Metrics, tracing, and error reporting · `komorebi_semantic_image_search/src/monitoring`
- [Infra](https://github.com/adarsh-menon/komorebi-semantic-image-search-system/tree/main/komorebi_semantic_image_search/infra): deployment · Container, Kubernetes, and reverse-proxy deployment assets · `komorebi_semantic_image_search/infra`

## Connections

- Client → API App: HTTP requests · Clients call the application entrypoint
- API App → Middleware: applies · Middleware runs before handlers
- API App → Routes: registers · Routes are mounted into the app
- Routes → Schemas: validates · Handlers use request and response schemas
- Routes → Image Flow: ingest/search · Upload and indexing endpoints invoke service orchestration
- Routes → Vector Service: retrieve · Search endpoints access vector retrieval
- Image Flow → Preprocess: prepare · Raw images are normalized before inference
- Image Flow → Embeddings: encode · Images are converted into semantic vectors
- Image Flow → Captioning: enrich · Captions can be generated during ingestion
- Preprocess → Object Storage: read/write · Image files are loaded from and stored to object storage
- Embeddings → Model Loader: loads models · Embedding generation depends on selected ML backends
- Captioning → Model Loader: loads models · Caption generation depends on multimodal backends
- Image Flow → Vector Store: persist · Embeddings and metadata are written to the vector layer
- Vector Service → Vector Store: query · Similarity search is delegated to the backend store
- Vector Service → Query Rewrite: normalize · Queries may be expanded before retrieval
- Vector Service → Reranker: refine · Initial matches are reranked into final results
- Workers → Image Flow: batch ingest · Workers reuse the ingestion pipeline for async jobs
- Workers → Vector Store: cleanup/index · Background jobs maintain stored vectors and metadata
- Monitoring → API App: instrument · Observability spans the request service
- Monitoring → Workers: instrument · Background processing is also observed
- Infra → API App: deploys · Container and Kubernetes assets package the service
- Infra → Object Storage: configures · Deployment can target local or cloud object storage
- Infra → Vector Store: configures · Deployment can target local or external vector search
