# mmileticc/movielensbackendktor architecture

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

- Interactive diagram: https://gitdiagram.com/mmileticc/movielensbackendktor
- Repository: https://github.com/mmileticc/movielensbackendktor

## Overview

Movienee is a Ktor backend for movie discovery and social tracking. The main workflow serves authenticated Android requests through route modules, which combine TMDB metadata, cinema availability, AI search, and user-specific data stored in PostgreSQL. A separate scraping lifecycle gathers regional cinema listings, enriches them with TMDB IDs, persists them, and refreshes semantic indexes. The README documents these flows; some route and scraper implementations were not sampled, so their links are shown only where documented or otherwise evidenced.

Main entry points: [`src/main/kotlin/Application.kt`](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/Application.kt) (Ktor application), [`src/main/kotlin/db`](https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/db) (Domain repositories), [`src/main/kotlin/services/TmdbService.kt`](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/TmdbService.kt) (TMDB catalog), [`src/main/kotlin/scraping/ScraperJob.kt`](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/ScraperJob.kt) (Scraping lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and sessions"]
  node_application["Ktor application<br/>[Application.kt]"]
  node_routing["Auth and vision routes<br/>[Routing.kt]"]
end

subgraph group_cinema["Cinema discovery"]
  node_scraping["Scraping lifecycle<br/>[ScraperJob.kt]"]
  node_scraper_engine["Concurrent scraper engine"]
  node_chain_scrapers["Cinema chain scrapers"]
  node_scraped_model["Cinema listings<br/>[ScrapedMovie.kt]"]
  node_semantic_index["Semantic cinema index"]
end

subgraph group_movie["Movie services"]
  node_movie_routes["Movie routes<br/>[MovieRouting.kt]"]
  node_gemini["Gemini AI<br/>[GeminiService.kt]"]
  node_tmdb["TMDB catalog<br/>[TmdbService.kt]"]
  node_omdb["OMDb ratings<br/>[OmdbService.kt]"]
end

subgraph group_social["Social and personalization"]
  node_actions_routes["User action routes"]
  node_friends_routes["Friend routes<br/>[FriendsRouting.kt]"]
  node_comments_routes["Comment routes<br/>[CommentsRouting.kt]"]
  node_taste["Taste profiles"]
  node_social_routes["Sharing and notifications"]
end

subgraph group_data["Persistence"]
  node_repositories["Domain repositories"]
  node_schema["Database tables"]
  node_database[("PostgreSQL")]
end

node_android(("Android app"))
node_external_cinemas["Cinema websites"]
node_external_ai["Google Gemini API"]
node_external_tmdb["TMDB API"]
node_external_omdb["OMDb API"]
node_firebase["Firebase services"]

node_android -->|"sends requests"| node_application
node_application -->|"registers routes"| node_routing
node_application -->|"registers routes"| node_movie_routes
node_application -->|"registers routes"| node_actions_routes
node_application -->|"registers routes"| node_friends_routes
node_application -->|"registers routes"| node_comments_routes
node_application -->|"starts lifecycle"| node_scraping
node_scraping -->|"runs scrapers"| node_scraper_engine
node_scraper_engine -->|"dispatches concurrently"| node_chain_scrapers
node_chain_scrapers -->|"scrapes listings"| node_external_cinemas
node_scraper_engine -->|"produces listings"| node_scraped_model
node_scraping -->|"enriches movie IDs"| node_tmdb
node_scraping -->|"persists listings"| node_repositories
node_scraping -->|"refreshes index"| node_semantic_index
node_semantic_index -->|"loads listings"| node_repositories
node_semantic_index -->|"embeds text"| node_external_ai
node_routing -->|"recognizes images"| node_gemini
node_routing -->|"resolves candidates"| node_tmdb
node_routing -->|"searches repertoire"| node_semantic_index
node_movie_routes -->|"fetches movie data"| node_tmdb
node_movie_routes -.->|"fetches ratings"| node_omdb
node_movie_routes -->|"gets genre affinities"| node_taste
node_movie_routes -->|"reads movie data"| node_repositories
node_actions_routes -->|"stores user actions"| node_repositories
node_actions_routes -->|"caches movie details"| node_tmdb
node_friends_routes -->|"manages friendships"| node_repositories
node_friends_routes -->|"compares tastes"| node_taste
node_friends_routes -->|"fetches movie data"| node_tmdb
node_comments_routes -.->|"manages comments"| node_repositories
node_application -->|"initializes services"| node_repositories
node_repositories -->|"queries and updates"| node_schema
node_schema -->|"stores records"| node_database
node_application -->|"initializes admin SDK"| node_firebase
node_application -->|"warms API client"| node_external_tmdb
node_gemini -->|"calls model API"| node_external_ai
node_tmdb -->|"requests catalog data"| node_external_tmdb
node_omdb -->|"requests ratings"| node_external_omdb

click node_application "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/Application.kt"
click node_routing "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/Routing.kt"
click node_movie_routes "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/MovieRouting.kt"
click node_actions_routes "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/UserActionsRouting.kt"
click node_friends_routes "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/FriendsRouting.kt"
click node_comments_routes "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/CommentsRouting.kt"
click node_scraping "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/ScraperJob.kt"
click node_scraper_engine "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/ScrapingEngineConcurrent.kt"
click node_chain_scrapers "https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/scraping/scraper"
click node_scraped_model "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/model/ScrapedMovie.kt"
click node_semantic_index "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/CinemaSemanticIndex.kt"
click node_gemini "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/GeminiService.kt"
click node_tmdb "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/TmdbService.kt"
click node_omdb "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/OmdbService.kt"
click node_taste "https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/db/TasteProfileRepository.kt"
click node_social_routes "https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin"
click node_repositories "https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/db"
click node_schema "https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/db"

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_routing toneBlue
class node_scraping,node_scraper_engine,node_chain_scrapers,node_scraped_model,node_semantic_index toneAmber
class node_movie_routes,node_gemini,node_tmdb,node_omdb,node_external_ai,node_external_tmdb,node_external_omdb toneMint
class node_actions_routes,node_friends_routes,node_comments_routes,node_taste,node_social_routes toneRose
class node_repositories,node_schema,node_database,node_android,node_external_cinemas,node_firebase toneIndigo
```

## Components

### API and sessions

- [Ktor application](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/Application.kt): `src/main/kotlin/Application.kt`
- [Auth and vision routes](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/Routing.kt): `src/main/kotlin/Routing.kt`

### Cinema discovery

- [Scraping lifecycle](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/ScraperJob.kt): `src/main/kotlin/scraping/ScraperJob.kt`
- [Concurrent scraper engine](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/ScrapingEngineConcurrent.kt): `src/main/kotlin/scraping/ScrapingEngineConcurrent.kt`
- [Cinema chain scrapers](https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/scraping/scraper): `src/main/kotlin/scraping/scraper`
- [Cinema listings](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/scraping/model/ScrapedMovie.kt): `src/main/kotlin/scraping/model/ScrapedMovie.kt`
- [Semantic cinema index](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/CinemaSemanticIndex.kt): `src/main/kotlin/services/CinemaSemanticIndex.kt`

### Movie services

- [Movie routes](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/MovieRouting.kt): `src/main/kotlin/MovieRouting.kt`
- [Gemini AI](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/GeminiService.kt): `src/main/kotlin/services/GeminiService.kt`
- [TMDB catalog](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/TmdbService.kt): `src/main/kotlin/services/TmdbService.kt`
- [OMDb ratings](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/services/OmdbService.kt): `src/main/kotlin/services/OmdbService.kt`

### Social and personalization

- [User action routes](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/UserActionsRouting.kt): `src/main/kotlin/UserActionsRouting.kt`
- [Friend routes](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/FriendsRouting.kt): `src/main/kotlin/FriendsRouting.kt`
- [Comment routes](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/CommentsRouting.kt): `src/main/kotlin/CommentsRouting.kt`
- [Taste profiles](https://github.com/mmileticc/movielensbackendktor/blob/main/src/main/kotlin/db/TasteProfileRepository.kt): `src/main/kotlin/db/TasteProfileRepository.kt`
- [Sharing and notifications](https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin): `src/main/kotlin`

### Persistence

- [Domain repositories](https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/db): `src/main/kotlin/db`
- [Database tables](https://github.com/mmileticc/movielensbackendktor/tree/main/src/main/kotlin/db): `src/main/kotlin/db`
- **PostgreSQL**

### Other components

- **Android app**
- **Cinema websites**
- **Google Gemini API**
- **TMDB API**
- **OMDb API**
- **Firebase services**

## Connections

- Android app → Ktor application: sends requests (evidence: `README.md`)
- Ktor application → Auth and vision routes: registers routes (evidence: `README.md`)
- Ktor application → Movie routes: registers routes (evidence: `README.md`)
- Ktor application → User action routes: registers routes (evidence: `README.md`)
- Ktor application → Friend routes: registers routes (evidence: `README.md`)
- Ktor application → Comment routes: registers routes (evidence: `README.md`)
- Ktor application → Scraping lifecycle: starts lifecycle (evidence: `README.md`)
- Scraping lifecycle → Concurrent scraper engine: runs scrapers (evidence: `README.md`)
- Concurrent scraper engine → Cinema chain scrapers: dispatches concurrently (evidence: `README.md`)
- Cinema chain scrapers → Cinema websites: scrapes listings (evidence: `README.md`)
- Concurrent scraper engine → Cinema listings: produces listings (evidence: `src/main/kotlin/scraping/ScrapingEngineConcurrent.kt`)
- Scraping lifecycle → TMDB catalog: enriches movie IDs (evidence: `README.md`)
- Scraping lifecycle → Domain repositories: persists listings (evidence: `README.md`)
- Scraping lifecycle → Semantic cinema index: refreshes index (evidence: `README.md`)
- Semantic cinema index → Domain repositories: loads listings (evidence: `README.md`)
- Semantic cinema index → Google Gemini API: embeds text (evidence: `src/main/kotlin/services/CinemaSemanticIndex.kt`)
- Auth and vision routes → Gemini AI: recognizes images (evidence: `README.md`)
- Auth and vision routes → TMDB catalog: resolves candidates (evidence: `README.md`)
- Auth and vision routes → Semantic cinema index: searches repertoire (evidence: `README.md`)
- Movie routes → TMDB catalog: fetches movie data (evidence: `src/main/kotlin/MovieRouting.kt`)
- Movie routes → OMDb ratings: fetches ratings (evidence: `src/main/kotlin/MovieRouting.kt`)
- Movie routes → Taste profiles: gets genre affinities (evidence: `src/main/kotlin/MovieRouting.kt`)
- Movie routes → Domain repositories: reads movie data (evidence: `src/main/kotlin/MovieRouting.kt`)
- User action routes → Domain repositories: stores user actions (evidence: `src/main/kotlin/UserActionsRouting.kt`)
- User action routes → TMDB catalog: caches movie details (evidence: `src/main/kotlin/UserActionsRouting.kt`)
- Friend routes → Domain repositories: manages friendships (evidence: `src/main/kotlin/FriendsRouting.kt`)
- Friend routes → Taste profiles: compares tastes (evidence: `src/main/kotlin/FriendsRouting.kt`)
- Friend routes → TMDB catalog: fetches movie data (evidence: `src/main/kotlin/FriendsRouting.kt`)
- Comment routes → Domain repositories: manages comments
- Ktor application → Domain repositories: initializes services (evidence: `src/main/kotlin/Application.kt`)
- Domain repositories → Database tables: queries and updates (evidence: `src/main/kotlin/db/UserActionsRepository.kt`)
- Database tables → PostgreSQL: stores records (evidence: `src/main/kotlin/db/DatabaseFactory.kt`)
- Ktor application → Firebase services: initializes admin SDK (evidence: `src/main/kotlin/Application.kt`)
- Ktor application → TMDB API: warms API client (evidence: `README.md`)
- Gemini AI → Google Gemini API: calls model API (evidence: `src/main/kotlin/services/GeminiService.kt`)
- TMDB catalog → TMDB API: requests catalog data (evidence: `src/main/kotlin/services/TmdbService.kt`)
- OMDb ratings → OMDb API: requests ratings (evidence: `src/main/kotlin/services/OmdbService.kt`)
