# amirmahdimtz/vision-similarity-service architecture

> Architecture diagram of the GitHub repository amirmahdimtz/vision-similarity-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amirmahdimtz/vision-similarity-service
- Repository: https://github.com/amirmahdimtz/vision-similarity-service

## Overview

Vision Similarity Service is a FastAPI application that accepts two uploaded images and returns their cosine-similarity score. Its workflow validates upload metadata and size, extracts and normalizes a YOLO embedding for each image, then computes and returns the bounded score. Configuration and dependency injection support application startup and component construction. The README documents the YOLO embedding approach; unsampled configuration details and any additional runtime behavior are not inferred.

Main entry points: [`src/infrastructure/utils/config_reader.py`](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/utils/config_reader.py) (Config reader), [`src/application/image_similarity/image_similarity_controller.py`](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/image_similarity/image_similarity_controller.py) (Similarity controller), [`src/application/web.py`](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/web.py) (Web service), [`src/infrastructure/ml/yolo_embedding_provider.py`](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/ml/yolo_embedding_provider.py) (YOLO embedding provider)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP application"]
  node_host["Application host<br/>[app.py]"]
  node_web["Web service<br/>[web.py]"]
  node_controller["Similarity controller"]
  node_response_dto["Score response"]
end

subgraph group_similarity["Similarity workflow"]
  node_similarity_service["Similarity calculation"]
  node_embedding_provider["YOLO embedding provider"]
end

subgraph group_infrastructure["Runtime infrastructure"]
  node_bootstrap["DI bootstrap<br/>[bootstrap.py]"]
  node_inject["Dependency injection<br/>[inject.py]"]
end

subgraph group_settings["Configuration"]
  node_config_reader["Config reader<br/>[config_reader.py]"]
  node_app_config["Application settings"]
  node_default_config["Default settings<br/>[appsettings.yaml]"]
end

node_client(("API client"))
node_yolo_runtime["Ultralytics YOLO"]

node_client -->|"sends requests"| node_web
node_host -->|"bootstraps DI"| node_bootstrap
node_host -->|"creates app"| node_web
node_web -->|"reads settings"| node_config_reader
node_web -->|"discovers and routes"| node_controller
node_controller -->|"compares images"| node_similarity_service
node_controller -->|"sets upload limit"| node_config_reader
node_controller -->|"returns score"| node_response_dto
node_similarity_service -->|"extracts embeddings"| node_embedding_provider
node_embedding_provider -->|"extracts features"| node_yolo_runtime
node_embedding_provider -->|"reads model path"| node_config_reader
node_bootstrap -->|"loads modules"| node_inject
node_app_config -->|"loads in development"| node_config_reader
node_default_config -->|"loads otherwise"| node_config_reader

click node_host "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/app.py"
click node_web "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/web.py"
click node_controller "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/image_similarity/image_similarity_controller.py"
click node_response_dto "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/image_similarity/dtos/image_similarity_dto.py"
click node_similarity_service "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/core/services/image_similarity/image_similarity_service.py"
click node_embedding_provider "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/ml/yolo_embedding_provider.py"
click node_bootstrap "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/di/bootstrap.py"
click node_inject "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/di/inject.py"
click node_config_reader "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/utils/config_reader.py"
click node_app_config "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/res/appsettings.development.yaml"
click node_default_config "https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/res/appsettings.yaml"

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_host,node_web,node_controller,node_response_dto,node_client toneBlue
class node_similarity_service,node_embedding_provider toneAmber
class node_bootstrap,node_inject toneMint
class node_config_reader,node_app_config,node_default_config toneRose
class node_yolo_runtime toneIndigo
```

## Components

### HTTP application

- [Application host](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/app.py): `src/host/app.py`
- [Web service](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/web.py): `src/application/web.py`
- [Similarity controller](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/image_similarity/image_similarity_controller.py): `src/application/image_similarity/image_similarity_controller.py`
- [Score response](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/application/image_similarity/dtos/image_similarity_dto.py): `src/application/image_similarity/dtos/image_similarity_dto.py`

### Similarity workflow

- [Similarity calculation](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/core/services/image_similarity/image_similarity_service.py): `src/core/services/image_similarity/image_similarity_service.py`
- [YOLO embedding provider](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/ml/yolo_embedding_provider.py): `src/infrastructure/ml/yolo_embedding_provider.py`

### Runtime infrastructure

- [DI bootstrap](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/di/bootstrap.py): `src/infrastructure/di/bootstrap.py`
- [Dependency injection](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/di/inject.py): `src/infrastructure/di/inject.py`

### Configuration

- [Config reader](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/infrastructure/utils/config_reader.py): `src/infrastructure/utils/config_reader.py`
- [Application settings](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/res/appsettings.development.yaml): `src/host/res/appsettings.development.yaml`
- [Default settings](https://github.com/amirmahdimtz/vision-similarity-service/blob/main/src/host/res/appsettings.yaml): `src/host/res/appsettings.yaml`

### Other components

- **API client**
- **Ultralytics YOLO**

## Connections

- API client → Web service: sends requests (evidence: `src/application/web.py`)
- Application host → DI bootstrap: bootstraps DI (evidence: `src/host/app.py`)
- Application host → Web service: creates app (evidence: `src/host/app.py`)
- Web service → Config reader: reads settings (evidence: `src/application/web.py`)
- Web service → Similarity controller: discovers and routes (evidence: `src/application/web.py`)
- Similarity controller → Similarity calculation: compares images (evidence: `src/application/image_similarity/image_similarity_controller.py`)
- Similarity controller → Config reader: sets upload limit (evidence: `src/application/image_similarity/image_similarity_controller.py`)
- Similarity controller → Score response: returns score (evidence: `src/application/image_similarity/image_similarity_controller.py`)
- Similarity calculation → YOLO embedding provider: extracts embeddings (evidence: `src/core/services/image_similarity/image_similarity_service.py`)
- YOLO embedding provider → Ultralytics YOLO: extracts features (evidence: `README.md`)
- YOLO embedding provider → Config reader: reads model path (evidence: `src/infrastructure/ml/yolo_embedding_provider.py`)
- DI bootstrap → Dependency injection: loads modules (evidence: `src/infrastructure/di/bootstrap.py`)
- Application settings → Config reader: loads in development (evidence: `src/infrastructure/utils/config_reader.py`)
- Default settings → Config reader: loads otherwise (evidence: `src/infrastructure/utils/config_reader.py`)
