# joegcode/trailerflix-nextjs architecture

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

- Interactive diagram: https://gitdiagram.com/joegcode/trailerflix-nextjs
- Repository: https://github.com/joegcode/trailerflix-nextjs

## Overview

##### Main Components
- Frontend:
- Pages under src/app (e.g., home, about, search, movie details, user pages) using React components.
- UI components from src/components (Navbar, MovieCard, CardGrid, SearchBar, etc.).
- Business & API Logic:
- Actions (under src/actions) split between authentication (signIn, signOut, signUp) and movie-related actions (getMovieDetails, getMovies, searchMovies, etc.).
- API endpoints under src/app/api (e.g., /api/movie-videos, /api/search, etc.) which bridge client requests with backend logic.
- Data Access / Integration:
- External TMDB API usage is evident through utility functions and constant configuration (src/utils/constants/tmdb.ts).
- Supabase integration for user data and favorites via src/utils/supabase (client.ts, server.ts, middleware.ts).
- Validation/Schema layer:
- Schemas under src/schemas/auth (for signIn and signUp validation) to enforce correct data structure.
- Configuration & Build:
- Config files such as next.config.ts, tailwind.config.ts, and configuration for ESLint, Prettier, etc.

##### Relationships and Data Flows
- The Browser (client) interacts with the Next.js frontend view layer which includes components rendering pages as defined in src/app.
- UI components dispatch user actions (e.g., sign in/up, searching movies, handling favorites) that call the actions in src/actions.
- API endpoints in src/app/api act as middleware – receiving HTTP requests (from the UI or via browser API calls) and invoking corresponding actions.
- Business logic in actions fetches data primarily from external services:
- Movie information from TMDB (using utilities in src/utils/constants/tmdb.ts and related service functions).
- User and favorites data via Supabase (using utils/supabase).
- Schemas validate data to ensure secure and correct transactions between frontend actions and the backend.
- Finally, rendered results are sent back to the client to update the UI.

##### Architectural Patterns and Design Principles
- Component-Based Architecture: Clear separation between pages (application routing) and presentational components (found in src/components).
- Separation of Concerns: Distinct layers for UI, business logic (actions), API endpoints, and external service integrations.
- API-Driven Interactions: Use of Next.js API routes which act as a backend layer for server-side operations.
- Modular and Extensible: The directory structure (with “actions”, “components”, “schemas”, “utils”) suggests a modular approach that makes future feature additions (e.g., TV Shows, Actor Pages) straightforward.
- External Service Reliance: Direct integration with TMDB and Supabase, critical to the application’s functionality.

##### Relevant Technologies, Frameworks, or Libraries
- Next.js: The core framework managing page routing and server/client rendering.
- Tailwind CSS: For utility-first styling and responsive design.
- Supabase: For handling user authentication and favorites management.
- Integration with external TMDB API for movie data.
- TypeScript for type safety (noted by .ts and tsconfig.json).

##### Detailed Architectural Elements
- Specific features such as search functionality, authentication routes (login, sign-up, confirm), and favorites.
- Presence of middleware (src/middleware.ts and supabase middleware in src/utils/supabase) which could serve as request interceptors or validators.
- How client-side UX (via components) communicates with server-side functions and eventually external services.

This structured breakdown ensures all essential architectural elements are captured for both current functionalities and future enhancements listed in the roadmap.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    A["Browser (Client)"]:::browser

    %% Frontend Layer
    subgraph "Frontend Layer"
        B["Frontend Pages"]:::frontend
        C["UI Components"]:::frontend
    end

    %% API & Business Layer
    subgraph "API & Business Logic"
        D["API Endpoints"]:::api
        E["Actions: Authentication"]:::actions
        F["Actions: Movies"]:::actions
        G["Schema (Auth)"]:::schema
    end

    %% Data Integration Layer
    subgraph "External Integrations"
        H["TMDB Integration"]:::external
        I["Supabase Integration"]:::external
    end

    %% Configuration & Build (Side Component)
    J["Configuration & Build"]:::config

    %% Data Flow
    A -->|"request"| B
    B -->|"renders"| C
    C -->|"triggers"| D
    D -->|"callsAuth"| E
    D -->|"callsMovies"| F
    E -->|"validates"| G
    F -->|"fetchesData"| H
    E -->|"managesUser"| I
    F -->|"updatesFav"| I
    
    %% Feedback Loop
    E -->|"responds"| D
    F -->|"responds"| D
    D -->|"rendersData"| C
    C -->|"updatesUI"| B
    B -->|"response"| A

    %% Click Events
    click B "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/app"
    click C "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/components"
    click D "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/app/api"
    click E "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/actions/auth"
    click F "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/actions/movies"
    click G "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/schemas/auth"
    click H "https://github.com/joegcode/trailerflix-nextjs/blob/master/src/utils/constants/tmdb.ts"
    click I "https://github.com/joegcode/trailerflix-nextjs/tree/master/src/utils/supabase"
    click J "https://github.com/joegcode/trailerflix-nextjs/blob/master/next.config.ts"

    %% Styles
    classDef browser fill:#f7c6c7,stroke:#333,stroke-width:2px;
    classDef frontend fill:#dfe7fd,stroke:#333,stroke-width:2px;
    classDef api fill:#fdd835,stroke:#333,stroke-width:2px;
    classDef actions fill:#a5d6a7,stroke:#333,stroke-width:2px;
    classDef schema fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef external fill:#b39ddb,stroke:#333,stroke-width:2px;
    classDef config fill:#80deea,stroke:#333,stroke-width:2px;
```
