Stream Sync

Movie discovery + social features stack composed of:

• Frontend: React + Vite (frontend) on http://localhost:5173
• API Gateway: Spring Cloud Gateway (services/api-gateway) on http://localhost:8080
• Services (Spring Boot, Java 21): auth-service, user-service, interaction-service, movie-service, recommendation-service
• Datastores: Postgres for movie-service and recommendation-service, H2 file DBs for auth-service and user-service
• SSM Engine: Python service (ssm-engine) that downloads a Kaggle dataset and (re)builds a FAISS index

Repository structure

High-level guide to what lives where and how it runs.

• docker-compose.yml: One-command local stack (DBs, services, ssm-engine, frontend). The API entrypoint is the gateway on port 8080.
• .env.example: Template for required runtime environment variables (copied to .env for local runs).
• services/: Spring Boot microservices (Gradle, Java 21). Built into containers by Compose.
  • services/api-gateway/: Spring Cloud Gateway. Routes /api/* paths to the internal service containers (see services/api-gateway/src/main/resources/application.yml).
  • services/auth-service/: Authentication + JWT issuing/verification. Uses an H2 file database persisted to ./data/auth-service/.
  • services/user-service/: User profile/service APIs. Uses an H2 file database persisted to ./data/user-service/. Calls recommendation-service for some downstream operations.
  • services/interaction-service/: Captures user interactions (watched/ratings/etc.). Uses H2 (configured in its application.properties).
  • services/movie-service/: Movie catalog APIs backed by Postgres (movie-db). Also talks to ssm-engine to ingest the Kaggle dataset stream and refresh the catalog.
  • services/recommendation-service/: Recommendation APIs backed by Postgres (recommendation-db). Also talks to ssm-engine for embeddings/search.
• ssm-engine/: Python service providing semantic search / embeddings + FAISS index lifecycle.
  • Downloads the Kaggle dataset on startup (and periodically), then rebuilds the FAISS index (see ssm-engine/README.md).
• frontend/: React + Vite UI. In Compose it runs on port 5173 and is mounted for live-editing (./frontend/src → /app/src).
• data/: Local persistent state mounted into containers (H2 database files and service data directories). Safe to delete if you want a clean reset (or use docker compose down -v to reset volumes too).
• doc/: Architecture documentation used to explain the system and justify key decisions.
  • doc/subsystem_overview.md: Overview of the runtime subsystems and how requests flow through the gateway to services and ssm-engine.
  • doc/requirements.md: Functional + NFRs, each mapped to evidence in the codebase.
  • doc/stakeholder_identification.md: Stakeholders, concerns, and viewpoint-based architectural diagrams (functional / component-connector / information / security).
  • doc/architectural_tactics.md: The architectural tactics intended to satisfy key NFRs (with rationale and diagrams).
  • doc/implementation_patterns.md: The key GoF patterns that are structurally significant in this repo (notably Strategy + Observer), with UML/runtime diagrams and concrete class mappings.
  • doc/architecture_analysis.md: Trade-off analysis comparing the implemented microservices approach vs a modular-monolith alternative (with quantified NFR discussion).
  • doc/arch/: ADRs (Architecture Decision Records).
    • doc/arch/adr-001.md: Split movie catalog into movie-service + ML/vector search into ssm-engine; define the semantic-search enrichment + fallback approach.
    • doc/arch/adr-002.md: Database-per-microservice (Postgres for movie/recommendation, H2 files for auth/user, FAISS artifacts for ssm-engine).
    • doc/arch/adr-003.md: Spring Cloud Gateway as the single edge router and stable /api/* contract.
    • doc/arch/adr-004.md: NDJSON streaming ingestion from ssm-engine plus coordinated (clean) index/embeddings rebuild lifecycle.
    • doc/arch/adr-005.md: Rejected decision: adding a message broker; documents why HTTP polling + async HTTP were chosen for now.

Quickstart (Docker Compose)

Prerequisites

• Docker Desktop (with Compose v2)
• Git

Optional (recommended for best ssm-engine performance):

• NVIDIA GPU + drivers and Docker GPU support (Docker Desktop + WSL2 + NVIDIA Container Toolkit)

1) Create .env

This repo uses docker-compose.yml with env_file: .env for multiple services.

Copy the example file and update values as needed:

Copy-Item .\.env.example .\.env

Minimum recommended values in .env:

• DB_USERNAME
• DB_PASSWORD
• JWT_SECRET

Kaggle auth (for ssm-engine) can be provided via:

• KAGGLE_API_TOKEN (either JSON token content or username:key)
• or Kaggle credentials file (%USERPROFILE%\.kaggle\kaggle.json) if you prefer not to pass a token via env

2) Start everything

From the repo root:

docker compose up --build

First startup can take a while because ssm-engine may download the dataset and build embeddings / FAISS index.

To stop:

docker compose down

To reset all container data (Postgres volumes + ssm-engine volume):

docker compose down -v

Service URLs and Ports

Public entrypoints

• Frontend: http://localhost:5173
• API Gateway: http://localhost:8080

API Gateway routes

The gateway routes requests to internal services:

• /api/auth/** → auth-service
• /api/user/** → user-service
• /api/movies/** → movie-service
• /api/interaction/** → interaction-service
• /api/recommendation/** → recommendation-service
• /api/ssm/** → ssm-engine (rewritten to the engine root path)

Databases

• Movie DB (Postgres): host port 5432 → container movie-db:5432
• Recommendation DB (Postgres): host port 5433 → container recommendation-db:5432

H2 file DBs for auth-service and user-service are persisted under ./data/... via Compose volumes.

Notes for ssm-engine (Kaggle + FAISS)

ssm-engine is configured in docker-compose.yml with:

• KAGGLE_DATASET (default: alanvourch/tmdb-movies-daily-updates)
• KAGGLE_API_TOKEN (optional)
• EMBED_BATCH_SIZE (default: 256)

If Kaggle auth is missing/invalid, the engine will fail to download the dataset and dependent services may not become healthy.

No GPU?

The Compose file reserves an NVIDIA GPU for ssm-engine via the deploy.resources.reservations.devices section.

If you don’t have GPU support enabled in Docker Desktop:

• Remove or comment out the ssm-engine: deploy: block in docker-compose.yml, then rerun docker compose up --build.
• Consider lowering EMBED_BATCH_SIZE in .env (e.g. 64 or 128) to reduce memory pressure.

Development (without Docker)

This repo is Docker-first. If you want to run parts locally:

• Backend services are Gradle/Spring Boot projects (Java 21) under services/*
• Frontend is a Vite project under frontend

Typical commands (run from each directory):

# Backend service (example)
.\gradlew.bat bootRun

# Frontend
npm install
npm run dev

If you go the non-Docker route, you’ll need to provide equivalent environment variables and ensure dependencies (Postgres + ssm-engine) are reachable.

Troubleshooting

• Gateway returns 502/504: a downstream service container is not healthy yet; check logs:

docker compose logs -f api-gateway
docker compose logs -f ssm-engine

• Postgres container not starting: a previous volume may be incompatible; reset volumes:

docker compose down -v
docker compose up --build

• ssm-engine Kaggle failures: ensure KAGGLE_API_TOKEN is set correctly (or that your Kaggle credentials file exists) and that your Kaggle account has accepted the dataset terms, if required.