# gwill1337/petnetflix architecture

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

- Interactive diagram: https://gitdiagram.com/gwill1337/petnetflix
- Repository: https://github.com/gwill1337/petnetflix

## Overview

PetNetflix is a full-stack movie browsing app. Users browse and search a movie catalog, view movie details, and—when signed in—manage favorites and comments. The React app serves the browsing flow and calls the FastAPI API; authentication supports passwords and Google OAuth, with refreshable cookie sessions. The backend routers own their domain operations and use SQLAlchemy models for PostgreSQL state. README documents the major capabilities; some frontend component-to-API calls and router registrations are supported only at the documentation or import-reference level, so uncertain links are omitted.

Main entry points: [`core/main.py`](https://github.com/gwill1337/petnetflix/blob/dev/core/main.py) (FastAPI app), [`core/db.py`](https://github.com/gwill1337/petnetflix/blob/dev/core/db.py) (SQLAlchemy models), [`frontend/src/App.tsx`](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/App.tsx) (Movie catalog), [`core/routers/oauth.py`](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/oauth.py) (Google OAuth)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_routes["App routes<br/>[MainRoutes.tsx]"]
  node_catalog["Movie catalog<br/>[App.tsx]"]
  node_moviecard["Movie cards<br/>[MovieCard.tsx]"]
  node_details["Movie details<br/>[MovieDetails.tsx]"]
  node_commentsui["Comments UI<br/>[Comments.tsx]"]
  node_favoriteui["Favorite control<br/>[FavoriteButton.tsx]"]
  node_header["Header and search<br/>[Header.tsx]"]
  node_authmodal["Sign-in modal<br/>[AuthModal.tsx]"]
  node_authprovider["Auth provider<br/>[AuthProvider.tsx]"]
  node_authstate["Auth state<br/>[auth.context.ts]"]
  node_authhook["Auth hook<br/>[useAuth.ts]"]
  node_themeprovider["Theme provider<br/>[ThemeProvider.tsx]"]
  node_themecontext["Theme state<br/>[theme.context.ts]"]
  node_debounce["Debounce hook<br/>[useDebounce.ts]"]
  node_frontendconfig["API configuration<br/>[config.ts]"]
end

subgraph group_api["API services"]
  node_api["FastAPI app<br/>[main.py]"]
  node_movies["Movie endpoints<br/>[movies.py]"]
  node_favorites["Favorite endpoints<br/>[favorites.py]"]
  node_comments["Comment endpoints<br/>[comments.py]"]
  node_config["Backend settings<br/>[config.py]"]
  node_schemas["API schemas<br/>[schemas.py]"]
end

subgraph group_identity["Identity"]
  node_auth["Password auth<br/>[auth.py]"]
  node_oauth["Google OAuth<br/>[oauth.py]"]
  node_security["Token security<br/>[security.py]"]
end

subgraph group_data["Persistence"]
  node_db["SQLAlchemy models<br/>[db.py]"]
  node_postgres[("PostgreSQL")]
end

node_user(("Movie viewer"))
node_google(("Google identity"))
node_apiurl["Backend API"]

node_user -->|"uses"| node_routes
node_routes -->|"routes to"| node_catalog
node_routes -->|"routes to"| node_details
node_catalog -->|"fetches movies"| node_apiurl
node_catalog -->|"renders"| node_moviecard
node_moviecard -->|"renders"| node_favoriteui
node_details -->|"renders"| node_commentsui
node_header -->|"opens"| node_authmodal
node_authprovider -->|"provides"| node_authstate
node_authhook -->|"reads"| node_authstate
node_themeprovider -->|"provides"| node_themecontext
node_catalog -->|"imports"| node_debounce
node_apiurl -.->|"sends requests"| node_api
node_api -->|"registers"| node_movies
node_api -->|"registers"| node_favorites
node_api -->|"registers"| node_comments
node_api -->|"registers"| node_auth
node_api -->|"registers"| node_oauth
node_auth -->|"queries"| node_db
node_auth -->|"issues tokens"| node_security
node_oauth -->|"queries"| node_db
node_oauth -->|"issues tokens"| node_security
node_oauth -->|"authenticates with"| node_google
node_movies -->|"queries"| node_db
node_favorites -->|"queries"| node_db
node_comments -->|"queries"| node_db
node_db -->|"persists"| node_postgres
node_api -->|"loads settings"| node_config

click node_routes "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/MainRoutes.tsx"
click node_catalog "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/App.tsx"
click node_moviecard "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/MovieCard.tsx"
click node_details "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/pages/MovieDetails.tsx"
click node_commentsui "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/Comments.tsx"
click node_favoriteui "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/FavoriteButton.tsx"
click node_header "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/Header.tsx"
click node_authmodal "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/AuthModal.tsx"
click node_authprovider "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/AuthProvider.tsx"
click node_authstate "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/context/auth.context.ts"
click node_authhook "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/hooks/useAuth.ts"
click node_themeprovider "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/ThemeProvider.tsx"
click node_themecontext "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/context/theme.context.ts"
click node_debounce "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/hooks/useDebounce.ts"
click node_frontendconfig "https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/config/config.ts"
click node_api "https://github.com/gwill1337/petnetflix/blob/dev/core/main.py"
click node_movies "https://github.com/gwill1337/petnetflix/blob/dev/core/routers/movies.py"
click node_favorites "https://github.com/gwill1337/petnetflix/blob/dev/core/routers/favorites.py"
click node_comments "https://github.com/gwill1337/petnetflix/blob/dev/core/routers/comments.py"
click node_auth "https://github.com/gwill1337/petnetflix/blob/dev/core/routers/auth.py"
click node_oauth "https://github.com/gwill1337/petnetflix/blob/dev/core/routers/oauth.py"
click node_security "https://github.com/gwill1337/petnetflix/blob/dev/core/security.py"
click node_config "https://github.com/gwill1337/petnetflix/blob/dev/core/config.py"
click node_schemas "https://github.com/gwill1337/petnetflix/blob/dev/core/schemas.py"
click node_db "https://github.com/gwill1337/petnetflix/blob/dev/core/db.py"

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_routes,node_catalog,node_moviecard,node_details,node_commentsui,node_favoriteui,node_header,node_authmodal,node_authprovider,node_authstate,node_authhook,node_themeprovider,node_themecontext,node_debounce,node_frontendconfig,node_user toneBlue
class node_api,node_movies,node_favorites,node_comments,node_config,node_schemas toneAmber
class node_auth,node_oauth,node_security,node_apiurl toneMint
class node_db,node_postgres toneRose
class node_google toneIndigo
```

## Components

### Web app

- [App routes](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/MainRoutes.tsx): `frontend/src/MainRoutes.tsx`
- [Movie catalog](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Movie cards](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/MovieCard.tsx): `frontend/src/components/MovieCard.tsx`
- [Movie details](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/pages/MovieDetails.tsx): `frontend/src/pages/MovieDetails.tsx`
- [Comments UI](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/Comments.tsx): `frontend/src/components/Comments.tsx`
- [Favorite control](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/FavoriteButton.tsx): `frontend/src/components/FavoriteButton.tsx`
- [Header and search](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/Header.tsx): `frontend/src/components/Header.tsx`
- [Sign-in modal](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/AuthModal.tsx): `frontend/src/components/AuthModal.tsx`
- [Auth provider](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/AuthProvider.tsx): `frontend/src/components/AuthProvider.tsx`
- [Auth state](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/context/auth.context.ts): `frontend/src/context/auth.context.ts`
- [Auth hook](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/hooks/useAuth.ts): `frontend/src/hooks/useAuth.ts`
- [Theme provider](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/components/ThemeProvider.tsx): `frontend/src/components/ThemeProvider.tsx`
- [Theme state](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/context/theme.context.ts): `frontend/src/context/theme.context.ts`
- [Debounce hook](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/hooks/useDebounce.ts): `frontend/src/hooks/useDebounce.ts`
- [API configuration](https://github.com/gwill1337/petnetflix/blob/dev/frontend/src/config/config.ts): `frontend/src/config/config.ts`

### API services

- [FastAPI app](https://github.com/gwill1337/petnetflix/blob/dev/core/main.py): `core/main.py`
- [Movie endpoints](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/movies.py): `core/routers/movies.py`
- [Favorite endpoints](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/favorites.py): `core/routers/favorites.py`
- [Comment endpoints](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/comments.py): `core/routers/comments.py`
- [Backend settings](https://github.com/gwill1337/petnetflix/blob/dev/core/config.py): `core/config.py`
- [API schemas](https://github.com/gwill1337/petnetflix/blob/dev/core/schemas.py): `core/schemas.py`

### Identity

- [Password auth](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/auth.py): `core/routers/auth.py`
- [Google OAuth](https://github.com/gwill1337/petnetflix/blob/dev/core/routers/oauth.py): `core/routers/oauth.py`
- [Token security](https://github.com/gwill1337/petnetflix/blob/dev/core/security.py): `core/security.py`

### Persistence

- [SQLAlchemy models](https://github.com/gwill1337/petnetflix/blob/dev/core/db.py): `core/db.py`
- **PostgreSQL**

### Other components

- **Movie viewer**
- **Google identity**
- **Backend API**

## Connections

- Movie viewer → App routes: uses
- App routes → Movie catalog: routes to (evidence: `frontend/src/MainRoutes.tsx`)
- App routes → Movie details: routes to (evidence: `frontend/src/MainRoutes.tsx`)
- Movie catalog → Backend API: fetches movies (evidence: `frontend/src/App.tsx`)
- Movie catalog → Movie cards: renders (evidence: `frontend/src/App.tsx`)
- Movie cards → Favorite control: renders (evidence: `frontend/src/components/MovieCard.tsx`)
- Movie details → Comments UI: renders (evidence: `frontend/src/pages/MovieDetails.tsx`)
- Header and search → Sign-in modal: opens (evidence: `frontend/src/components/Header.tsx`)
- Auth provider → Auth state: provides (evidence: `frontend/src/components/AuthProvider.tsx`)
- Auth hook → Auth state: reads (evidence: `frontend/src/hooks/useAuth.ts`)
- Theme provider → Theme state: provides (evidence: `frontend/src/components/ThemeProvider.tsx`)
- Movie catalog → Debounce hook: imports (evidence: `frontend/src/App.tsx`)
- Backend API → FastAPI app: sends requests
- FastAPI app → Movie endpoints: registers (evidence: `core/main.py`)
- FastAPI app → Favorite endpoints: registers (evidence: `core/main.py`)
- FastAPI app → Comment endpoints: registers (evidence: `core/main.py`)
- FastAPI app → Password auth: registers (evidence: `core/main.py`)
- FastAPI app → Google OAuth: registers (evidence: `core/main.py`)
- Password auth → SQLAlchemy models: queries (evidence: `core/routers/auth.py`)
- Password auth → Token security: issues tokens (evidence: `core/routers/auth.py`)
- Google OAuth → SQLAlchemy models: queries (evidence: `core/routers/oauth.py`)
- Google OAuth → Token security: issues tokens (evidence: `core/routers/oauth.py`)
- Google OAuth → Google identity: authenticates with
- Movie endpoints → SQLAlchemy models: queries (evidence: `core/routers/movies.py`)
- Favorite endpoints → SQLAlchemy models: queries (evidence: `core/routers/favorites.py`)
- Comment endpoints → SQLAlchemy models: queries (evidence: `core/routers/comments.py`)
- SQLAlchemy models → PostgreSQL: persists
- FastAPI app → Backend settings: loads settings (evidence: `core/main.py`)
