# arpan-dey-web/cinetube-backend architecture

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

- Interactive diagram: https://gitdiagram.com/arpan-dey-web/cinetube-backend
- Repository: https://github.com/arpan-dey-web/cinetube-backend

## Overview

1. **What this repo is**
   - CineTube Backend is a TypeScript/Express API for a movie/series portal. The architecture is feature-first: each domain area owns its own router, controller, service, and validation files.

2. **Process boundary and deployment shape**
   - The runtime entry is `src/server.ts`, which boots the Express app defined in `src/app.ts`.
   - The repo is built to `dist/` with `tsup` and deployed on Vercel, so the same app is packaged for production/serverless execution.

3. **HTTP application composition**
   - `src/app.ts` is the central composition layer: it wires middleware, mounts feature routes, and exposes the root health/status endpoint.
   - `src/app/modules/root.route.ts` likely provides the simple base response used to verify the service is running.

4. **Request pipeline and cross-cutting middleware**
   - Requests pass through shared middleware for auth, request validation, and centralized error handling.
   - `qs` query parsing, cookie parsing, and credentialed CORS are important because the API relies on cookie-based sessions and richer query filtering.

5. **Authentication and authorization boundary**
   - Authentication is handled by Better Auth through `src/lib/auth.ts` and related middleware.
   - The repo uses session/cookie auth rather than JWTs, and access is role-aware: user vs admin.
   - Utility code in `src/utils/access.ts` and auth middleware gate protected routes and admin-only operations.

6. **Persistence layer**
   - Prisma is the data access layer, centered on `src/lib/prisma.ts` and the Prisma schema/migrations under `prisma/`.
   - PostgreSQL is the backing store.
   - `src/generated/` contains checked-in Prisma client artifacts, so generated model types are part of the source tree and build output.

7. **Movie/catalog subsystem**
   - `src/app/modules/movie/` handles movie/series CRUD, filtering, and metadata like genre, cast, release year, price type, and streaming link.
   - This is primarily admin-managed content and forms the upstream entity for reviews, purchases, and watchlists.

8. **Review and engagement subsystem**
   - `src/app/modules/review/` manages review creation, editing, deletion, moderation, likes, spoiler flags, and tags.
   - Reviews connect users to movies and are subject to moderation, which means there is a workflow boundary between user-generated content and admin approval.

9. **Commerce subsystem**
   - `src/app/modules/payment/` handles Stripe payment-intent creation and webhook verification.
   - `src/app/modules/purchase/` records purchases and checks whether a user has access to premium content.
   - The webhook is a critical trust boundary: payment confirmation is finalized server-side, not by the client.

10. **User personalization subsystem**
    - `src/app/modules/watchlist/` lets users save and toggle movies in their watchlist.
    - `src/app/modules/user/` handles user-facing account data and likely purchase-history-related access patterns.
    - These routes depend on the authenticated user context and the shared Prisma models.

11. **Admin subsystem**
    - `src/app/modules/admin/` exposes dashboard stats and moderation-oriented operations.
    - It aggregates data across movies, reviews, purchases, and users, so it is a read-heavy cross-domain boundary rather than a separate data silo.

12. **Error handling and response conventions**
    - Async route handlers are wrapped with `catchAsync`, and responses are standardized via `sendResponse`.
    - Errors flow to a global error handler, giving the API a single consistent failure path instead of per-route ad hoc handling.

13. **Build and artifact boundaries**
    - Source lives under `src/`; compiled JavaScript and type artifacts live in `dist/`.
    - The presence of generated Prisma client files, migration SQL, and build output indicates a clear separation between authored code, generated ORM code, and deployment artifacts.

14. **Diagramming takeaway**
    - An accurate architecture diagram should show: client/front end → Express app → middleware/auth/validation → feature routers → controllers → services → Prisma/PostgreSQL.
    - Stripe adds an external callback path into the payment subsystem via webhook, and Better Auth adds a session/authentication path that cuts across most protected routes.

Main entry points: [`src/app.ts`](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app.ts) (App), [`src/lib/prisma.ts`](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/lib/prisma.ts) (Prisma), [`src/app/middleware/auth.ts`](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/auth.ts) (Auth mw), [`src/server.ts`](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/server.ts) (Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_runtime["Runtime API"]
  node_server(("Server<br/>entrypoint<br/>[server.ts]"))
  node_app["App<br/>[app.ts]"]
  node_root_route["Root route<br/>health endpoint<br/>[root.route.ts]"]
  node_auth_mw{{"Auth mw<br/>middleware<br/>[auth.ts]"}}
  node_validate_mw{{"Validate mw<br/>middleware<br/>[validateRequest.ts]"}}
  node_error_mw{{"Error mw<br/>middleware"}}
  node_auth_lib["Auth lib<br/>session auth<br/>[auth.ts]"]
  node_access_utils["Access utils<br/>rbac helpers<br/>[access.ts]"]
  node_movie_mod["Movies<br/>catalog feature<br/>[movie.route.ts]"]
  node_review_mod["Reviews<br/>ugc feature<br/>[review.route.ts]"]
  node_payment_mod["Payments<br/>stripe feature<br/>[payment.route.ts]"]
  node_purchase_mod["Purchases<br/>commerce feature<br/>[purchase.route.ts]"]
  node_watchlist_mod["Watchlist<br/>personalization<br/>[watchlist.route.ts]"]
  node_user_mod["Users<br/>account feature<br/>[user.route.ts]"]
  node_admin_mod["Admin<br/>ops feature<br/>[admin.routes.ts]"]
end

subgraph group_grp_data["Data Layer"]
  node_prisma_lib[("Prisma<br/>orm client<br/>[prisma.ts]")]
  node_prisma_schema["Schema<br/>[schema.prisma]"]
  node_generated_client["Generated client<br/>generated orm<br/>[client.ts]"]
end

subgraph group_grp_build["Build Artifacts"]
  node_dist_bundle["Dist<br/>build output<br/>[server.js]"]
end

node_server -->|"boots"| node_app
node_app -->|"mounts"| node_root_route
node_app -->|"uses"| node_auth_mw
node_app -->|"uses"| node_validate_mw
node_app -->|"uses"| node_error_mw
node_app -->|"routes"| node_movie_mod
node_app -->|"routes"| node_review_mod
node_app -->|"routes"| node_payment_mod
node_app -->|"routes"| node_purchase_mod
node_app -->|"routes"| node_watchlist_mod
node_app -->|"routes"| node_user_mod
node_app -->|"routes"| node_admin_mod
node_auth_mw -->|"verifies"| node_auth_lib
node_auth_mw -->|"checks"| node_access_utils
node_movie_mod -->|"reads/writes"| node_prisma_lib
node_review_mod -->|"reads/writes"| node_prisma_lib
node_payment_mod -->|"records"| node_prisma_lib
node_purchase_mod -->|"checks"| node_prisma_lib
node_watchlist_mod -->|"stores"| node_prisma_lib
node_user_mod -->|"reads/writes"| node_prisma_lib
node_admin_mod -->|"aggregates"| node_prisma_lib
node_prisma_lib -->|"built from"| node_prisma_schema
node_prisma_lib -->|"exports"| node_generated_client
node_dist_bundle -.->|"compiled from"| node_server

click node_server "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/server.ts"
click node_app "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app.ts"
click node_root_route "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/root.route.ts"
click node_auth_mw "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/auth.ts"
click node_validate_mw "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/validateRequest.ts"
click node_error_mw "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/globalErrorHandler.ts"
click node_auth_lib "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/lib/auth.ts"
click node_access_utils "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/utils/access.ts"
click node_movie_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/movie/movie.route.ts"
click node_review_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/review/review.route.ts"
click node_payment_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/payment/payment.route.ts"
click node_purchase_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/purchase/purchase.route.ts"
click node_watchlist_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/watchlist/watchlist.route.ts"
click node_user_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/user/user.route.ts"
click node_admin_mod "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/admin/admin.routes.ts"
click node_prisma_lib "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/lib/prisma.ts"
click node_prisma_schema "https://github.com/arpan-dey-web/cinetube-backend/blob/main/prisma/schema.prisma"
click node_generated_client "https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/generated/client.ts"
click node_dist_bundle "https://github.com/arpan-dey-web/cinetube-backend/blob/main/dist/server.js"

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_server,node_app,node_root_route,node_auth_mw,node_validate_mw,node_error_mw,node_auth_lib,node_access_utils,node_movie_mod,node_review_mod,node_payment_mod,node_purchase_mod,node_watchlist_mod,node_user_mod,node_admin_mod toneBlue
class node_prisma_lib,node_prisma_schema,node_generated_client toneAmber
class node_dist_bundle toneMint
```

## Components

### Runtime API

TypeScript/Express application entry, composition, middleware, and feature routes.

- [Server](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/server.ts): entrypoint · Boots the HTTP process. · `src/server.ts`
- [App](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app.ts): express app · Composes middleware and route mounting. · `src/app.ts`
- [Root route](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/root.route.ts): health endpoint · Simple base response for service checks. · `src/app/modules/root.route.ts`
- [Auth mw](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/auth.ts): middleware · Protects routes with session-aware auth checks. · `src/app/middleware/auth.ts`
- [Validate mw](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/validateRequest.ts): middleware · Applies request validation before handlers run. · `src/app/middleware/validateRequest.ts`
- [Error mw](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/middleware/globalErrorHandler.ts): middleware · Centralized error handling for failed requests. · `src/app/middleware/globalErrorHandler.ts`
- [Auth lib](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/lib/auth.ts): session auth · Better Auth integration and session plumbing. · `src/lib/auth.ts`
- [Access utils](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/utils/access.ts): rbac helpers · Role and authorization helpers for protected actions. · `src/utils/access.ts`
- [Movies](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/movie/movie.route.ts): catalog feature · Movie and series management plus metadata workflows. · `src/app/modules/movie/movie.route.ts`
- [Reviews](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/review/review.route.ts): ugc feature · Review creation, moderation, likes, and spoiler controls. · `src/app/modules/review/review.route.ts`
- [Payments](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/payment/payment.route.ts): stripe feature · Payment intent creation and webhook handling. · `src/app/modules/payment/payment.route.ts`
- [Purchases](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/purchase/purchase.route.ts): commerce feature · Purchase records and premium access checks. · `src/app/modules/purchase/purchase.route.ts`
- [Watchlist](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/watchlist/watchlist.route.ts): personalization · Saved-title list for authenticated users. · `src/app/modules/watchlist/watchlist.route.ts`
- [Users](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/user/user.route.ts): account feature · User-facing account and profile operations. · `src/app/modules/user/user.route.ts`
- [Admin](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/app/modules/admin/admin.routes.ts): ops feature · Dashboard stats and cross-domain moderation tools. · `src/app/modules/admin/admin.routes.ts`

### Data Layer

Prisma client, schema, and generated ORM artifacts.

- [Prisma](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/lib/prisma.ts): orm client · Shared database client used by services. · `src/lib/prisma.ts`
- [Schema](https://github.com/arpan-dey-web/cinetube-backend/blob/main/prisma/schema.prisma): db schema · Prisma schema and migration source of truth. · `prisma/schema.prisma`
- [Generated client](https://github.com/arpan-dey-web/cinetube-backend/blob/main/src/generated/client.ts): generated orm · Checked-in Prisma client and model artifacts. · `src/generated/client.ts`

### Build Artifacts

Compiled output and deployment bundle.

- [Dist](https://github.com/arpan-dey-web/cinetube-backend/blob/main/dist/server.js): build output · Compiled runtime bundle for deployment. · `dist/server.js`

## Connections

- Server → App: boots · Server starts the Express app.
- App → Root route: mounts · App exposes the root status endpoint.
- App → Auth mw: uses · Requests pass through authentication guards.
- App → Validate mw: uses · Requests are validated before controller execution.
- App → Error mw: uses · Unhandled failures flow to centralized error handling.
- App → Movies: routes · Mounts movie/catalog routes.
- App → Reviews: routes · Mounts review routes.
- App → Payments: routes · Mounts payment routes and webhook entrypoints.
- App → Purchases: routes · Mounts purchase routes.
- App → Watchlist: routes · Mounts watchlist routes.
- App → Users: routes · Mounts user routes.
- App → Admin: routes · Mounts admin routes.
- Auth mw → Auth lib: verifies · Middleware relies on the session/auth provider.
- Auth mw → Access utils: checks · Protected and admin-only access is derived from role helpers.
- Movies → Prisma: reads/writes · Movie services persist via Prisma.
- Reviews → Prisma: reads/writes · Reviews and moderation data go through Prisma.
- Payments → Prisma: records · Payment and purchase state is stored in the database.
- Purchases → Prisma: checks · Purchase access checks query persisted state.
- Watchlist → Prisma: stores · Watchlist state is persisted through Prisma.
- Users → Prisma: reads/writes · User account data is backed by Prisma.
- Admin → Prisma: aggregates · Admin views aggregate data across domains.
- Prisma → Schema: built from · Client is generated from the Prisma schema.
- Prisma → Generated client: exports · Runtime consumes the checked-in generated client.
- Dist → Server: compiled from · Deployment bundle contains the compiled server entry.
