# arpan-dey-web/cinetube-frontend architecture

> Architecture diagram of the GitHub repository arpan-dey-web/cinetube-frontend, 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-frontend
- Repository: https://github.com/arpan-dey-web/cinetube-frontend

## Overview

1. **What this repository is**
   - This is a **Next.js App Router** frontend for a movie/series portal, organized as a **feature-based monorepo-style app** rather than a flat pages-only project.
   - The codebase is structured to support the README’s product vision: public browsing, auth, watchlist, reviews, payments, and an admin dashboard.
   - Based on the file tree, the repo is currently **frontend-heavy**; the backend is represented through feature API modules and a shared API client, but there is no separate Express/Prisma server in this tree.

2. **Top-level application boundary**
   - `src/app` is the routing shell and layout boundary.
   - It uses **route groups** to separate concerns:
     - `(public)` for marketing/catalog pages,
     - `(auth)` for login/register,
     - `dashboard` for authenticated user/admin areas.
   - `src/app/layout.tsx` and `src/app/globals.css` define the global app shell and styling baseline.
   - `src/app/(public)/layout.tsx` and `src/app/dashboard/layout.tsx` likely provide distinct navigation/footer/sidebar layouts for those zones.

3. **How pages are composed**
   - Most route files are thin wrappers that delegate to feature-level views.
   - Example pattern:
     - `src/app/(public)/browse/page.tsx` → `src/features/movie/views/browse-page.tsx`
     - `src/app/dashboard/admin/analytics/page.tsx` → `src/features/dashboard/views/admin-analytics-page.tsx`
   - This keeps routing separate from page implementation and makes the UI reusable across routes.

4. **Primary domain modules**
   - The app is split into feature domains under `src/features`:
     - **home**: landing page sections and public content pages
     - **movie**: browse and movie detail experiences
     - **auth**: login/register flows
     - **dashboard**: user/admin dashboard screens and analytics widgets
     - **watchlist**: saved titles
     - **review**: review-related data and display
     - **purchase** and **payment**: commerce/checkout flow
     - **archive**: archive page content
   - Each feature has its own `api`, `components`, and `views` folders, which is the main maintainability boundary in the repo.

5. **Data flow and content sourcing**
   - There are two visible data patterns:
     - **Static content modules** in `src/constants` for site content, catalog data, movie catalog, and blog posts.
     - **Feature API modules** in `src/features/*/api` that likely encapsulate remote calls or server interactions.
   - `src/shared/api/client.ts` is the central client abstraction, suggesting all feature-level fetches should go through one shared transport layer.
   - `src/actions/revalidate.ts` indicates the app uses **Next.js server actions / cache revalidation** as part of content updates or post-mutation refreshes.

6. **Public/marketing experience**
   - The public site is broad and content-rich:
     - home, about, blog, archive, browse, contact, FAQ, help, pricing, privacy, terms, watchlist.
   - Home page composition is driven by `src/features/home/components`, which includes:
     - hero/carousel
     - trending/newly added/editor’s picks
     - categories
     - stats
     - testimonials
     - pricing
     - FAQ
     - newsletter
     - blog preview
   - This aligns with the README’s requirement for a dense landing page with multiple meaningful sections.

7. **Catalog and detail experience**
   - `src/features/movie` is the core product area.
   - Browse flow includes:
     - search bar
     - filters panel
     - paginated grid
     - skeleton loading state
     - filter utilities and a dedicated hook for grid state
   - Detail flow includes:
     - hero/media presentation
     - sidebar metadata
     - related titles
     - review section
     - purchase modal
     - payment return notice
     - video player
   - This module is the clearest embodiment of the “movie/series listing + details + action” architecture.

8. **Authentication boundary**
   - Auth is isolated in `src/features/auth`, with separate API calls and page-specific components for login/register.
   - `src/providers/auth-provider.tsx` suggests session/auth state is made available app-wide through React context.
   - `src/features/auth/utils/auth-session.ts` is the likely place where session/token state is normalized for the UI.
   - Social login UI is represented by `AuthSocialButtons.tsx`, indicating the repo anticipates multiple auth methods even if the backend is not present here.

9. **User and admin dashboard architecture**
   - `src/app/dashboard` and `src/features/dashboard` form the multi-role workspace.
   - The dashboard feature contains:
     - overview cards
     - activity charts
     - genre donut chart
     - recent activity table
     - sidebar/topbar chrome
     - profile and watchlist views
     - admin views for analytics, messages, movies, reviews, and users
   - This is the main role-based boundary in the app: the dashboard is where operational/admin tasks are centralized.

10. **Commerce and monetization flow**
   - `src/features/payment` and `src/features/purchase` represent the checkout boundary.
   - `src/providers/StripeProvider.tsx` indicates Stripe is the concrete payment integration planned for the frontend.
   - The movie detail page includes a purchase modal and return notice, so purchase/payment is integrated into the title-detail journey rather than being a separate storefront.
   - `src/app/dashboard/purchase/page.tsx` exposes purchase history or access management inside the authenticated area.

11. **Reviews and social engagement**
   - `src/features/review` provides review API/query support and a featured reviews section.
   - `src/features/watchlist` provides the saved-items workflow via API and a public watchlist page.
   - The README describes likes/comments/spoilers/approval; in this tree, the architecture is ready for those behaviors but the implementation surface is centered on review rendering and API abstraction.

12. **Shared UI and design system**
   - `src/ui` is a component library of reusable primitives and composite controls: buttons, cards, dialogs, tables, sheets, sliders, charts, nav menus, sidebars, etc.
   - `src/shared/components` contains app-wide structural components such as navbar, footer, and page transitions.
   - `src/design-system` defines tokens for colors, spacing, typography, radius, shadows, and animations, which gives the app a centralized visual system rather than scattered ad hoc styling.

13. **Cross-cutting providers and runtime concerns**
   - `src/providers` contains app-wide context providers:
     - theme switching
     - auth/session
     - Stripe
   - `src/config/env.ts` and `src/config/routes.ts` centralize runtime configuration and route constants.
   - This indicates the app is designed to keep environment-sensitive values and navigation references out of feature code.

14. **Practical architecture takeaway**
   - The repo is organized around a clean flow:
     - **App Router route** → **feature view** → **feature components/API** → **shared client/constants/UI**
   - Public pages, authentication, catalog browsing, commerce, and dashboards are separated into distinct route and feature boundaries.
   - For an architecture diagram, the dominant containers are:
     - Next.js app shell
     - feature modules
     - shared UI/system layer
     - provider layer
     - static content/constants layer
     - external services implied by auth/payment/revalidation

Main entry points: [`src/shared/api/client.ts`](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/shared/api/client.ts) (API client), [`src/features/movie/views/movie-detail-page.tsx`](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/movie/views/movie-detail-page.tsx) (Detail view), [`src/features/dashboard/views/dashboard-home-page.tsx`](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/dashboard/views/dashboard-home-page.tsx) (Dashboard home), [`src/features/auth/components/LoginPage/LoginPage.tsx`](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/auth/components/LoginPage/LoginPage.tsx) (Login form)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App shell"]
  node_app_root_layout["Root layout<br/>app layout<br/>[layout.tsx]"]
  node_app_public_layout["Public layout<br/>route layout<br/>[layout.tsx]"]
  node_app_dashboard_layout["Dashboard layout<br/>route layout<br/>[layout.tsx]"]
  node_app_public_home["Home route<br/>route page<br/>[page.tsx]"]
  node_app_browse["Browse route<br/>route page<br/>[page.tsx]"]
  node_app_movie_detail["Detail route<br/>route page<br/>[page.tsx]"]
  node_app_login["Login route<br/>route page<br/>[page.tsx]"]
  node_app_register["Register route<br/>route page<br/>[page.tsx]"]
  node_app_dashboard_home["Dashboard home<br/>route page<br/>[page.tsx]"]
  node_app_admin_analytics["Admin analytics<br/>route page<br/>[page.tsx]"]
end

subgraph group_features["Feature modules"]
  node_feature_home["Home pages<br/>feature view<br/>[home-page.tsx]"]
  node_feature_movie_browse["Browse view<br/>feature view<br/>[browse-page.tsx]"]
  node_feature_movie_detail["Detail view<br/>feature view"]
  node_feature_auth_login["Login form<br/>auth component<br/>[LoginPage.tsx]"]
  node_feature_auth_register["Register form<br/>auth component<br/>[RegisterPage.tsx]"]
  node_feature_dashboard_home["Dashboard home<br/>dashboard view"]
  node_feature_admin_analytics["Admin analytics<br/>dashboard view"]
  node_feature_purchase["Purchase flow<br/>commerce view<br/>[purchase-page.tsx]"]
end

subgraph group_shared["Shared foundation"]
  node_shared_api["API client<br/>shared transport<br/>[client.ts]"]
  node_shared_nav_shell["Nav shell<br/>shared layout<br/>[Navbar.tsx]"]
  node_shared_ui["UI kit<br/>component library<br/>[button.tsx]"]
  node_content["Static content<br/>content constants<br/>[site-content.ts]"]
end

subgraph group_platform["Providers & config"]
  node_providers["App providers<br/>context providers<br/>[auth-provider.tsx]"]
  node_config["Config<br/>[routes.ts]"]
end

subgraph group_external["External services"]
  node_backend_api[("Backend API<br/>external backend")]
  node_stripe[("Stripe<br/>external payments")]
end

node_app_root_layout -->|"mounts"| node_providers
node_app_root_layout -->|"wraps"| node_shared_nav_shell
node_app_public_layout -->|"renders"| node_feature_home
node_app_public_layout -->|"uses"| node_shared_nav_shell
node_app_dashboard_layout -->|"wraps"| node_feature_dashboard_home
node_app_public_home -->|"delegates to"| node_feature_home
node_app_browse -->|"delegates to"| node_feature_movie_browse
node_app_movie_detail -->|"delegates to"| node_feature_movie_detail
node_app_login -->|"delegates to"| node_feature_auth_login
node_app_register -->|"delegates to"| node_feature_auth_register
node_app_dashboard_home -->|"delegates to"| node_feature_dashboard_home
node_app_admin_analytics -->|"delegates to"| node_feature_admin_analytics
node_feature_home -->|"reads"| node_content
node_feature_movie_browse -->|"queries via"| node_shared_api
node_feature_movie_detail -->|"queries via"| node_shared_api
node_feature_auth_login -->|"authenticates via"| node_shared_api
node_feature_auth_register -->|"authenticates via"| node_shared_api
node_feature_dashboard_home -->|"composes"| node_shared_ui
node_feature_admin_analytics -->|"composes"| node_shared_ui
node_feature_movie_detail -->|"checks out with"| node_stripe
node_feature_movie_detail -->|"loads data from"| node_backend_api
node_feature_dashboard_home -->|"loads data from"| node_backend_api
node_feature_auth_login -->|"loads data from"| node_backend_api
node_feature_auth_register -->|"loads data from"| node_backend_api
node_providers -->|"provides"| node_stripe
node_providers -->|"configures access to"| node_backend_api
node_config -->|"configures"| node_shared_api

click node_app_root_layout "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/layout.tsx"
click node_app_public_layout "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/layout.tsx"
click node_app_dashboard_layout "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/layout.tsx"
click node_app_public_home "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/page.tsx"
click node_app_browse "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/browse/page.tsx"
click node_app_movie_detail "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/browse/[id]/page.tsx"
click node_app_login "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(auth)/login/page.tsx"
click node_app_register "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(auth)/register/page.tsx"
click node_app_dashboard_home "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/page.tsx"
click node_app_admin_analytics "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/admin/analytics/page.tsx"
click node_feature_home "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/home/views/home-page.tsx"
click node_feature_movie_browse "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/movie/views/browse-page.tsx"
click node_feature_movie_detail "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/movie/views/movie-detail-page.tsx"
click node_feature_auth_login "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/auth/components/LoginPage/LoginPage.tsx"
click node_feature_auth_register "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/auth/components/RegisterPage/RegisterPage.tsx"
click node_feature_dashboard_home "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/dashboard/views/dashboard-home-page.tsx"
click node_feature_admin_analytics "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/dashboard/views/admin-analytics-page.tsx"
click node_feature_purchase "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/purchase/views/purchase-page.tsx"
click node_shared_api "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/shared/api/client.ts"
click node_shared_nav_shell "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/shared/components/Navbar.tsx"
click node_shared_ui "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/ui/button.tsx"
click node_providers "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/providers/auth-provider.tsx"
click node_config "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/config/routes.ts"
click node_content "https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/constants/site-content.ts"

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_app_root_layout,node_app_public_layout,node_app_dashboard_layout,node_app_public_home,node_app_browse,node_app_movie_detail,node_app_login,node_app_register,node_app_dashboard_home,node_app_admin_analytics toneBlue
class node_feature_home,node_feature_movie_browse,node_feature_movie_detail,node_feature_auth_login,node_feature_auth_register,node_feature_dashboard_home,node_feature_admin_analytics,node_feature_purchase toneAmber
class node_shared_api,node_shared_nav_shell,node_shared_ui,node_content toneMint
class node_providers,node_config toneRose
class node_backend_api,node_stripe toneIndigo
```

## Components

### App shell

Next.js App Router boundaries and route-level layouts.

- [Root layout](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/layout.tsx): app layout · Global app shell and top-level providers mount point. · `src/app/layout.tsx`
- [Public layout](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/layout.tsx): route layout · Shell for public browsing and marketing pages. · `src/app/(public)/layout.tsx`
- [Dashboard layout](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/layout.tsx): route layout · Shell for authenticated dashboard areas. · `src/app/dashboard/layout.tsx`
- [Home route](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/page.tsx): route page · Public landing page entry point. · `src/app/(public)/page.tsx`
- [Browse route](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/browse/page.tsx): route page · Public catalog browsing entry point. · `src/app/(public)/browse/page.tsx`
- [Detail route](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(public)/browse/[id]/page.tsx): route page · Movie or series detail page entry point. · `src/app/(public)/browse/[id]/page.tsx`
- [Login route](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(auth)/login/page.tsx): route page · Authentication sign-in entry point. · `src/app/(auth)/login/page.tsx`
- [Register route](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/(auth)/register/page.tsx): route page · Authentication sign-up entry point. · `src/app/(auth)/register/page.tsx`
- [Dashboard home](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/page.tsx): route page · Authenticated workspace landing page. · `src/app/dashboard/page.tsx`
- [Admin analytics](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/app/dashboard/admin/analytics/page.tsx): route page · Admin reporting and analytics entry point. · `src/app/dashboard/admin/analytics/page.tsx`

### Feature modules

Domain features that implement the product flows.

- [Home pages](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/home/views/home-page.tsx): feature view · Landing, about, help, pricing, blog, and policy views. · `src/features/home/views/home-page.tsx`
- [Browse view](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/movie/views/browse-page.tsx): feature view · Catalog search, filtering, pagination, and grid orchestration. · `src/features/movie/views/browse-page.tsx`
- [Detail view](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/movie/views/movie-detail-page.tsx): feature view · Title hero, metadata, related titles, reviews, and purchase flow. · `src/features/movie/views/movie-detail-page.tsx`
- [Login form](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/auth/components/LoginPage/LoginPage.tsx): auth component · Sign-in screen composition and form handling. · `src/features/auth/components/LoginPage/LoginPage.tsx`
- [Register form](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/auth/components/RegisterPage/RegisterPage.tsx): auth component · Sign-up screen composition and form handling. · `src/features/auth/components/RegisterPage/RegisterPage.tsx`
- [Dashboard home](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/dashboard/views/dashboard-home-page.tsx): dashboard view · Overview cards and activity summary for the authenticated area. · `src/features/dashboard/views/dashboard-home-page.tsx`
- [Admin analytics](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/dashboard/views/admin-analytics-page.tsx): dashboard view · Administrative analytics workspace. · `src/features/dashboard/views/admin-analytics-page.tsx`
- [Purchase flow](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/features/purchase/views/purchase-page.tsx): commerce view · Purchase and checkout boundary exposed from the dashboard. · `src/features/purchase/views/purchase-page.tsx`

### Shared foundation

Reusable UI, helpers, and transport used across features.

- [API client](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/shared/api/client.ts): shared transport · Central client used by feature API modules. · `src/shared/api/client.ts`
- [Nav shell](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/shared/components/Navbar.tsx): shared layout · Global navbar and footer composition. · `src/shared/components/Navbar.tsx`
- [UI kit](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/ui/button.tsx): component library · Reusable design-system-backed primitives and composites. · `src/ui/button.tsx`
- [Static content](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/constants/site-content.ts): content constants · Catalog, blog, and site content used by public pages. · `src/constants/site-content.ts`

### Providers & config

App-wide providers and runtime configuration.

- [App providers](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/providers/auth-provider.tsx): context providers · Theme, auth, and payment providers used across the app. · `src/providers/auth-provider.tsx`
- [Config](https://github.com/arpan-dey-web/cinetube-frontend/blob/main/src/config/routes.ts): runtime config · Environment values and route constants. · `src/config/routes.ts`

### External services

Backend and third-party systems implied by the frontend.

- **Backend API**: external backend · Remote application services consumed through the shared client.
- **Stripe**: external payments · Payment processor integrated through the payment provider.

## Connections

- Root layout → App providers: mounts · Global providers are composed at the root.
- Root layout → Nav shell: wraps · Root layout hosts common navigation chrome.
- Public layout → Home pages: renders · Public shell hosts marketing and content pages.
- Public layout → Nav shell: uses · Public area uses shared navbar/footer.
- Dashboard layout → Dashboard home: wraps · Dashboard shell provides authenticated workspace chrome.
- Home route → Home pages: delegates to · Route page delegates implementation to the home feature.
- Browse route → Browse view: delegates to · Catalog route delegates to the movie browse view.
- Detail route → Detail view: delegates to · Detail route delegates to the movie detail view.
- Login route → Login form: delegates to · Login route delegates to the auth feature.
- Register route → Register form: delegates to · Register route delegates to the auth feature.
- Dashboard home → Dashboard home: delegates to · Dashboard route delegates to the dashboard feature.
- Admin analytics → Admin analytics: delegates to · Admin analytics route delegates to the dashboard feature.
- Home pages → Static content: reads · Landing and content pages are powered by static content modules.
- Browse view → API client: queries via · Browse data is loaded through the shared API client.
- Detail view → API client: queries via · Detail data and mutations go through the shared API client.
- Login form → API client: authenticates via · Login uses feature API calls over the shared client.
- Register form → API client: authenticates via · Registration uses feature API calls over the shared client.
- Dashboard home → UI kit: composes · Dashboard screens are built from shared UI primitives.
- Admin analytics → UI kit: composes · Admin screens are built from shared UI primitives.
- Detail view → Stripe: checks out with · Purchase modal and payment flow integrate with Stripe.
- Detail view → Backend API: loads data from · Title, review, and related-content data come from backend services.
- Dashboard home → Backend API: loads data from · Dashboard metrics and activity are sourced from backend services.
- Login form → Backend API: loads data from · Session creation depends on backend auth services.
- Register form → Backend API: loads data from · Account creation depends on backend auth services.
- App providers → Stripe: provides · Stripe provider exposes payment context app-wide.
- App providers → Backend API: configures access to · Auth/session and theme providers support API-driven app behavior.
- Config → API client: configures · Environment and route constants shape the shared client and navigation.
