# leosilva-dev/moviematch architecture

> Architecture diagram of the GitHub repository leosilva-dev/moviematch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leosilva-dev/moviematch
- Repository: https://github.com/leosilva-dev/moviematch

## Overview

##### Project type and purpose
- This is a full-stack web application built with Next.js (App Router), using React for the UI, Prisma + a SQL database for persistence, and integrating with The Movie Database (TMDB) API.
- Users can create “sessions” (identified by a code), browse popular movies (via TMDB), and vote on movies within a session.

##### High-level file-structure analysis
- infra/docker-compose.yaml: local Docker setup (database, possibly Prisma Studio).
- prisma/: database schema and migrations for sessions & votes tables.
- src/app/: Next.js App Router—pages (SSR/SSG), server-side API routes under src/app/api.
- src/components/: shared UI components (buttons, cards, inputs).
- src/lib/: helper modules (Prisma client, TMDB API client, utility functions).
- next.config.ts, eslint.config.mjs, postcss.config.mjs, tsconfig.json: configuration.

##### Key README insights
- Bootstrapped via create-next-app.
- Standard dev workflow (npm run dev).
- Deployed on Vercel (supports serverless functions for API routes).

##### Main components
a. Client (Browser) – React pages & UI components
b. Next.js Server –
- App Router + Page rendering (SSR/SSG)
- API Routes (serverless functions)
c. Internal Services –
- TMDB Service (wrapped in src/lib/tmdb.ts)
- Prisma Service (src/lib/prisma.ts)
d. Database – PostgreSQL (or another SQL) managed via Docker Compose
e. External Service – TMDB REST API

##### Relationships & data flow
- Browser → Next.js Page (SSR) → Next.js API Route (if client-side fetch or form submit).
- API Route uses Prisma client to read/write sessions & votes in the database.
- API Route may call TMDB client to fetch popular movies.
- Next.js Page renders data returned from API or fetches directly via getServerSideProps / server components.
- Prisma client issues SQL queries to the database.
- Docker Compose hosts the database; Prisma migrations manage schema.

##### Architectural patterns & design principles
- Separation of concerns:
- UI Components vs. Data-access (Prisma) vs. External API (TMDB)
- API routes as thin controllers invoking service libraries.
- DTOs/Types in src/types to keep domain models typed.
- Migrations with Prisma to ensure reproducible schema changes.
- Infra folder codifies environment setup (Docker for local dev).

##### Technologies & frameworks in each layer
- Frontend: Next.js App Router, React, CSS modules or global CSS (globals.css), Vercel Font Optimization.
- Backend: Next.js API Routes (serverless), TypeScript.
- Data layer: Prisma ORM, PostgreSQL.
- External: TMDB REST API via Axios or native fetch wrapper in src/lib/tmdb.ts.
- Infra: Docker Compose for local DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Browser + UI Components)"
        direction TB
        Browser["Browser"]:::external
        subgraph "Next.js Pages" 
            direction TB
            HomePage["src/app/page.tsx"]:::frontend
            SessionPage["src/app/session/[code]/page.tsx"]:::frontend
            Layout["src/app/layout.tsx"]:::frontend
        end
        subgraph "UI Components"
            direction TB
            Button["src/components/ui/button.tsx"]:::frontend
            Card["src/components/ui/card.tsx"]:::frontend
            Input["src/components/ui/input.tsx"]:::frontend
        end
    end

    %% Server Layer
    subgraph "Next.js Server (App Router & API)"
        direction TB
        subgraph "App Router & SSR"
            direction TB
            GlobalsCSS["src/app/globals.css"]:::server
        end
        subgraph "API Routes (Serverless)"
            direction TB
            MoviesAPI["src/app/api/movies/popular/route.ts"]:::server
            SessionsAPI["src/app/api/sessions/route.ts"]:::server
            SessionCodeAPI["src/app/api/sessions/[code]/route.ts"]:::server
            VotesAPI["src/app/api/votes/route.ts"]:::server
        end
    end

    %% Services Layer
    subgraph "Internal Services & Utilities"
        direction TB
        PrismaClient["src/lib/prisma.ts"]:::service
        TMDBClient["src/lib/tmdb.ts"]:::service
        Utils["src/lib/utils.ts"]:::service
    end

    %% Database
    Database[(PostgreSQL)]:::database

    %% External Service
    ExternalTMDB(("TMDB REST API")):::external

    %% Infra & Config
    infra["infra/docker-compose.yaml"]:::infra
    nextConfig["next.config.ts"]:::infra
    tsconfig["tsconfig.json"]:::infra
    eslint["eslint.config.mjs"]:::infra
    postcss["postcss.config.mjs"]:::infra
    schema["prisma/schema.prisma"]:::infra
    mig1["prisma/migrations/20250424145335_create_sessions_table/migration.sql"]:::infra
    mig2["prisma/migrations/20250511040403_add_votes_model/migration.sql"]:::infra
    typesTMDB["src/types/tmdb.ts"]:::infra

    %% Connections
    Browser -->|"Navigation / SSR"| HomePage
    Browser -->|"Navigation / SSR"| SessionPage
    HomePage -->|"Fetch data REST/HTTP"| SessionsAPI
    SessionPage -->|"Fetch session REST/HTTP"| SessionCodeAPI
    SessionPage -->|"Fetch movies REST/HTTP"| MoviesAPI
    SessionPage -->|"Submit vote REST/HTTP"| VotesAPI

    MoviesAPI -->|"uses"| TMDBClient
    SessionsAPI -->|"uses"| PrismaClient
    SessionCodeAPI -->|"uses"| PrismaClient
    VotesAPI -->|"uses"| PrismaClient

    PrismaClient -->|"SQL queries"| Database
    TMDBClient -->|"HTTP GET /movie/popular"| ExternalTMDB

    infra -->|"Hosts DB"| Database
    schema -->|"Defines schema"| PrismaClient
    mig1 -->|"Migration"| Database
    mig2 -->|"Migration"| Database

    %% Click events
    click HomePage "https://github.com/leosilva-dev/moviematch/blob/main/src/app/page.tsx"
    click SessionPage "https://github.com/leosilva-dev/moviematch/blob/main/src/app/session/[code]/page.tsx"
    click Layout "https://github.com/leosilva-dev/moviematch/blob/main/src/app/layout.tsx"
    click Button "https://github.com/leosilva-dev/moviematch/blob/main/src/components/ui/button.tsx"
    click Card "https://github.com/leosilva-dev/moviematch/blob/main/src/components/ui/card.tsx"
    click Input "https://github.com/leosilva-dev/moviematch/blob/main/src/components/ui/input.tsx"
    click GlobalsCSS "https://github.com/leosilva-dev/moviematch/blob/main/src/app/globals.css"
    click MoviesAPI "https://github.com/leosilva-dev/moviematch/blob/main/src/app/api/movies/popular/route.ts"
    click SessionsAPI "https://github.com/leosilva-dev/moviematch/blob/main/src/app/api/sessions/route.ts"
    click SessionCodeAPI "https://github.com/leosilva-dev/moviematch/blob/main/src/app/api/sessions/[code]/route.ts"
    click VotesAPI "https://github.com/leosilva-dev/moviematch/blob/main/src/app/api/votes/route.ts"
    click PrismaClient "https://github.com/leosilva-dev/moviematch/blob/main/src/lib/prisma.ts"
    click TMDBClient "https://github.com/leosilva-dev/moviematch/blob/main/src/lib/tmdb.ts"
    click Utils "https://github.com/leosilva-dev/moviematch/blob/main/src/lib/utils.ts"
    click infra "https://github.com/leosilva-dev/moviematch/blob/main/infra/docker-compose.yaml"
    click nextConfig "https://github.com/leosilva-dev/moviematch/blob/main/next.config.ts"
    click tsconfig "https://github.com/leosilva-dev/moviematch/blob/main/tsconfig.json"
    click eslint "https://github.com/leosilva-dev/moviematch/blob/main/eslint.config.mjs"
    click postcss "https://github.com/leosilva-dev/moviematch/blob/main/postcss.config.mjs"
    click schema "https://github.com/leosilva-dev/moviematch/blob/main/prisma/schema.prisma"
    click mig1 "https://github.com/leosilva-dev/moviematch/blob/main/prisma/migrations/20250424145335_create_sessions_table/migration.sql"
    click mig2 "https://github.com/leosilva-dev/moviematch/blob/main/prisma/migrations/20250511040403_add_votes_model/migration.sql"
    click typesTMDB "https://github.com/leosilva-dev/moviematch/blob/main/src/types/tmdb.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef server fill:#FED8B1,stroke:#d2691e,color:#d2691e;
    classDef service fill:#FFE4B5,stroke:#cd853f,color:#cd853f;
    classDef database fill:#C8E6C9,stroke:#388e3c,color:#388e3c;
    classDef external fill:#E0E0E0,stroke:#757575,color:#424242;
    classDef infra fill:#f0f4c3,stroke:#9e9d24,color:#9e9d24;
```
