# asphyxiaovo/anime-recommendation-api architecture

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

- Interactive diagram: https://gitdiagram.com/asphyxiaovo/anime-recommendation-api
- Repository: https://github.com/asphyxiaovo/anime-recommendation-api

## Overview

This repository provides an anime recommendation API backed by a content-based recommender, plus an offline training and evaluation workflow. API clients request health, anime details, or similar titles; the API delegates to the recommender, which loads a saved bundle or builds one from the catalog, then ranks items by cosine similarity. Offline, training settings drive catalog loading, TF-IDF bundle creation, similarity evaluation, and artifact logging. The excerpts establish these calls and configuration references; some artifact and dataset connections are inferred from explicit paths, while unsampled internals are not expanded.

Main entry points: [`training/train_content_based.py`](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/train_content_based.py) (Training Workflow), [`app/services/recommender.py`](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/services/recommender.py) (Anime Recommender), [`app/main.py`](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/main.py) (API Routes), [`training/pipeline.py`](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/pipeline.py) (Feature Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Recommendation API"]
  node_api["API Routes<br/>[main.py]"]
  node_schemas["Response Schemas<br/>[schemas.py]"]
  node_settings["Runtime Settings<br/>[config.py]"]
end

subgraph group_model["Recommendation Runtime"]
  node_recommender["Anime Recommender<br/>[recommender.py]"]
end

subgraph group_training["Model Training"]
  node_pipeline["Feature Pipeline<br/>[pipeline.py]"]
  node_trainer["Training Workflow"]
  node_evaluation["Similarity Evaluation<br/>[evaluate.py]"]
end

subgraph group_ops["Data and Tracking"]
  node_catalog[("Anime Catalog<br/>[anime_catalog.csv]")]
  node_bundle[("Model Bundle")]
  node_train_config["Training Config<br/>[content_based.yaml]"]
end

node_client(("API Client"))
node_mlflow["MLflow Tracking"]

node_client -->|"requests"| node_api
node_api -->|"dispatches"| node_recommender
node_api -->|"reads defaults"| node_settings
node_api -->|"returns typed"| node_schemas
node_recommender -->|"reads paths"| node_settings
node_recommender -->|"builds fallback"| node_pipeline
node_recommender -->|"loads artifact"| node_bundle
node_recommender -->|"loads fallback data"| node_catalog
node_pipeline -->|"reads CSV"| node_catalog
node_trainer -->|"loads settings"| node_train_config
node_trainer -->|"builds and saves"| node_pipeline
node_trainer -->|"evaluates bundle"| node_evaluation
node_trainer -->|"logs run"| node_mlflow
node_trainer -->|"writes artifact"| node_bundle

click node_api "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/main.py"
click node_schemas "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/schemas.py"
click node_settings "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/core/config.py"
click node_recommender "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/services/recommender.py"
click node_catalog "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/data/external/anime_catalog.csv"
click node_pipeline "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/pipeline.py"
click node_bundle "https://github.com/asphyxiaovo/anime-recommendation-api/tree/main/models/production"
click node_trainer "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/train_content_based.py"
click node_evaluation "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/evaluate.py"
click node_train_config "https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/experiments/configs/content_based.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_api,node_schemas,node_settings,node_client toneBlue
class node_recommender toneAmber
class node_pipeline,node_trainer,node_evaluation toneMint
class node_catalog,node_bundle,node_train_config toneRose
class node_mlflow toneIndigo
```

## Components

### Recommendation API

- [API Routes](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/main.py): `app/main.py`
- [Response Schemas](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/schemas.py): `app/schemas.py`
- [Runtime Settings](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/core/config.py): `app/core/config.py`

### Recommendation Runtime

- [Anime Recommender](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/app/services/recommender.py): `app/services/recommender.py`

### Model Training

- [Feature Pipeline](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/pipeline.py): `training/pipeline.py`
- [Training Workflow](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/train_content_based.py): `training/train_content_based.py`
- [Similarity Evaluation](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/training/evaluate.py): `training/evaluate.py`

### Data and Tracking

- [Anime Catalog](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/data/external/anime_catalog.csv): `data/external/anime_catalog.csv`
- [Model Bundle](https://github.com/asphyxiaovo/anime-recommendation-api/tree/main/models/production): `models/production`
- [Training Config](https://github.com/asphyxiaovo/anime-recommendation-api/blob/main/experiments/configs/content_based.yaml): `experiments/configs/content_based.yaml`

### Other components

- **API Client**
- **MLflow Tracking**

## Connections

- API Client → API Routes: requests
- API Routes → Anime Recommender: dispatches (evidence: `app/main.py`)
- API Routes → Runtime Settings: reads defaults (evidence: `app/main.py`)
- API Routes → Response Schemas: returns typed (evidence: `app/main.py`)
- Anime Recommender → Runtime Settings: reads paths (evidence: `app/services/recommender.py`)
- Anime Recommender → Feature Pipeline: builds fallback (evidence: `app/services/recommender.py`)
- Anime Recommender → Model Bundle: loads artifact (evidence: `app/services/recommender.py`)
- Anime Recommender → Anime Catalog: loads fallback data (evidence: `app/services/recommender.py`)
- Feature Pipeline → Anime Catalog: reads CSV (evidence: `training/pipeline.py`)
- Training Workflow → Training Config: loads settings (evidence: `training/train_content_based.py`)
- Training Workflow → Feature Pipeline: builds and saves (evidence: `training/train_content_based.py`)
- Training Workflow → Similarity Evaluation: evaluates bundle (evidence: `training/train_content_based.py`)
- Training Workflow → MLflow Tracking: logs run (evidence: `training/train_content_based.py`)
- Training Workflow → Model Bundle: writes artifact (evidence: `training/train_content_based.py`)