# kw4ngk1m/multimodal-recsys architecture

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

- Interactive diagram: https://gitdiagram.com/kw4ngk1m/multimodal-recsys
- Repository: https://github.com/kw4ngk1m/multimodal-recsys

## Overview

This repository combines a multimodal shopping search and recommendation API with offline model research, A/B experimentation, and user simulation. The main serving flow is a user request routed by FastAPI to search or recommendation logic, which uses catalog data and stored embeddings; interaction events support experiment measurement. Offline RecSys and paper experiments develop and evaluate models, while the simulator generates persona-based behavior for testing. Several router and subsystem implementations were not excerpted, so their internal call paths are omitted or marked unverified.

Main entry points: [`backend/app/main.py`](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/main.py) (FastAPI App), [`backend/app/routers/search.py`](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/search.py) (Search API), [`backend/app/models.py`](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/models.py) (Application Database), [`simulator/__main__.py`](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/__main__.py) (Simulation Runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["API Serving"]
  node_api["FastAPI App<br/>[main.py]"]
  node_search_route["Search API<br/>[search.py]"]
  node_search_core["Search Scoring<br/>[search_core.py]"]
  node_recommend_route["Recommendation API<br/>[recommend.py]"]
  node_recommenders["Recommenders"]
end

subgraph group_data["Catalog and Events"]
  node_events_route["Event API<br/>[events.py]"]
  node_catalog["Catalog Index<br/>[catalog_index.py]"]
  node_feature_store["Feature Store<br/>[feature_store.py]"]
  node_database[("Application Database<br/>[models.py]")]
end

subgraph group_experiments["Experiments and Models"]
  node_admin_routes["Admin and Metrics APIs<br/>[admin.py]"]
  node_ab_services["A/B and Metrics<br/>[ab.py]"]
end

subgraph group_interfaces["User and Admin UI"]
  node_dashboard["Dashboard<br/>[app.py]"]
  node_dashboard_data["Dashboard Data<br/>[data.py]"]
end

subgraph group_research["Research and Simulation"]
  node_offline_recsys["Offline Training and Evaluation"]
  node_paper_pipeline["Paper Experiments"]
  node_sim_engine["Behavior Engine<br/>[engine.py]"]
  node_sim_data["Simulation Data<br/>[data.py]"]
  node_simulator["Simulation Runner<br/>[__main__.py]"]
  node_monitoring["Monitoring Runner<br/>[runner.py]"]
end

node_shopper(("Shopper"))

node_shopper -->|"uses"| node_api
node_api -->|"mounts routes"| node_search_route
node_api -->|"mounts routes"| node_recommend_route
node_api -->|"mounts routes"| node_events_route
node_api -->|"mounts routes"| node_admin_routes
node_search_route -->|"scores queries"| node_search_core
node_search_route -->|"gets index"| node_catalog
node_search_route -->|"reads items"| node_database
node_api -->|"warms index"| node_catalog
node_recommend_route -.->|"selects model"| node_recommenders
node_recommend_route -.->|"loads user data"| node_database
node_events_route -->|"writes events"| node_database
node_events_route -->|"updates features"| node_feature_store
node_admin_routes -.->|"manages models"| node_database
node_admin_routes -.->|"measures experiments"| node_ab_services
node_dashboard -->|"uses data"| node_dashboard_data
node_dashboard -.->|"calls service"| node_api
node_offline_recsys -.->|"evaluates methods"| node_paper_pipeline
node_simulator -->|"loads data"| node_sim_data
node_simulator -.->|"runs behavior"| node_sim_engine
node_sim_engine -->|"uses data"| node_sim_data
node_simulator -.->|"feeds A/B logs"| node_api

click node_api "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/main.py"
click node_search_route "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/search.py"
click node_search_core "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/search_core.py"
click node_recommend_route "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/recommend.py"
click node_recommenders "https://github.com/kw4ngk1m/multimodal-recsys/tree/main/backend/app/recommenders"
click node_events_route "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/events.py"
click node_catalog "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/catalog_index.py"
click node_feature_store "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/feature_store.py"
click node_database "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/models.py"
click node_admin_routes "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/admin.py"
click node_ab_services "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/ab.py"
click node_dashboard "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/dashboard/app.py"
click node_dashboard_data "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/dashboard/data.py"
click node_offline_recsys "https://github.com/kw4ngk1m/multimodal-recsys/tree/main/recsys"
click node_paper_pipeline "https://github.com/kw4ngk1m/multimodal-recsys/tree/main/paper/msrs_paper"
click node_sim_engine "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/engine.py"
click node_sim_data "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/data.py"
click node_simulator "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/__main__.py"
click node_monitoring "https://github.com/kw4ngk1m/multimodal-recsys/blob/main/monitoring/runner.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_api,node_search_route,node_search_core,node_recommend_route,node_recommenders toneBlue
class node_events_route,node_catalog,node_feature_store,node_database toneAmber
class node_admin_routes,node_ab_services toneMint
class node_dashboard,node_dashboard_data toneRose
class node_offline_recsys,node_paper_pipeline,node_sim_engine,node_sim_data,node_simulator,node_monitoring,node_shopper toneIndigo
```

## Components

### API Serving

- [FastAPI App](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/main.py): `backend/app/main.py`
- [Search API](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/search.py): `backend/app/routers/search.py`
- [Search Scoring](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/search_core.py): `backend/app/services/search_core.py`
- [Recommendation API](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/recommend.py): `backend/app/routers/recommend.py`
- [Recommenders](https://github.com/kw4ngk1m/multimodal-recsys/tree/main/backend/app/recommenders): `backend/app/recommenders`

### Catalog and Events

- [Event API](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/events.py): `backend/app/routers/events.py`
- [Catalog Index](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/catalog_index.py): `backend/app/services/catalog_index.py`
- [Feature Store](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/feature_store.py): `backend/app/services/feature_store.py`
- [Application Database](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/models.py): `backend/app/models.py`

### Experiments and Models

- [Admin and Metrics APIs](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/routers/admin.py): `backend/app/routers/admin.py`
- [A/B and Metrics](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/backend/app/services/ab.py): `backend/app/services/ab.py`

### User and Admin UI

- [Dashboard](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/dashboard/app.py): `dashboard/app.py`
- [Dashboard Data](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/dashboard/data.py): `dashboard/data.py`

### Research and Simulation

- [Offline Training and Evaluation](https://github.com/kw4ngk1m/multimodal-recsys/tree/main/recsys): `recsys`
- [Paper Experiments](https://github.com/kw4ngk1m/multimodal-recsys/tree/main/paper/msrs_paper): `paper/msrs_paper`
- [Behavior Engine](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/engine.py): `simulator/engine.py`
- [Simulation Data](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/data.py): `simulator/data.py`
- [Simulation Runner](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/simulator/__main__.py): `simulator/__main__.py`
- [Monitoring Runner](https://github.com/kw4ngk1m/multimodal-recsys/blob/main/monitoring/runner.py): `monitoring/runner.py`

### Other components

- **Shopper**

## Connections

- Shopper → FastAPI App: uses (evidence: `README.md`)
- FastAPI App → Search API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI App → Recommendation API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI App → Event API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI App → Admin and Metrics APIs: mounts routes (evidence: `backend/app/main.py`)
- Search API → Search Scoring: scores queries (evidence: `backend/app/routers/search.py`)
- Search API → Catalog Index: gets index (evidence: `backend/app/routers/search.py`)
- Search API → Application Database: reads items (evidence: `backend/app/routers/search.py`)
- FastAPI App → Catalog Index: warms index (evidence: `backend/app/main.py`)
- Recommendation API → Recommenders: selects model
- Recommendation API → Application Database: loads user data
- Event API → Application Database: writes events (evidence: `backend/app/routers/events.py`)
- Event API → Feature Store: updates features (evidence: `backend/app/routers/events.py`)
- Admin and Metrics APIs → Application Database: manages models
- Admin and Metrics APIs → A/B and Metrics: measures experiments
- Dashboard → Dashboard Data: uses data (evidence: `dashboard/app.py`)
- Dashboard → FastAPI App: calls service
- Offline Training and Evaluation → Paper Experiments: evaluates methods
- Simulation Runner → Simulation Data: loads data (evidence: `simulator/server.py`)
- Simulation Runner → Behavior Engine: runs behavior
- Behavior Engine → Simulation Data: uses data (evidence: `simulator/engine.py`)
- Simulation Runner → FastAPI App: feeds A/B logs
