# syedaakibhossain-prog/cinmatch architecture

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

- Interactive diagram: https://gitdiagram.com/syedaakibhossain-prog/cinmatch
- Repository: https://github.com/syedaakibhossain-prog/cinmatch

## Overview

CineMatch serves movie-title searches through a browser UI and FastAPI: validated titles enter the recommendation model, which ranks similar films and enriches them with TMDB posters before returning results for cards and detail views. A separate request-control branch applies per-IP Redis sliding-window limits. README-described UI and deployment details are represented only where runtime behavior is supported; source excerpts do not show the Lua script or every frontend feature implementation.

Main entry points: [`backend/main.py`](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/main.py) (FastAPI routes), [`backend/src/recomender.py`](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/recomender.py) (Similarity ranking), [`backend/middleware/rate_limiter.py`](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/middleware/rate_limiter.py) (IP rate limit), [`frontend/app.js`](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/frontend/app.js) (Search and results UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_frontend["Search and results UI<br/>[app.js]"]
end

subgraph group_api["API request handling"]
  node_api_service["FastAPI routes<br/>[main.py]"]
  node_validation["Title validation<br/>[validators.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_recommend["Recommendation service"]
  node_recommender["Similarity ranking<br/>[recomender.py]"]
  node_movie_data[("Movie model artifacts<br/>[movies.pkl]")]
  node_vector_data[("Sparse movie vectors<br/>[movie_vectors.npz]")]
  node_poster_service["TMDB poster API"]
end

subgraph group_limits["Rate limiting"]
  node_limiter["IP rate limit<br/>[rate_limiter.py]"]
  node_redis_client["Redis client<br/>[redis_client.py]"]
  node_redis[("Redis store")]
end

node_visitor(("Movie seeker"))

node_visitor -->|"searches titles"| node_frontend
node_frontend -->|"requests recommendations"| node_api_service
node_api_service -->|"applies dependency"| node_limiter
node_api_service -->|"validates title"| node_validation
node_api_service -->|"requests recommendations"| node_recommender
node_recommender -->|"loads titles"| node_movie_data
node_recommender -->|"loads vectors"| node_vector_data
node_recommender -->|"fetches posters"| node_poster_service
node_limiter -->|"uses client"| node_redis_client
node_redis_client -->|"reads URL"| node_settings
node_limiter -->|"reads limits"| node_settings
node_limiter -->|"checks window"| node_redis
node_frontend -->|"renders results"| node_visitor

click node_frontend "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/frontend/app.js"
click node_api_service "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/main.py"
click node_validation "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/validators.py"
click node_recommender "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/recomender.py"
click node_movie_data "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/movies.pkl"
click node_vector_data "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/movie_vectors.npz"
click node_limiter "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/middleware/rate_limiter.py"
click node_redis_client "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/shared/redis_client.py"
click node_settings "https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/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_frontend toneBlue
class node_api_service,node_validation,node_settings toneAmber
class node_recommender,node_movie_data,node_vector_data,node_poster_service toneMint
class node_limiter,node_redis_client,node_redis toneRose
class node_visitor toneIndigo
```

## Components

### Web client

- [Search and results UI](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/frontend/app.js): `frontend/app.js`

### API request handling

- [FastAPI routes](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/main.py): `backend/main.py`
- [Title validation](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/validators.py): `backend/src/validators.py`
- [Runtime settings](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/config.py): `backend/src/config.py`

### Recommendation service

- [Similarity ranking](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/recomender.py): `backend/src/recomender.py`
- [Movie model artifacts](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/movies.pkl): `backend/src/movies.pkl`
- [Sparse movie vectors](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/src/movie_vectors.npz): `backend/src/movie_vectors.npz`
- **TMDB poster API**

### Rate limiting

- [IP rate limit](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/middleware/rate_limiter.py): `backend/middleware/rate_limiter.py`
- [Redis client](https://github.com/syedaakibhossain-prog/cinmatch/blob/main/backend/shared/redis_client.py): `backend/shared/redis_client.py`
- **Redis store**

### Other components

- **Movie seeker**

## Connections

- Movie seeker → Search and results UI: searches titles (evidence: `README.md`)
- Search and results UI → FastAPI routes: requests recommendations (evidence: `frontend/app.js`)
- FastAPI routes → IP rate limit: applies dependency (evidence: `backend/main.py`)
- FastAPI routes → Title validation: validates title (evidence: `backend/main.py`)
- FastAPI routes → Similarity ranking: requests recommendations (evidence: `backend/main.py`)
- Similarity ranking → Movie model artifacts: loads titles (evidence: `backend/src/recomender.py`)
- Similarity ranking → Sparse movie vectors: loads vectors (evidence: `backend/src/recomender.py`)
- Similarity ranking → TMDB poster API: fetches posters (evidence: `backend/src/recomender.py`)
- IP rate limit → Redis client: uses client (evidence: `backend/middleware/rate_limiter.py`)
- Redis client → Runtime settings: reads URL (evidence: `backend/shared/redis_client.py`)
- IP rate limit → Runtime settings: reads limits (evidence: `backend/middleware/rate_limiter.py`)
- IP rate limit → Redis store: checks window (evidence: `README.md`)
- Search and results UI → Movie seeker: renders results (evidence: `frontend/app.js`)
