How weesi/cinestream-api works
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: main.py FastAPI application · users.py User action routes · hybrid_engine.py Hybrid recommendation · collab_engine.py Collaborative clusters
Components 15
API and identity
- FastAPI application
app/main.py - Auth and onboarding
app/routers/auth.py - User action routes
app/routers/users.py - Recommendation routes
app/routers/recommendations.py
Interaction tracking
- Event schemas
app/models/events.py - Event and state service
app/services/event_service.py - User statistics
app/services/stats_service.py
Recommendation
- Hybrid recommendation
app/services/hybrid_engine.py - Content recommendations
app/services/content_engine.py - Collaborative clusters
app/services/collab_engine.py - Interaction scoring
app/services/scoring.py
Search and state
- Index configuration
app/core/config.py - Elasticsearch client
app/core/elasticsearch.py - Elasticsearch indices
Other components
- Web client
Connections 22
- Web client → FastAPI application: calls API
README.md - FastAPI application → Auth and onboarding: registers routes
app/main.py - FastAPI application → User action routes: registers routes
app/main.py - FastAPI application → Recommendation routes: registers routes
app/main.py - Auth and onboarding → Elasticsearch client: gets client
app/routers/auth.py - Auth and onboarding → Elasticsearch indices: reads and writes users
app/routers/auth.py - User action routes → Event schemas: validates payloads
app/routers/users.py - User action routes → Event and state service: delegates actions
app/routers/users.py - User action routes → User statistics: requests statistics
app/routers/users.py - Event and state service → Elasticsearch indices: writes and reads state
app/services/event_service.py - User statistics → Elasticsearch indices: aggregates user data
app/services/stats_service.py - Recommendation routes → Hybrid recommendation: requests recommendations
app/routers/recommendations.py - Recommendation routes → Collaborative clusters: runs batch
app/routers/recommendations.py - Hybrid recommendation → Content recommendations: runs content engine
app/services/hybrid_engine.py - Hybrid recommendation → Collaborative clusters: runs collaborative engine
app/services/hybrid_engine.py - Hybrid recommendation → Elasticsearch indices: reads preferences and metadata
app/services/hybrid_engine.py - Content recommendations → Interaction scoring: computes interaction weights
app/services/content_engine.py - Content recommendations → Elasticsearch indices: reads interactions and embeddings
app/services/content_engine.py - Collaborative clusters → Interaction scoring: computes interaction weights
app/services/collab_engine.py - Collaborative clusters → Elasticsearch indices: loads data and stores clusters
app/services/collab_engine.py - Elasticsearch client → Index configuration: loads settings
app/core/elasticsearch.py - Elasticsearch client → Elasticsearch indices: initializes indices
app/core/elasticsearch.py