How sudipsharma826/aimovierecommendationsystem works
1. This is a two-package monorepo with a hard frontend/backend boundary. The frontend/ folder is a Next.js app, the backend/ folder is an Express + TypeScript API, and the root vercel.json plus frontend/vercel.json indicate the frontend is meant to be deployed separately from the backend.
2. The frontend is the user-facing orchestration layer. src/app/page.tsx renders the main recommendation experience through RecommendationApp, while src/app/api/* contains proxy routes that forward requests to the backend. The app is split into a main recommendation UI, a health endpoint, and an auth proxy path.
3. The frontend data path is intentionally cookie-aware. Client code in src/lib/api.ts sends requests with credentials: "include", and the Next.js API routes forward the auth_token cookie to the backend and relay Set-Cookie back to the browser. That proxy layer is the key boundary that makes cross-origin auth work between Vercel and the API host.
4. The backend is a classic route-controller-service stack. src/index.ts boots the Express server, mounts middleware, and wires /api/auth and /api/recommend. Route files define HTTP surfaces, controllers handle request/response shaping, and services contain the business logic.
5. Authentication is a separate subsystem centered on email OTP and JWT cookies. auth.routes.ts, auth.middleware.ts, and auth.service.ts implement the verification flow, session issuance, and protection of recommendation endpoints. Prisma-backed user records store verification state and token/OTP lifecycle fields, and the auth middleware is the gatekeeper for the recommendation API.
6. The core product logic is the recommendation pipeline. recommended.controller.ts receives the user’s prompt, genre, mood, and count, then delegates to langchain.service.ts. That service builds a LangChain chain using prompt templates, an OpenRouter-backed chat model, and structured output generation.
7. The LLM contract is schema-driven. src/schemas/movie.schema.ts defines the output shape with Zod, and that schema is used both for validation and for typed inference back into the app. The result is a JSON recommendation payload shaped as { movies: [...] }, not freeform text.
8. There are supporting backend services around the main recommendation flow. cache-check.service.ts suggests cached-result lookup or reuse, recommendation-tool.service.ts suggests tool-like orchestration around recommendation generation, and langchain.service.ts is the central place where those capabilities converge. Even if some of these are auxiliary, they sit behind the same API boundary and are part of the backend’s internal business layer.
9. Persistence is handled through Prisma. prisma/schema.prisma and the migration folder show the system has a relational data model rather than a stateless demo-only backend. This is important for architecture diagrams because auth state, OTPs, and token metadata are persisted independently of the request cycle.
10. External dependencies matter to the architecture because they define the runtime edges. OpenRouter is the LLM gateway used by the backend to reach model providers, and the README also describes email delivery for OTP verification. So the main external calls are: browser → Next.js proxy → Express API → OpenRouter, plus backend → email provider for verification.
11. The frontend component structure is presentation-heavy but still bounded. RecommendationApp owns form state, loading/error/empty states, and rendering of recommendation cards; MovieCard and skeleton components are reusable UI primitives; src/components/ui/* are shared design-system controls. This keeps UI state local while the backend owns the AI and auth workflows.
12. Operationally, the repo is designed for cross-origin deployment. CORS, environment variables, secure/httpOnly cookies, and the Next.js proxy routes are all part of the architecture, not implementation details. For a diagram, the key deployment split is: browser talks to Next.js, Next.js proxies to Express, Express talks to DB and external APIs.
Main entry points: langchain.service.ts LangChain service · index.ts Express server · recommended.routes.ts Recommend routes · api.ts API client
Components 23
Frontend
Next.js orchestration layer and browser-facing proxy boundary.
- Browser · User interacts with the app through the deployed frontend.
- App page · Renders the main experience and mounts the recommendation flow.
frontend/src/app/page.tsx - Recommendation UI · Owns form state, loading states, and recommendation rendering.
frontend/src/components/recommendation-app.tsx - API client · Browser-side request helper configured to include credentials.
frontend/src/lib/api.ts - Auth proxy · Forwarding layer for auth requests and cookie relaying.
frontend/src/app/api/auth/[...path]/route.ts - Recommend proxy · Forwarding layer for recommendation requests.
frontend/src/app/api/recommend/route.ts - Health route · Frontend health endpoint for deployment/runtime checks.
frontend/src/app/api/health/route.ts - Vercel config · Separate frontend deployment boundary.
frontend/vercel.json
Backend
Express API, auth, and recommendation pipeline.
- Express server · Bootstraps middleware and mounts the API routes.
backend/src/index.ts - Auth routes · HTTP surface for OTP verification and session issuance.
backend/src/routes/auth.routes.ts - Auth service · Implements OTP, JWT cookie, and verification workflow.
backend/src/services/auth.service.ts - Auth middleware · Protects recommendation endpoints with session checks.
backend/src/middleware/auth.middleware.ts - Recommend routes · HTTP surface for recommendation generation.
backend/src/routes/recommended.routes.ts - Recommend controller · Shapes request and response for the recommendation API.
backend/src/controllers/recommended.controller.ts - LangChain service · Builds the model chain and produces structured movie recommendations.
backend/src/services/langchain.service.ts - Cache check · Checks for cached or reusable recommendation results.
backend/src/services/cache-check.service.ts - Tool service · Auxiliary orchestration around recommendation generation.
backend/src/services/recommendation-tool.service.ts - Movie schema · Defines the structured recommendation output contract.
backend/src/schemas/movie.schema.ts - Prisma client · Shared database access layer used by backend services.
backend/src/lib/prisma.ts - Prisma schema · Relational model for users, auth state, and token lifecycle.
backend/prisma/schema.prisma
External
Runtime dependencies outside the repository.
- Database · Persists users, verification state, and session metadata.
- OpenRouter · External model access used by the recommendation pipeline.
- Email provider · Sends OTP verification emails.
Connections 26
- Browser → App page: loads · The browser opens the Next.js application.
- App page → Recommendation UI: mounts · The app page renders the recommendation experience.
- Recommendation UI → API client: requests · UI actions call the shared API helper.
- API client → Recommend proxy: POST /recommend · Client requests are sent through the frontend proxy.
- API client → Auth proxy: auth calls · Authentication traffic is routed through the frontend proxy.
- Auth proxy → Auth routes: forwards · Auth proxy forwards requests to the backend API.
- Recommend proxy → Recommend routes: forwards · Recommendation proxy forwards requests to the backend API.
- Health route → Express server: checks · Health endpoint reflects backend reachability.
- Express server → Auth routes: mounts · Express mounts the auth route set.
- Express server → Recommend routes: mounts · Express mounts the recommendation route set.
- Express server → Auth middleware: uses · Middleware is wired into the API request chain.
- Auth routes → Auth service: delegates · Route handlers delegate to auth business logic.
- Auth service → Prisma client: reads/writes · Auth state is persisted through Prisma.
- Auth service → Email provider: sends OTP · Verification codes are delivered via email.
- Auth middleware → Prisma client: validates session · Middleware checks persisted auth/session state.
- Recommend routes → Auth middleware: protects · Recommendation endpoints require auth checks.
- Recommend routes → Recommend controller: delegates · Route handlers forward to the controller layer.
- Recommend controller → LangChain service: invokes · Controller passes prompt and preference inputs downstream.
- LangChain service → Cache check: consults · Recommendation generation can reuse cached results.
- LangChain service → Tool service: orchestrates · Auxiliary recommendation tooling is composed here.
- LangChain service → Movie schema: validates output · Structured movie payloads are enforced with Zod.
- LangChain service → OpenRouter: calls model · The backend reaches external LLM providers through OpenRouter.
- Recommend controller → Movie schema: returns shape · The API responds with the schema-driven movie payload.
- Prisma client → Database: connects · Prisma mediates access to the relational database.
- Prisma schema → Database: models · The schema defines the persisted data model.
- Vercel config → Browser: deploys · Frontend is deployed separately as the browser-facing app.