# sudipsharma826/aimovierecommendationsystem architecture

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

- Interactive diagram: https://gitdiagram.com/sudipsharma826/aimovierecommendationsystem
- Repository: https://github.com/sudipsharma826/aimovierecommendationsystem

## Overview

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: [`backend/src/services/langchain.service.ts`](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/langchain.service.ts) (LangChain service), [`backend/src/index.ts`](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/index.ts) (Express server), [`backend/src/routes/recommended.routes.ts`](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/routes/recommended.routes.ts) (Recommend routes), [`frontend/src/lib/api.ts`](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/lib/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_page["App page<br/>next page<br/>[page.tsx]"]
  node_recommendation_app["Recommendation UI<br/>react app"]
  node_api_client["API client<br/>fetch client<br/>[api.ts]"]
  node_proxy_auth["Auth proxy<br/>next route<br/>[route.ts]"]
  node_proxy_recommend["Recommend proxy<br/>next route<br/>[route.ts]"]
  node_proxy_health["Health route<br/>next route<br/>[route.ts]"]
  node_frontend_vercel["Vercel config<br/>deployment<br/>[vercel.json]"]
end

subgraph group_backend["Backend"]
  node_server["Express server<br/>api boot<br/>[index.ts]"]
  node_auth_routes["Auth routes<br/>express routes<br/>[auth.routes.ts]"]
  node_auth_service["Auth service<br/>auth logic<br/>[auth.service.ts]"]
  node_auth_middleware["Auth middleware<br/>guard<br/>[auth.middleware.ts]"]
  node_recommend_routes["Recommend routes<br/>express routes"]
  node_recommend_controller["Recommend controller"]
  node_langchain_service["LangChain service<br/>llm pipeline"]
  node_cache_service["Cache check<br/>support service"]
  node_tool_service["Tool service<br/>support service"]
  node_movie_schema["Movie schema<br/>zod schema<br/>[movie.schema.ts]"]
  node_prisma_client["Prisma client<br/>db client<br/>[prisma.ts]"]
  node_prisma_schema["Prisma schema<br/>data model<br/>[schema.prisma]"]
end

subgraph group_external["External"]
  node_database[("Database<br/>relational store")]
  node_openrouter{{"OpenRouter<br/>llm gateway"}}
  node_email_provider{{"Email provider<br/>email service"}}
end

node_browser -->|"loads"| node_page
node_page -->|"mounts"| node_recommendation_app
node_recommendation_app -->|"requests"| node_api_client
node_api_client -->|"POST /recommend"| node_proxy_recommend
node_api_client -->|"auth calls"| node_proxy_auth
node_proxy_auth -->|"forwards"| node_auth_routes
node_proxy_recommend -->|"forwards"| node_recommend_routes
node_proxy_health -->|"checks"| node_server
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_recommend_routes
node_server -->|"uses"| node_auth_middleware
node_auth_routes -->|"delegates"| node_auth_service
node_auth_service -->|"reads/writes"| node_prisma_client
node_auth_service -->|"sends OTP"| node_email_provider
node_auth_middleware -->|"validates session"| node_prisma_client
node_recommend_routes -->|"protects"| node_auth_middleware
node_recommend_routes -->|"delegates"| node_recommend_controller
node_recommend_controller -->|"invokes"| node_langchain_service
node_langchain_service -->|"consults"| node_cache_service
node_langchain_service -->|"orchestrates"| node_tool_service
node_langchain_service -->|"validates output"| node_movie_schema
node_langchain_service -->|"calls model"| node_openrouter
node_recommend_controller -->|"returns shape"| node_movie_schema
node_prisma_client -->|"connects"| node_database
node_prisma_schema -->|"models"| node_database
node_frontend_vercel -.->|"deploys"| node_browser

click node_page "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/page.tsx"
click node_recommendation_app "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/components/recommendation-app.tsx"
click node_api_client "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/lib/api.ts"
click node_proxy_auth "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/auth/[...path]/route.ts"
click node_proxy_recommend "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/recommend/route.ts"
click node_proxy_health "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/health/route.ts"
click node_frontend_vercel "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/vercel.json"
click node_server "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/index.ts"
click node_auth_routes "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/routes/auth.routes.ts"
click node_auth_service "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/auth.service.ts"
click node_auth_middleware "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/middleware/auth.middleware.ts"
click node_recommend_routes "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/routes/recommended.routes.ts"
click node_recommend_controller "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/controllers/recommended.controller.ts"
click node_langchain_service "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/langchain.service.ts"
click node_cache_service "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/cache-check.service.ts"
click node_tool_service "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/recommendation-tool.service.ts"
click node_movie_schema "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/schemas/movie.schema.ts"
click node_prisma_client "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/lib/prisma.ts"
click node_prisma_schema "https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/prisma/schema.prisma"

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_browser,node_page,node_recommendation_app,node_api_client,node_proxy_auth,node_proxy_recommend,node_proxy_health,node_frontend_vercel toneBlue
class node_server,node_auth_routes,node_auth_service,node_auth_middleware,node_recommend_routes,node_recommend_controller,node_langchain_service,node_cache_service,node_tool_service,node_movie_schema,node_prisma_client,node_prisma_schema toneAmber
class node_database,node_openrouter,node_email_provider toneMint
```

## Components

### Frontend

Next.js orchestration layer and browser-facing proxy boundary.

- **Browser**: client · User interacts with the app through the deployed frontend.
- [App page](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/page.tsx): next page · Renders the main experience and mounts the recommendation flow. · `frontend/src/app/page.tsx`
- [Recommendation UI](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/components/recommendation-app.tsx): react app · Owns form state, loading states, and recommendation rendering. · `frontend/src/components/recommendation-app.tsx`
- [API client](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/lib/api.ts): fetch client · Browser-side request helper configured to include credentials. · `frontend/src/lib/api.ts`
- [Auth proxy](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/auth/[...path]/route.ts): next route · Forwarding layer for auth requests and cookie relaying. · `frontend/src/app/api/auth/[...path]/route.ts`
- [Recommend proxy](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/recommend/route.ts): next route · Forwarding layer for recommendation requests. · `frontend/src/app/api/recommend/route.ts`
- [Health route](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/src/app/api/health/route.ts): next route · Frontend health endpoint for deployment/runtime checks. · `frontend/src/app/api/health/route.ts`
- [Vercel config](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/frontend/vercel.json): deployment · Separate frontend deployment boundary. · `frontend/vercel.json`

### Backend

Express API, auth, and recommendation pipeline.

- [Express server](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/index.ts): api boot · Bootstraps middleware and mounts the API routes. · `backend/src/index.ts`
- [Auth routes](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/routes/auth.routes.ts): express routes · HTTP surface for OTP verification and session issuance. · `backend/src/routes/auth.routes.ts`
- [Auth service](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/auth.service.ts): auth logic · Implements OTP, JWT cookie, and verification workflow. · `backend/src/services/auth.service.ts`
- [Auth middleware](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/middleware/auth.middleware.ts): guard · Protects recommendation endpoints with session checks. · `backend/src/middleware/auth.middleware.ts`
- [Recommend routes](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/routes/recommended.routes.ts): express routes · HTTP surface for recommendation generation. · `backend/src/routes/recommended.routes.ts`
- [Recommend controller](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/controllers/recommended.controller.ts): controller · Shapes request and response for the recommendation API. · `backend/src/controllers/recommended.controller.ts`
- [LangChain service](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/langchain.service.ts): llm pipeline · Builds the model chain and produces structured movie recommendations. · `backend/src/services/langchain.service.ts`
- [Cache check](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/cache-check.service.ts): support service · Checks for cached or reusable recommendation results. · `backend/src/services/cache-check.service.ts`
- [Tool service](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/services/recommendation-tool.service.ts): support service · Auxiliary orchestration around recommendation generation. · `backend/src/services/recommendation-tool.service.ts`
- [Movie schema](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/schemas/movie.schema.ts): zod schema · Defines the structured recommendation output contract. · `backend/src/schemas/movie.schema.ts`
- [Prisma client](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/src/lib/prisma.ts): db client · Shared database access layer used by backend services. · `backend/src/lib/prisma.ts`
- [Prisma schema](https://github.com/sudipsharma826/aimovierecommendationsystem/blob/master/backend/prisma/schema.prisma): data model · Relational model for users, auth state, and token lifecycle. · `backend/prisma/schema.prisma`

### External

Runtime dependencies outside the repository.

- **Database**: relational store · Persists users, verification state, and session metadata.
- **OpenRouter**: llm gateway · External model access used by the recommendation pipeline.
- **Email provider**: email service · Sends OTP verification emails.

## Connections

- 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.
