# weesi/cinestream-api architecture

> Architecture diagram of the GitHub repository weesi/cinestream-api, 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/weesi/cinestream-api
- Repository: https://github.com/weesi/cinestream-api

## Overview

CineStream is an internal FastAPI service for email-based user setup, media-interaction tracking, and personalized recommendations. The main user path is client → API routes → event and state services → Elasticsearch; recommendation requests then combine real-time content similarity with stored collaborative clusters, with a popularity fallback for cold starts. The README documents tracking and onboarding capabilities; sampled code confirms the route/service flow and recommendation engines. The batch is exposed as an admin endpoint; no scheduler is shown. Some service internals were only partially excerpted, so uncertain links are omitted.

Main entry points: [`app/main.py`](https://github.com/weesi/cinestream-api/blob/main/app/main.py) (FastAPI application), [`app/routers/users.py`](https://github.com/weesi/cinestream-api/blob/main/app/routers/users.py) (User action routes), [`app/services/hybrid_engine.py`](https://github.com/weesi/cinestream-api/blob/main/app/services/hybrid_engine.py) (Hybrid recommendation), [`app/services/collab_engine.py`](https://github.com/weesi/cinestream-api/blob/main/app/services/collab_engine.py) (Collaborative clusters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_application["FastAPI application<br/>[main.py]"]
  node_auth_routes["Auth and onboarding<br/>[auth.py]"]
  node_user_routes["User action routes<br/>[users.py]"]
  node_recommendation_routes["Recommendation routes<br/>[recommendations.py]"]
end

subgraph group_tracking["Interaction tracking"]
  node_event_models["Event schemas<br/>[events.py]"]
  node_event_service["Event and state service<br/>[event_service.py]"]
  node_stats_service["User statistics<br/>[stats_service.py]"]
end

subgraph group_recommendation["Recommendation"]
  node_hybrid_engine["Hybrid recommendation<br/>[hybrid_engine.py]"]
  node_content_engine["Content recommendations<br/>[content_engine.py]"]
  node_collab_engine["Collaborative clusters<br/>[collab_engine.py]"]
  node_scoring["Interaction scoring<br/>[scoring.py]"]
end

subgraph group_storage["Search and state"]
  node_configuration["Index configuration<br/>[config.py]"]
  node_elasticsearch_client["Elasticsearch client<br/>[elasticsearch.py]"]
  node_elasticsearch[("Elasticsearch indices")]
end

node_client(("Web client"))

node_client -->|"calls API"| node_application
node_application -->|"registers routes"| node_auth_routes
node_application -->|"registers routes"| node_user_routes
node_application -->|"registers routes"| node_recommendation_routes
node_auth_routes -->|"gets client"| node_elasticsearch_client
node_auth_routes -->|"reads and writes users"| node_elasticsearch
node_user_routes -->|"validates payloads"| node_event_models
node_user_routes -->|"delegates actions"| node_event_service
node_user_routes -->|"requests statistics"| node_stats_service
node_event_service -->|"writes and reads state"| node_elasticsearch
node_stats_service -->|"aggregates user data"| node_elasticsearch
node_recommendation_routes -->|"requests recommendations"| node_hybrid_engine
node_recommendation_routes -->|"runs batch"| node_collab_engine
node_hybrid_engine -->|"runs content engine"| node_content_engine
node_hybrid_engine -->|"runs collaborative engine"| node_collab_engine
node_hybrid_engine -->|"reads preferences and metadata"| node_elasticsearch
node_content_engine -->|"computes interaction weights"| node_scoring
node_content_engine -->|"reads interactions and embeddings"| node_elasticsearch
node_collab_engine -->|"computes interaction weights"| node_scoring
node_collab_engine -->|"loads data and stores clusters"| node_elasticsearch
node_elasticsearch_client -->|"loads settings"| node_configuration
node_elasticsearch_client -->|"initializes indices"| node_elasticsearch

click node_application "https://github.com/weesi/cinestream-api/blob/main/app/main.py"
click node_auth_routes "https://github.com/weesi/cinestream-api/blob/main/app/routers/auth.py"
click node_user_routes "https://github.com/weesi/cinestream-api/blob/main/app/routers/users.py"
click node_recommendation_routes "https://github.com/weesi/cinestream-api/blob/main/app/routers/recommendations.py"
click node_event_models "https://github.com/weesi/cinestream-api/blob/main/app/models/events.py"
click node_event_service "https://github.com/weesi/cinestream-api/blob/main/app/services/event_service.py"
click node_stats_service "https://github.com/weesi/cinestream-api/blob/main/app/services/stats_service.py"
click node_hybrid_engine "https://github.com/weesi/cinestream-api/blob/main/app/services/hybrid_engine.py"
click node_content_engine "https://github.com/weesi/cinestream-api/blob/main/app/services/content_engine.py"
click node_collab_engine "https://github.com/weesi/cinestream-api/blob/main/app/services/collab_engine.py"
click node_scoring "https://github.com/weesi/cinestream-api/blob/main/app/services/scoring.py"
click node_configuration "https://github.com/weesi/cinestream-api/blob/main/app/core/config.py"
click node_elasticsearch_client "https://github.com/weesi/cinestream-api/blob/main/app/core/elasticsearch.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_application,node_auth_routes,node_user_routes,node_recommendation_routes,node_client toneBlue
class node_event_models,node_event_service,node_stats_service toneAmber
class node_hybrid_engine,node_content_engine,node_collab_engine,node_scoring toneMint
class node_configuration,node_elasticsearch_client,node_elasticsearch toneRose
```

## Components

### API and identity

- [FastAPI application](https://github.com/weesi/cinestream-api/blob/main/app/main.py): `app/main.py`
- [Auth and onboarding](https://github.com/weesi/cinestream-api/blob/main/app/routers/auth.py): `app/routers/auth.py`
- [User action routes](https://github.com/weesi/cinestream-api/blob/main/app/routers/users.py): `app/routers/users.py`
- [Recommendation routes](https://github.com/weesi/cinestream-api/blob/main/app/routers/recommendations.py): `app/routers/recommendations.py`

### Interaction tracking

- [Event schemas](https://github.com/weesi/cinestream-api/blob/main/app/models/events.py): `app/models/events.py`
- [Event and state service](https://github.com/weesi/cinestream-api/blob/main/app/services/event_service.py): `app/services/event_service.py`
- [User statistics](https://github.com/weesi/cinestream-api/blob/main/app/services/stats_service.py): `app/services/stats_service.py`

### Recommendation

- [Hybrid recommendation](https://github.com/weesi/cinestream-api/blob/main/app/services/hybrid_engine.py): `app/services/hybrid_engine.py`
- [Content recommendations](https://github.com/weesi/cinestream-api/blob/main/app/services/content_engine.py): `app/services/content_engine.py`
- [Collaborative clusters](https://github.com/weesi/cinestream-api/blob/main/app/services/collab_engine.py): `app/services/collab_engine.py`
- [Interaction scoring](https://github.com/weesi/cinestream-api/blob/main/app/services/scoring.py): `app/services/scoring.py`

### Search and state

- [Index configuration](https://github.com/weesi/cinestream-api/blob/main/app/core/config.py): `app/core/config.py`
- [Elasticsearch client](https://github.com/weesi/cinestream-api/blob/main/app/core/elasticsearch.py): `app/core/elasticsearch.py`
- **Elasticsearch indices**

### Other components

- **Web client**

## Connections

- Web client → FastAPI application: calls API (evidence: `README.md`)
- FastAPI application → Auth and onboarding: registers routes (evidence: `app/main.py`)
- FastAPI application → User action routes: registers routes (evidence: `app/main.py`)
- FastAPI application → Recommendation routes: registers routes (evidence: `app/main.py`)
- Auth and onboarding → Elasticsearch client: gets client (evidence: `app/routers/auth.py`)
- Auth and onboarding → Elasticsearch indices: reads and writes users (evidence: `app/routers/auth.py`)
- User action routes → Event schemas: validates payloads (evidence: `app/routers/users.py`)
- User action routes → Event and state service: delegates actions (evidence: `app/routers/users.py`)
- User action routes → User statistics: requests statistics (evidence: `app/routers/users.py`)
- Event and state service → Elasticsearch indices: writes and reads state (evidence: `app/services/event_service.py`)
- User statistics → Elasticsearch indices: aggregates user data (evidence: `app/services/stats_service.py`)
- Recommendation routes → Hybrid recommendation: requests recommendations (evidence: `app/routers/recommendations.py`)
- Recommendation routes → Collaborative clusters: runs batch (evidence: `app/routers/recommendations.py`)
- Hybrid recommendation → Content recommendations: runs content engine (evidence: `app/services/hybrid_engine.py`)
- Hybrid recommendation → Collaborative clusters: runs collaborative engine (evidence: `app/services/hybrid_engine.py`)
- Hybrid recommendation → Elasticsearch indices: reads preferences and metadata (evidence: `app/services/hybrid_engine.py`)
- Content recommendations → Interaction scoring: computes interaction weights (evidence: `app/services/content_engine.py`)
- Content recommendations → Elasticsearch indices: reads interactions and embeddings (evidence: `app/services/content_engine.py`)
- Collaborative clusters → Interaction scoring: computes interaction weights (evidence: `app/services/collab_engine.py`)
- Collaborative clusters → Elasticsearch indices: loads data and stores clusters (evidence: `app/services/collab_engine.py`)
- Elasticsearch client → Index configuration: loads settings (evidence: `app/core/elasticsearch.py`)
- Elasticsearch client → Elasticsearch indices: initializes indices (evidence: `app/core/elasticsearch.py`)
