# inman2004/moviesdb architecture

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

- Interactive diagram: https://gitdiagram.com/inman2004/moviesdb
- Repository: https://github.com/inman2004/moviesdb

## Overview

#### Purpose and Runtime
MoviesDB is a client-side React movie-discovery application backed by The Movie Database (TMDB) API. It runs as a Vite-built TypeScript SPA, with Tailwind/PostCSS styling and browser-side state. The TMDB credential is supplied through `VITE_TMDB_API_KEY`.

Key runtime entry points:
- `client/src/main.tsx` bootstraps React into the browser.
- `client/src/App.tsx` defines the application shell and likely route composition.
- `client/src/services/api.ts` is the boundary for TMDB requests.

#### Application Shell and Navigation
The root application coordinates shared UI, page rendering, and global visual behavior. Reusable header/footer components form the persistent navigation shell around route-specific pages.

- `client/src/App.tsx`
- `client/src/components/Header.tsx`
- `client/src/components/Footer.tsx`

React Router v6 is the stated navigation mechanism; page modules represent movie browsing, search, profile, and personal-library destinations.

#### Movie Discovery and Presentation
The home page organizes TMDB movie categories—popular, top rated, currently playing, and upcoming—into reusable visual sections and card/slider displays. Loading placeholders keep asynchronous API fetches from producing empty layouts.

- `client/src/pages/home.tsx`
- `client/src/components/MovieSection.tsx`
- `client/src/components/MoviesCard.tsx`
- `client/src/components/Slider.tsx`
- `client/src/components/MovieCardSkeleton.tsx`
- `client/src/components/LoadingSpinner.tsx`

#### Detail, Search, and Playback Flows
Search is a dedicated page that turns user input into TMDB queries. Actor profiles expose person-centric data. Movie playback is isolated as its own route/page, separating embedded or selected viewing behavior from discovery UI.

- `client/src/pages/SearchPage.tsx`
- `client/src/pages/ActorProfile.tsx`
- `client/src/pages/MoviePlayer.tsx`
- `client/src/components/Reviews.tsx`
- `client/src/services/api.ts`

The API service is the external-service boundary: UI components/pages should consume normalized request functions rather than embed TMDB URLs or keys directly.

#### Client-Side Library State
Favorites, watchlists, watched history, and collections are modeled as separate React Context providers. These contexts provide cross-route state for user-curated movie lists without a repository-visible backend.

- `client/src/context/FavoritesContext.tsx`
- `client/src/context/WatchlistContext.tsx`
- `client/src/context/WatchedContext.tsx`
- `client/src/context/CollectionsContext.tsx`

Corresponding pages render each state domain:
- `client/src/pages/Favorites.tsx`
- `client/src/pages/Watchlist.tsx`
- `client/src/pages/History.tsx`
- `client/src/pages/Collections.tsx`

#### Theme and Profile Boundary
Theme selection is global UI state, independently provided from movie-library contexts. Profile is a route-level consumer/presentation boundary for user-oriented features rather than an indicated authentication service.

- `client/src/context/ThemeContext.tsx`
- `client/src/pages/Profile.tsx`

#### Build and Deployment
The client is built and served by Vite, deployed as a static SPA with Vercel-specific routing/deployment configuration. GitHub Actions contains the deployment automation.

- `client/vite.config.ts`
- `client/vercel.json`
- `.github/workflows/deploy.yml`

Primary infrastructure is Node.js/npm for development and build, Vercel for hosting, and TMDB as the sole identified remote data service.

Main entry points: [`client/src/App.tsx`](https://github.com/inman2004/moviesdb/blob/main/client/src/App.tsx) (Application shell), [`client/src/services/api.ts`](https://github.com/inman2004/moviesdb/blob/main/client/src/services/api.ts) (TMDB API service), [`client/src/pages/home.tsx`](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/home.tsx) (Home discovery), [`client/src/pages/SearchPage.tsx`](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/SearchPage.tsx) (Search page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["React SPA"]
  node_main(("React bootstrap<br/>entry point<br/>[main.tsx]"))
  node_app["Application shell<br/>React root<br/>[App.tsx]"]
  node_navigation["Header &amp; footer<br/>shared UI<br/>[Header.tsx]"]
  node_home["Home discovery<br/>route page<br/>[home.tsx]"]
  node_movie_views["Movie sections &amp; cards<br/>presentation<br/>[MovieSection.tsx]"]
  node_search["Search page<br/>route page<br/>[SearchPage.tsx]"]
  node_detail_routes["Actor, reviews &amp; player<br/>route features<br/>[ActorProfile.tsx]"]
  node_library_pages["Library pages<br/>route pages<br/>[Favorites.tsx]"]
  node_profile["Profile<br/>route page<br/>[Profile.tsx]"]
  node_api{{"TMDB API service<br/>service boundary<br/>[api.ts]"}}
end

subgraph group_state["Client State"]
  node_library_contexts["Movie library contexts<br/>React Context"]
  node_theme_context["Theme context<br/>React Context<br/>[ThemeContext.tsx]"]
end

subgraph group_delivery["Build &amp; Delivery"]
  node_vite["Vite build<br/>build configuration<br/>[vite.config.ts]"]
  node_vercel_config["Vercel routing config<br/>deployment configuration<br/>[vercel.json]"]
  node_deploy["GitHub deployment<br/>CI workflow<br/>[deploy.yml]"]
end

node_tmdb[("TMDB<br/>external movie API")]
node_vercel["Vercel hosting<br/>static hosting"]

node_main -->|"mounts"| node_app
node_app -->|"renders"| node_navigation
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_search
node_app -->|"routes to"| node_detail_routes
node_app -->|"routes to"| node_library_pages
node_app -->|"routes to"| node_profile
node_app -->|"provides"| node_library_contexts
node_app -->|"provides"| node_theme_context
node_home -->|"composes"| node_movie_views
node_home -->|"loads categories"| node_api
node_search -->|"queries"| node_api
node_detail_routes -->|"loads movie and person data"| node_api
node_api -->|"requests"| node_tmdb
node_library_pages -->|"reads and updates"| node_library_contexts
node_profile -->|"consumes"| node_theme_context
node_vite -->|"builds static SPA for"| node_vercel
node_vercel_config -->|"configures"| node_vercel
node_deploy -->|"deploys to"| node_vercel

click node_main "https://github.com/inman2004/moviesdb/blob/main/client/src/main.tsx"
click node_app "https://github.com/inman2004/moviesdb/blob/main/client/src/App.tsx"
click node_navigation "https://github.com/inman2004/moviesdb/blob/main/client/src/components/Header.tsx"
click node_home "https://github.com/inman2004/moviesdb/blob/main/client/src/pages/home.tsx"
click node_movie_views "https://github.com/inman2004/moviesdb/blob/main/client/src/components/MovieSection.tsx"
click node_search "https://github.com/inman2004/moviesdb/blob/main/client/src/pages/SearchPage.tsx"
click node_detail_routes "https://github.com/inman2004/moviesdb/blob/main/client/src/pages/ActorProfile.tsx"
click node_library_pages "https://github.com/inman2004/moviesdb/blob/main/client/src/pages/Favorites.tsx"
click node_profile "https://github.com/inman2004/moviesdb/blob/main/client/src/pages/Profile.tsx"
click node_api "https://github.com/inman2004/moviesdb/blob/main/client/src/services/api.ts"
click node_library_contexts "https://github.com/inman2004/moviesdb/blob/main/client/src/context/FavoritesContext.tsx"
click node_theme_context "https://github.com/inman2004/moviesdb/blob/main/client/src/context/ThemeContext.tsx"
click node_vite "https://github.com/inman2004/moviesdb/blob/main/client/vite.config.ts"
click node_vercel_config "https://github.com/inman2004/moviesdb/blob/main/client/vercel.json"
click node_deploy "https://github.com/inman2004/moviesdb/blob/main/.github/workflows/deploy.yml"

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_main,node_app,node_navigation,node_home,node_movie_views,node_search,node_detail_routes,node_library_pages,node_profile,node_api toneBlue
class node_library_contexts,node_theme_context toneAmber
class node_vite,node_vercel_config,node_deploy toneMint
class node_tmdb,node_vercel toneNeutral
```

## Components

### React SPA

Browser-rendered application UI and routes.

- [React bootstrap](https://github.com/inman2004/moviesdb/blob/main/client/src/main.tsx): entry point · `client/src/main.tsx`
- [Application shell](https://github.com/inman2004/moviesdb/blob/main/client/src/App.tsx): React root · Composes routes and persistent UI. · `client/src/App.tsx`
- [Header & footer](https://github.com/inman2004/moviesdb/blob/main/client/src/components/Header.tsx): shared UI · Persistent navigation shell components. · `client/src/components/Header.tsx`
- [Home discovery](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/home.tsx): route page · Displays TMDB movie categories. · `client/src/pages/home.tsx`
- [Movie sections & cards](https://github.com/inman2004/moviesdb/blob/main/client/src/components/MovieSection.tsx): presentation · Reusable section, card, slider, and loading displays. · `client/src/components/MovieSection.tsx`
- [Search page](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/SearchPage.tsx): route page · Turns user input into movie queries. · `client/src/pages/SearchPage.tsx`
- [Actor, reviews & player](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/ActorProfile.tsx): route features · Person profiles, reviews, and isolated movie playback. · `client/src/pages/ActorProfile.tsx`
- [Library pages](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/Favorites.tsx): route pages · Favorites, watchlist, history, and collections views. · `client/src/pages/Favorites.tsx`
- [Profile](https://github.com/inman2004/moviesdb/blob/main/client/src/pages/Profile.tsx): route page · `client/src/pages/Profile.tsx`
- [TMDB API service](https://github.com/inman2004/moviesdb/blob/main/client/src/services/api.ts): service boundary · Centralizes TMDB request functions and credentials. · `client/src/services/api.ts`

### Client State

Cross-route React Context providers.

- [Movie library contexts](https://github.com/inman2004/moviesdb/blob/main/client/src/context/FavoritesContext.tsx): React Context · Favorites, watchlist, watched history, and collections state. · `client/src/context/FavoritesContext.tsx`
- [Theme context](https://github.com/inman2004/moviesdb/blob/main/client/src/context/ThemeContext.tsx): React Context · Global visual theme state. · `client/src/context/ThemeContext.tsx`

### Build & Delivery

Static SPA build and deployment pipeline.

- [Vite build](https://github.com/inman2004/moviesdb/blob/main/client/vite.config.ts): build configuration · `client/vite.config.ts`
- [Vercel routing config](https://github.com/inman2004/moviesdb/blob/main/client/vercel.json): deployment configuration · Configures static SPA routing and hosting. · `client/vercel.json`
- [GitHub deployment](https://github.com/inman2004/moviesdb/blob/main/.github/workflows/deploy.yml): CI workflow · Automates deployment. · `.github/workflows/deploy.yml`

### Other components

- **TMDB**: external movie API · Remote movie and person data service.
- **Vercel hosting**: static hosting

## Connections

- React bootstrap → Application shell: mounts
- Application shell → Header & footer: renders
- Application shell → Home discovery: routes to
- Application shell → Search page: routes to
- Application shell → Actor, reviews & player: routes to
- Application shell → Library pages: routes to
- Application shell → Profile: routes to
- Application shell → Movie library contexts: provides
- Application shell → Theme context: provides
- Home discovery → Movie sections & cards: composes
- Home discovery → TMDB API service: loads categories
- Search page → TMDB API service: queries
- Actor, reviews & player → TMDB API service: loads movie and person data
- TMDB API service → TMDB: requests
- Library pages → Movie library contexts: reads and updates
- Profile → Theme context: consumes
- Vite build → Vercel hosting: builds static SPA for
- Vercel routing config → Vercel hosting: configures
- GitHub deployment → Vercel hosting: deploys to