CineMatch

About

CineMatch is a hybrid movie recommendation system where each component handles the part of the problem it is best suited for. A Go backend serves a REST API with JWT auth, an LLM converts natural-language questions into safe SQL, Apache AGE runs graph traversals for related-title discovery, and a React/TypeScript frontend renders the experience. PostgreSQL 16 with PostGIS manages all structured storage, and an enrichment trigger pipeline auto-queues new movies for LLM-generated mood/theme tagging.

The system collects structured preference data at signup so recommendations are personalized from the first session, addressing the cold-start problem. Mood is treated as a real feature in the user profile, updated through feedback.

Stack

Codebase Snapshot

Numbers below are pulled from the tokei CLI tool.

Real API Surface

Routes below are pulled from internal/infra/http/server/server.go. The current API surface has 20 HTTP endpoints total (19 under /api + 1 health route).

Public

• GET /health
• POST /api/auth/register
• POST /api/auth/signup (register + onboarding in one transaction)
• POST /api/auth/login
• POST /api/auth/refresh
• POST /api/auth/logout
• GET /api/movies (supports q, genre, limit, offset)
• GET /api/movies/search
• GET /api/movies/top-rated/all-time
• GET /api/movies/trending/week
• GET /api/movies/{id}
• GET /api/movies/{id}/crew
• GET /api/movies/{id}/related
• GET /api/movies/{id}/graph-related
• POST /api/chat

Protected (JWT required)

• POST /api/users/onboard
• GET /api/feedback/{movieID}
• POST /api/feedback
• POST /api/feedback/not-interested
• GET /api/recommendations/graph

Project Status Matrix

This matrix separates what is live in backend routes, what currently runs with mock data in UI, and what is wired in frontend but not exposed in the backend yet.

Runtime Operations

API startup and shutdown behavior is explicit in cmd/cenimatch and internal/container.

Connection Bootstrap

Each new DB connection is prepared for both relational SQL and AGE graph calls before request handling starts.

Configuration Modes

Config loading has separate behavior for dev and production to speed local work while enforcing stricter prod settings.

CLI Tooling

The project ships with executable workflows for app runtime, downloads, and migration operations.

Migration Safety Notes

Migration behavior is catalog-driven and explicit about destructive operations.

Downloader Reliability

The download pipeline is generic and source-agnostic, with built-in protection for common ingestion failures.

Security Internals

Access and refresh tokens are handled as separate concerns with rotation and server-side revocation checks.

API Envelope Contract

API responses follow a consistent envelope structure so frontend parsing stays uniform across endpoints.

{
  "success": true,
  "data": { "...": "..." }
}

{
  "success": false,
  "error": { "code": "INVALID_REQUEST" }
}

Frontend / Backend Parity

This table tracks calls referenced in frontend API clients against routes currently registered in backend server setup.

Page Reliability Notes

• Mermaid bootstrap script: main.js is now included to initialize diagrams client-side.
• Graceful fallback: if Mermaid CDN cannot load, raw diagram source remains visible instead of blank output.
• Large diagrams: focused wrappers keep complex architecture charts scrollable on smaller screens.

System Architecture

Backend Layer Diagram

The Go backend follows a strict layered architecture: handlers only decode/encode HTTP, services own all business logic, and repositories own SQL. Security interfaces (bcrypt, JWT, refresh tokens) are injected via ports.

Technical Excellence

• Layer boundaries are enforced: handlers parse HTTP, services run business logic, and repositories own SQL.
• Dependency injection through ports: security and database dependencies are wired as interfaces, which keeps services isolated from concrete implementations.
• Transaction safety: WithTx is used for multi-step writes (like signup + onboarding) so partial writes are rolled back on failure.

Atomic Write Flows

Multi-step writes are wrapped in a shared transaction helper so profile, feedback, and graph state stay consistent.

Database Schema

14 tables across four domains: movie catalog, user identity, interaction tracking, and infrastructure. Movies are keyed on tmdb_id, users on UUID. Three PostgreSQL enums enforce type safety: tag_source, crew_role, mood_type. PostGIS GEOGRAPHY columns on feedback and locations enable spatial queries.

Technical Excellence

• Relational core: 14 tables with clear domain split and enum constraints for tag source, crew role, and mood type.
• Practical Postgres types: JSONB stores preference weights, arrays track mood IDs, and PostGIS GEOGRAPHY supports location-aware features.
• Trigger-based enrichment queue: new movies are automatically queued for enrichment through trg_movie_enrich.

Movie Catalog Domain

User & Interaction Domain

LLM Text-to-SQL Pipeline

Users type natural-language questions. The backend wraps them with a schema prompt, sends to OpenRouter (Llama 3.3 70B with multi-model fallback), validates the returned SQL through a strict guard, then executes it read-only against PostgreSQL.

Technical Excellence

• Schema grounding: the system prompt includes table/column context so generated SQL is tied to the real schema.
• Fallback strategy: the primary free model is retried 5 times, then the request rotates to 4 fallback models if needed.
• SQL safety checks: only SELECT is allowed, write operations are blocked, and a LIMIT clause is required.

Runtime Safety Contract

System Prompt Design

The prompt in internal/llm/schema_prompt.go is a full SQL contract, not a short instruction. It includes a table-by-table schema reference, graph-to-SQL mapping rules, and strict output constraints so the model returns one executable PostgreSQL SELECT.

• Schema coverage: prompt includes movies, genres, movie_genres, persons, movie_crew, movie_tags, users, user_preferences, user_mood_profile, watch_history, user_feedback, recommendations, and activity_events.
• Graph translation rules: graph concepts (WATCHED, RATED, IN_GENRE, ACTED_IN, DIRECTED) are mapped to relational joins.
• Output contract: return one raw SQL statement only, no markdown fences, no explanation text.
• Safety contract: non-SELECT statements are forbidden; queries must include LIMIT with max 50; unsafe requests must return UNSAFE: <reason>.
• Frontend alignment: when returning movie rows, the prompt asks for card fields like tmdb_id, title, release_year, vote_avg, and poster_path.

Authentication Flow

JWT access tokens (HS256, configurable expiry) plus refresh-token rotation. The refresh token format is uuid:hex_secret — only sha256(secret) is stored. Old tokens are revoked on rotation, preventing replay.

Apache AGE Graph Model

The movie_graph is built from relational tables and queried via Cypher through ag_catalog.cypher(). It supports genre-based recommendations, collaborative filtering, actor/director traversals, and explainability paths.

Technical Excellence

• Single-database hybrid model: relational queries and AGE Cypher traversals run in the same PostgreSQL deployment.
• Explainability-ready traversals: graph queries can return relationship paths, not just final movie IDs.
• Collaborative filtering path: overlapping user ratings are used to surface unseen titles from similar users.

Recommendation Query Recipes

Data Ingestion Pipeline

CineMatch uses a concurrent Go pipeline to ingest, clean, and normalize movie data from 7 sources including IMDb, TMDB, and Kaggle.

Technical Excellence

• Concurrent downloads: the downloader uses goroutines with semaphore limits to keep throughput high without exhausting memory.
• Data filtering at ingest time: regex and adult-flag filters remove explicit/malformed records before load (about 43K rows filtered in project ingestion).
• Load + optimize flow: bulk COPY into staging tables, then CTE-based normalization and index migrations for faster queries.

Deployment Architecture

Two Docker Compose files: docker-compose.yml runs the database (custom PG16 image with AGE + PostGIS), docker-compose.deploy.yml runs the Go backend, React frontend (Nginx), and a Cloudflared tunnel for zero-trust HTTPS access.

Features

• Interactive 5-step onboarding for cold-start personalization (account → genres → film anchors → preferences → mood)
• LLM-triggered database enrichment on movie insertion via PostgreSQL trigger
• Conversational movie search via text-to-SQL with multi-model LLM fallback and SQL safety guard
• Graph-based related movie discovery and personalized recommendations (Apache AGE Cypher)
• Mood-based quick pick with six mood categories
• JWT access + refresh token rotation with bcrypt hashing
• Query performance optimization: 68s → <1s via CTE narrowing + index migration
• Data quality pipeline: 43K explicit rows filtered at ingestion
• City-level live activity map rendered with ECharts
• Analytics dashboards backed by PostgreSQL views

Potential Next Additions

• Add GET /api/me so frontend can fetch current user profile without decoding token client-side.
• Add cursor-based pagination for movie feeds (after_id/after_score) to avoid large offset scans.
• Add basic per-IP rate limiting on /api/chat and auth routes to protect free-tier model and login endpoints.
• Add an API docs page (OpenAPI JSON + simple Swagger UI) so teammates can test endpoints quickly.
• Add request-id response header in error payloads to make debugging logs much easier during demos.
• Add a nightly job to revoke expired refresh tokens (the repository method already exists).
• Add a small endpoint for graph explainability paths so recommendations can show exactly which edge/path triggered the match.

Completed

• Full auth system — register, login, refresh-token rotation, logout (4 endpoints, bcrypt + JWT HS256)
• 5-step onboarding with DB movie picker, genre weights, runtime/decade prefs, mood profile — all persisted in one transaction
• Service layer extraction — clean handler → service → repository separation
• Wired frontend to real backend data — paginated movie list, text search, detail, and related endpoints
• Query performance: 68s → <1s via CTE narrowing + GIN trigram and join index migration
• Data quality pipeline — regex + adult-flag filter removed 43K explicit rows at ingestion time
• Actor/crew ingest from title.principals.tsv — directors, actors, producers in movie_crew
• LLM text-to-SQL pipeline — OpenRouter client with retry × 5 + 4 fallback models
• SQL guard — SELECT-only whitelist, DML blocking, forced LIMIT 50
• Chat page — full message history, dynamic movie grids / data tables, SQL transparency toggle
• Graph recommendations via Apache AGE Cypher traversals with genre/rating-based fallback
• Movie detail page — 3-column cast layout with DiceBear avatars, scrollable crew sections
• Docker deployment — Go backend + React/Nginx frontend + Cloudflared tunnel for zero-trust HTTPS

Project Structure

Team

Abdulrahman Alamoudi

Gary Young

Jack Lyons Team Leader

Yazeed Alharthi

Yordanos Tessema

Responsibilities