How arpan-dey-web/cinetube-backend works
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: app.ts App · prisma.ts Prisma · auth.ts Auth mw · server.ts Server
Components 19
Runtime API
TypeScript/Express application entry, composition, middleware, and feature routes.
- Server · Boots the HTTP process.
src/server.ts - App · Composes middleware and route mounting.
src/app.ts - Root route · Simple base response for service checks.
src/app/modules/root.route.ts - Auth mw · Protects routes with session-aware auth checks.
src/app/middleware/auth.ts - Validate mw · Applies request validation before handlers run.
src/app/middleware/validateRequest.ts - Error mw · Centralized error handling for failed requests.
src/app/middleware/globalErrorHandler.ts - Auth lib · Better Auth integration and session plumbing.
src/lib/auth.ts - Access utils · Role and authorization helpers for protected actions.
src/utils/access.ts - Movies · Movie and series management plus metadata workflows.
src/app/modules/movie/movie.route.ts - Reviews · Review creation, moderation, likes, and spoiler controls.
src/app/modules/review/review.route.ts - Payments · Payment intent creation and webhook handling.
src/app/modules/payment/payment.route.ts - Purchases · Purchase records and premium access checks.
src/app/modules/purchase/purchase.route.ts - Watchlist · Saved-title list for authenticated users.
src/app/modules/watchlist/watchlist.route.ts - Users · User-facing account and profile operations.
src/app/modules/user/user.route.ts - Admin · Dashboard stats and cross-domain moderation tools.
src/app/modules/admin/admin.routes.ts
Data Layer
Prisma client, schema, and generated ORM artifacts.
- Prisma · Shared database client used by services.
src/lib/prisma.ts - Schema · Prisma schema and migration source of truth.
prisma/schema.prisma - Generated client · Checked-in Prisma client and model artifacts.
src/generated/client.ts
Build Artifacts
Compiled output and deployment bundle.
- Dist · Compiled runtime bundle for deployment.
dist/server.js
Connections 24
- 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.