# omerdlw/guffin architecture

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

- Interactive diagram: https://gitdiagram.com/omerdlw/guffin
- Repository: https://github.com/omerdlw/guffin

## Overview

Guffin is a film-and-TV diary: users discover catalogue titles, inspect details, then record watches, ratings, reviews, lists, and show progress; profiles and activity expose that history socially. The graph groups route-facing product features, catalogue integrations, identity and persistence, and the shared interface. Several feature branches are documented in the README or apparent from the tree, but their internal calls were not sampled; those links are omitted rather than inferred. Database access is scoped by viewer identity under Postgres RLS, and TMDB supplies catalogue data.

Main entry points: [`src/app`](https://github.com/omerdlw/guffin/tree/main/src/app) (App routes), [`src/lib/tmdb/server.ts`](https://github.com/omerdlw/guffin/blob/main/src/lib/tmdb/server.ts) (TMDB client), [`src/features/search/server.ts`](https://github.com/omerdlw/guffin/blob/main/src/features/search/server.ts) (Search), [`src/features/tv/server.ts`](https://github.com/omerdlw/guffin/blob/main/src/features/tv/server.ts) (Show tracking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["Product features"]
  node_app["App routes"]
  node_home["Home feed<br/>[server.ts]"]
  node_search["Search<br/>[server.ts]"]
  node_film["Film details<br/>[movie.ts]"]
  node_tv["Show tracking<br/>[server.ts]"]
  node_people["People<br/>[credits.ts]"]
  node_profiles["Profiles and diary"]
  node_reviews["Reviews<br/>[server.ts]"]
  node_lists["Lists<br/>[server.ts]"]
  node_spotlights["Spotlights<br/>[server.ts]"]
  node_social["Social"]
end

subgraph group_catalogue["Catalogue services"]
  node_tmdb["TMDB client<br/>[server.ts]"]
  node_tmdbservice["TMDB"]
  node_quality["Catalogue quality<br/>[quality.ts]"]
end

subgraph group_identity["Identity and data"]
  node_auth["Auth and sessions<br/>[server.ts]"]
  node_authfeature["Auth workflows<br/>[server.ts]"]
  node_database[("Postgres")]
  node_dbaccess["Scoped DB access<br/>[client.ts]"]
  node_schema["Domain schema<br/>[schema.ts]"]
end

subgraph group_interface["Interface system"]
  node_design["Design system"]
  node_motion["Motion engine<br/>[engine.ts]"]
end

node_viewer(("Viewer"))

node_viewer -->|"uses routes"| node_app
node_app -->|"composes"| node_home
node_app -->|"composes"| node_search
node_app -->|"composes"| node_film
node_app -->|"composes"| node_tv
node_app -->|"composes"| node_profiles
node_app -->|"composes"| node_reviews
node_app -->|"composes"| node_lists
node_app -->|"composes"| node_spotlights
node_app -->|"composes"| node_people
node_app -->|"routes"| node_social
node_home -->|"reads identity"| node_authfeature
node_home -->|"reads activity"| node_database
node_search -->|"searches titles"| node_tmdb
node_search -->|"filters results"| node_quality
node_search -->|"queries community"| node_database
node_tv -->|"loads episodes"| node_tmdb
node_tv -->|"checks airing"| node_quality
node_tv -->|"reads progress"| node_database
node_reviews -->|"reads and writes"| node_database
node_lists -->|"reads and writes"| node_database
node_spotlights -->|"loads catalogue"| node_tmdb
node_spotlights -->|"filters titles"| node_quality
node_authfeature -->|"configures sessions"| node_auth
node_auth -->|"stores auth data"| node_database
node_authfeature -->|"creates viewer scope"| node_dbaccess
node_dbaccess -->|"scopes transactions"| node_database
node_dbaccess -->|"binds schema"| node_schema
node_tmdb -->|"fetches catalogue"| node_tmdbservice
node_tmdb -.->|"uses shared rules"| node_quality
node_app -->|"renders with"| node_design
node_app -->|"uses choreography"| node_motion

click node_app "https://github.com/omerdlw/guffin/tree/main/src/app"
click node_home "https://github.com/omerdlw/guffin/blob/main/src/features/home/server.ts"
click node_search "https://github.com/omerdlw/guffin/blob/main/src/features/search/server.ts"
click node_film "https://github.com/omerdlw/guffin/blob/main/src/features/movie/movie.ts"
click node_tv "https://github.com/omerdlw/guffin/blob/main/src/features/tv/server.ts"
click node_people "https://github.com/omerdlw/guffin/blob/main/src/features/person/credits.ts"
click node_profiles "https://github.com/omerdlw/guffin/tree/main/src/features/profile"
click node_reviews "https://github.com/omerdlw/guffin/blob/main/src/features/reviews/server.ts"
click node_lists "https://github.com/omerdlw/guffin/blob/main/src/features/lists/server.ts"
click node_spotlights "https://github.com/omerdlw/guffin/blob/main/src/features/spotlights/server.ts"
click node_social "https://github.com/omerdlw/guffin/tree/main/src/features/social"
click node_auth "https://github.com/omerdlw/guffin/blob/main/src/lib/auth/server.ts"
click node_authfeature "https://github.com/omerdlw/guffin/blob/main/src/features/auth/server.ts"
click node_dbaccess "https://github.com/omerdlw/guffin/blob/main/src/lib/db/client.ts"
click node_schema "https://github.com/omerdlw/guffin/blob/main/src/lib/db/schema.ts"
click node_tmdb "https://github.com/omerdlw/guffin/blob/main/src/lib/tmdb/server.ts"
click node_quality "https://github.com/omerdlw/guffin/blob/main/src/features/catalog/quality.ts"
click node_design "https://github.com/omerdlw/guffin/tree/main/src/design"
click node_motion "https://github.com/omerdlw/guffin/blob/main/src/motion/engine.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,node_home,node_search,node_film,node_tv,node_people,node_profiles,node_reviews,node_lists,node_spotlights,node_social,node_viewer toneBlue
class node_tmdb,node_tmdbservice,node_quality toneAmber
class node_auth,node_authfeature,node_database,node_dbaccess,node_schema toneMint
class node_design,node_motion toneRose
```

## Components

### Product features

- [App routes](https://github.com/omerdlw/guffin/tree/main/src/app): `src/app`
- [Home feed](https://github.com/omerdlw/guffin/blob/main/src/features/home/server.ts): `src/features/home/server.ts`
- [Search](https://github.com/omerdlw/guffin/blob/main/src/features/search/server.ts): `src/features/search/server.ts`
- [Film details](https://github.com/omerdlw/guffin/blob/main/src/features/movie/movie.ts): `src/features/movie/movie.ts`
- [Show tracking](https://github.com/omerdlw/guffin/blob/main/src/features/tv/server.ts): `src/features/tv/server.ts`
- [People](https://github.com/omerdlw/guffin/blob/main/src/features/person/credits.ts): `src/features/person/credits.ts`
- [Profiles and diary](https://github.com/omerdlw/guffin/tree/main/src/features/profile): `src/features/profile`
- [Reviews](https://github.com/omerdlw/guffin/blob/main/src/features/reviews/server.ts): `src/features/reviews/server.ts`
- [Lists](https://github.com/omerdlw/guffin/blob/main/src/features/lists/server.ts): `src/features/lists/server.ts`
- [Spotlights](https://github.com/omerdlw/guffin/blob/main/src/features/spotlights/server.ts): `src/features/spotlights/server.ts`
- [Social](https://github.com/omerdlw/guffin/tree/main/src/features/social): `src/features/social`

### Catalogue services

- [TMDB client](https://github.com/omerdlw/guffin/blob/main/src/lib/tmdb/server.ts): `src/lib/tmdb/server.ts`
- **TMDB**
- [Catalogue quality](https://github.com/omerdlw/guffin/blob/main/src/features/catalog/quality.ts): `src/features/catalog/quality.ts`

### Identity and data

- [Auth and sessions](https://github.com/omerdlw/guffin/blob/main/src/lib/auth/server.ts): `src/lib/auth/server.ts`
- [Auth workflows](https://github.com/omerdlw/guffin/blob/main/src/features/auth/server.ts): `src/features/auth/server.ts`
- **Postgres**
- [Scoped DB access](https://github.com/omerdlw/guffin/blob/main/src/lib/db/client.ts): `src/lib/db/client.ts`
- [Domain schema](https://github.com/omerdlw/guffin/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Interface system

- [Design system](https://github.com/omerdlw/guffin/tree/main/src/design): `src/design`
- [Motion engine](https://github.com/omerdlw/guffin/blob/main/src/motion/engine.ts): `src/motion/engine.ts`

### Other components

- **Viewer**

## Connections

- Viewer → App routes: uses routes
- App routes → Home feed: composes
- App routes → Search: composes (evidence: `src/app/api/search/route.ts`)
- App routes → Film details: composes (evidence: `src/app/api/backdrop/route.ts`)
- App routes → Show tracking: composes (evidence: `src/app/api/cron/shows/route.ts`)
- App routes → Profiles and diary: composes
- App routes → Reviews: composes
- App routes → Lists: composes
- App routes → Spotlights: composes
- App routes → People: composes (evidence: `src/app/api/backdrop/route.ts`)
- App routes → Social: routes (evidence: `src/app/api/social/follows/route.ts`)
- Home feed → Auth workflows: reads identity (evidence: `src/features/home/server.ts`)
- Home feed → Postgres: reads activity (evidence: `src/features/home/server.ts`)
- Search → TMDB client: searches titles (evidence: `src/features/search/server.ts`)
- Search → Catalogue quality: filters results (evidence: `src/features/search/server.ts`)
- Search → Postgres: queries community (evidence: `src/features/search/server.ts`)
- Show tracking → TMDB client: loads episodes (evidence: `src/features/tv/server.ts`)
- Show tracking → Catalogue quality: checks airing (evidence: `src/features/tv/server.ts`)
- Show tracking → Postgres: reads progress (evidence: `src/features/tv/server.ts`)
- Reviews → Postgres: reads and writes (evidence: `src/features/reviews/server.ts`)
- Lists → Postgres: reads and writes (evidence: `src/features/lists/server.ts`)
- Spotlights → TMDB client: loads catalogue (evidence: `src/features/spotlights/server.ts`)
- Spotlights → Catalogue quality: filters titles (evidence: `src/features/spotlights/server.ts`)
- Auth workflows → Auth and sessions: configures sessions (evidence: `src/features/auth/server.ts`)
- Auth and sessions → Postgres: stores auth data (evidence: `src/lib/auth/server.ts`)
- Auth workflows → Scoped DB access: creates viewer scope (evidence: `src/features/auth/server.ts`)
- Scoped DB access → Postgres: scopes transactions (evidence: `src/lib/db/client.ts`)
- Scoped DB access → Domain schema: binds schema (evidence: `src/lib/db/client.ts`)
- TMDB client → TMDB: fetches catalogue (evidence: `src/lib/tmdb/server.ts`)
- TMDB client → Catalogue quality: uses shared rules
- App routes → Design system: renders with
- App routes → Motion engine: uses choreography
