# nhutminhit/vector-space-model architecture

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

- Interactive diagram: https://gitdiagram.com/nhutminhit/vector-space-model
- Repository: https://github.com/nhutminhit/vector-space-model

## Overview

Anime Vector Space Model is a semantic-search application with a FastAPI API and web UI, plus a notebook-based analysis workflow. The main user path is a free-text or similar-anime request through a router and controller, then query embedding and Milvus retrieval; a separate TF-IDF baseline provides sparse search. The import path cleans anime data, builds documents, encodes them, and stores vectors. The README also documents model comparison and evaluation. Some notebook and UI internals are not excerpted, so those connections are shown only where documented.

Main entry points: [`apps/services/search_service.py`](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/search_service.py) (Dense search and import), [`apps/main.py`](https://github.com/nhutminhit/vector-space-model/blob/main/apps/main.py) (FastAPI app), [`apps/services/data_loader.py`](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/data_loader.py) (Anime preprocessing), [`apps/cli.py`](https://github.com/nhutminhit/vector-space-model/blob/main/apps/cli.py) (Import and stats CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and UI"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_search_routes["Search routes<br/>[search_router.py]"]
  node_import_routes["Import routes<br/>[import_router.py]"]
  node_tfidf_routes["TF-IDF routes<br/>[tfidf.py]"]
  node_request_schemas["Request schemas<br/>[schemas.py]"]
  node_web_ui["Web UI<br/>[app.js]"]
end

subgraph group_ingest["Data and ingestion"]
  node_import_controller["Import controller"]
  node_data_loader["Anime preprocessing<br/>[data_loader.py]"]
  node_search_service["Dense search and import<br/>[search_service.py]"]
end

subgraph group_retrieval["Search methods"]
  node_search_controller["Search controller"]
  node_embedding["Embedding models<br/>[embedding.py]"]
  node_milvus[("Milvus vector store<br/>[milvus_store.py]")]
  node_tfidf_service["TF-IDF search<br/>[tfidf_search.py]"]
end

subgraph group_analysis["Research and operations"]
  node_evaluation["Retrieval evaluation<br/>[evaluation.py]"]
  node_notebook["VSM analysis"]
  node_cli["Import and stats CLI<br/>[cli.py]"]
  node_config["Model and settings config<br/>[config.py]"]
end

node_user(("Search user"))

node_user -->|"sends requests"| node_fastapi
node_fastapi -->|"registers routes"| node_search_routes
node_fastapi -->|"registers routes"| node_import_routes
node_fastapi -->|"registers routes"| node_tfidf_routes
node_fastapi -->|"mounts UI"| node_web_ui
node_search_routes -->|"uses schemas"| node_request_schemas
node_import_routes -->|"uses schemas"| node_request_schemas
node_search_routes -->|"delegates search"| node_search_controller
node_import_routes -->|"delegates import"| node_import_controller
node_import_controller -->|"loads anime"| node_data_loader
node_import_controller -->|"ensures import"| node_search_service
node_search_controller -->|"runs retrieval"| node_search_service
node_search_controller -->|"loads similar source"| node_data_loader
node_search_service -->|"loads documents"| node_data_loader
node_search_service -->|"encodes passages and queries"| node_embedding
node_search_service -->|"creates and searches collections"| node_milvus
node_tfidf_routes -->|"loads anime"| node_data_loader
node_tfidf_routes -->|"runs sparse search"| node_tfidf_service
node_cli -->|"loads anime"| node_data_loader
node_cli -->|"downloads models"| node_embedding
node_cli -->|"imports data"| node_search_service
node_cli -->|"reads stats"| node_milvus
node_notebook -->|"evaluates retrieval"| node_evaluation
node_evaluation -->|"uses embeddings"| node_embedding
node_evaluation -->|"uses vector search"| node_milvus
node_evaluation -->|"compares baseline"| node_tfidf_service
node_search_service -->|"reads model registry"| node_config
node_embedding -->|"reads model settings"| node_config
node_milvus -->|"reads store settings"| node_config

click node_fastapi "https://github.com/nhutminhit/vector-space-model/blob/main/apps/main.py"
click node_search_routes "https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/search_router.py"
click node_import_routes "https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/import_router.py"
click node_tfidf_routes "https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/tfidf.py"
click node_request_schemas "https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/schemas.py"
click node_web_ui "https://github.com/nhutminhit/vector-space-model/blob/main/apps/static/app.js"
click node_import_controller "https://github.com/nhutminhit/vector-space-model/blob/main/apps/controller/import_controller.py"
click node_search_controller "https://github.com/nhutminhit/vector-space-model/blob/main/apps/controller/search_controller.py"
click node_data_loader "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/data_loader.py"
click node_search_service "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/search_service.py"
click node_embedding "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/embedding.py"
click node_milvus "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/milvus_store.py"
click node_tfidf_service "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/tfidf_search.py"
click node_evaluation "https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/evaluation.py"
click node_notebook "https://github.com/nhutminhit/vector-space-model/blob/main/vector-space-model.ipynb"
click node_cli "https://github.com/nhutminhit/vector-space-model/blob/main/apps/cli.py"
click node_config "https://github.com/nhutminhit/vector-space-model/blob/main/apps/config.py"

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_fastapi,node_search_routes,node_import_routes,node_tfidf_routes,node_request_schemas,node_web_ui,node_user toneBlue
class node_import_controller,node_data_loader,node_search_service toneAmber
class node_search_controller,node_embedding,node_milvus,node_tfidf_service toneMint
class node_evaluation,node_notebook,node_cli,node_config toneRose
```

## Components

### API and UI

- [FastAPI app](https://github.com/nhutminhit/vector-space-model/blob/main/apps/main.py): `apps/main.py`
- [Search routes](https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/search_router.py): `apps/router/search_router.py`
- [Import routes](https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/import_router.py): `apps/router/import_router.py`
- [TF-IDF routes](https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/tfidf.py): `apps/router/tfidf.py`
- [Request schemas](https://github.com/nhutminhit/vector-space-model/blob/main/apps/router/schemas.py): `apps/router/schemas.py`
- [Web UI](https://github.com/nhutminhit/vector-space-model/blob/main/apps/static/app.js): `apps/static/app.js`

### Data and ingestion

- [Import controller](https://github.com/nhutminhit/vector-space-model/blob/main/apps/controller/import_controller.py): `apps/controller/import_controller.py`
- [Anime preprocessing](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/data_loader.py): `apps/services/data_loader.py`
- [Dense search and import](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/search_service.py): `apps/services/search_service.py`

### Search methods

- [Search controller](https://github.com/nhutminhit/vector-space-model/blob/main/apps/controller/search_controller.py): `apps/controller/search_controller.py`
- [Embedding models](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/embedding.py): `apps/services/embedding.py`
- [Milvus vector store](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/milvus_store.py): `apps/services/milvus_store.py`
- [TF-IDF search](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/tfidf_search.py): `apps/services/tfidf_search.py`

### Research and operations

- [Retrieval evaluation](https://github.com/nhutminhit/vector-space-model/blob/main/apps/services/evaluation.py): `apps/services/evaluation.py`
- [VSM analysis](https://github.com/nhutminhit/vector-space-model/blob/main/vector-space-model.ipynb): `vector-space-model.ipynb`
- [Import and stats CLI](https://github.com/nhutminhit/vector-space-model/blob/main/apps/cli.py): `apps/cli.py`
- [Model and settings config](https://github.com/nhutminhit/vector-space-model/blob/main/apps/config.py): `apps/config.py`

### Other components

- **Search user**

## Connections

- Search user → FastAPI app: sends requests (evidence: `README.md`)
- FastAPI app → Search routes: registers routes (evidence: `apps/main.py`)
- FastAPI app → Import routes: registers routes (evidence: `apps/main.py`)
- FastAPI app → TF-IDF routes: registers routes (evidence: `apps/main.py`)
- FastAPI app → Web UI: mounts UI (evidence: `apps/main.py`)
- Search routes → Request schemas: uses schemas (evidence: `apps/router/search_router.py`)
- Import routes → Request schemas: uses schemas (evidence: `apps/router/import_router.py`)
- Search routes → Search controller: delegates search (evidence: `apps/router/search_router.py`)
- Import routes → Import controller: delegates import (evidence: `apps/router/import_router.py`)
- Import controller → Anime preprocessing: loads anime (evidence: `apps/controller/import_controller.py`)
- Import controller → Dense search and import: ensures import (evidence: `apps/controller/import_controller.py`)
- Search controller → Dense search and import: runs retrieval (evidence: `apps/controller/search_controller.py`)
- Search controller → Anime preprocessing: loads similar source (evidence: `apps/controller/search_controller.py`)
- Dense search and import → Anime preprocessing: loads documents (evidence: `apps/services/search_service.py`)
- Dense search and import → Embedding models: encodes passages and queries (evidence: `apps/services/search_service.py`)
- Dense search and import → Milvus vector store: creates and searches collections (evidence: `apps/services/search_service.py`)
- TF-IDF routes → Anime preprocessing: loads anime (evidence: `apps/router/tfidf.py`)
- TF-IDF routes → TF-IDF search: runs sparse search (evidence: `apps/router/tfidf.py`)
- Import and stats CLI → Anime preprocessing: loads anime (evidence: `apps/cli.py`)
- Import and stats CLI → Embedding models: downloads models (evidence: `apps/cli.py`)
- Import and stats CLI → Dense search and import: imports data (evidence: `apps/cli.py`)
- Import and stats CLI → Milvus vector store: reads stats (evidence: `apps/cli.py`)
- VSM analysis → Retrieval evaluation: evaluates retrieval (evidence: `README.md`)
- Retrieval evaluation → Embedding models: uses embeddings (evidence: `apps/services/evaluation.py`)
- Retrieval evaluation → Milvus vector store: uses vector search (evidence: `apps/services/evaluation.py`)
- Retrieval evaluation → TF-IDF search: compares baseline (evidence: `apps/services/evaluation.py`)
- Dense search and import → Model and settings config: reads model registry (evidence: `apps/services/search_service.py`)
- Embedding models → Model and settings config: reads model settings (evidence: `apps/services/embedding.py`)
- Milvus vector store → Model and settings config: reads store settings (evidence: `apps/services/milvus_store.py`)
