# shreyasuday/reccoflix architecture

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

- Interactive diagram: https://gitdiagram.com/shreyasuday/reccoflix
- Repository: https://github.com/shreyasuday/reccoflix

## Overview

1. **Overall shape**
   ReccoFlix is a server-rendered Node.js/Express application with a classic three-layer flow: browser requests hit Express, Express renders EJS views, and data is pulled from PostgreSQL and the external Kitsu anime API.

2. **Entry point and request routing**
   `index.js` is the application entry point. It is likely where the Express app, middleware, routes, auth setup, static asset serving, and server listen call are composed into one request pipeline.

3. **Database boundary**
   `db.js` centralizes PostgreSQL access. The app persists user accounts, sessions, and anime library state in Postgres rather than in-memory, which is what makes login state and user lists survive restarts.

4. **Schema and maintenance scripts**
   `schema.sql` defines the initial database structure, while `update_schema.js`, `update_schema_safe.js`, and `add_reset_columns.js` are schema-evolution utilities. This suggests the app has had iterative changes to support features like password reset and user-library tracking.

5. **Authentication subsystem**
   The readme and page set indicate two auth paths: local email/password login and Google OAuth. Authentication is session-based, so the browser holds a session cookie and the server uses that session to identify the current user across requests.

6. **User and profile data flow**
   After authentication, the app routes users to profile-oriented pages such as `views/profile.ejs`. That profile area is the main hub for account-specific data, especially the anime library and any user metadata returned from the auth provider or local account record.

7. **Anime discovery and catalog browsing**
   Browse/home/category pages (`home.ejs`, `browse.ejs`, `category.ejs`) present anime lists fetched from Kitsu. These pages are primarily read-only discovery surfaces that transform API data into cards, filters, and category views.

8. **Search and detail pipeline**
   `search.ejs` and `description.ejs` represent a search-to-detail flow: the user searches titles, selects a result, and lands on a detail page with synopsis, ratings, episode counts, and franchise/related metadata from Kitsu.

9. **Personal library subsystem**
   The key application-specific feature is the tracked anime library. Users can classify titles into statuses like Watched, Watching, Planned, On Hold, and Dropped, and then update or remove entries later from the profile/library UI.

10. **Frontend assets**
   `public/js/main.js` provides client-side interactivity, likely for actions such as search behavior, status selection, and UI updates without a full page refresh. `public/styles/main.css`, fonts, and images are the static presentation layer shared across all templates.

11. **Template composition**
   The app uses EJS partials (`views/partials/header.ejs`, `footer.ejs`) to share layout chrome across pages. This keeps navigation, auth links, and footer/legal content consistent while each page template focuses on its own data binding.

12. **Supporting pages and legal flow**
   `about.ejs`, `privacy.ejs`, `terms.ejs`, `login.ejs`, `register.ejs`, `forgot-password.ejs`, and `reset-password.ejs` show that the application includes both onboarding and account-recovery flows, alongside informational/legal pages. These are separate from the discovery/library paths but share the same rendering and session/auth infrastructure.

Main entry points: [`index.js`](https://github.com/shreyasuday/reccoflix/blob/main/index.js) (Entry), [`views/profile.ejs`](https://github.com/shreyasuday/reccoflix/blob/main/views/profile.ejs) (Profile), [`db.js`](https://github.com/shreyasuday/reccoflix/blob/main/db.js) (Postgres), [`views/partials/header.ejs`](https://github.com/shreyasuday/reccoflix/blob/main/views/partials/header.ejs) (Layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_index["Entry<br/>express app<br/>[index.js]"]
  node_auth(("Auth<br/>session login"))
  node_routes["Pages<br/>route layer"]
end

subgraph group_data["Data"]
  node_db[("Postgres<br/>database access<br/>[db.js]")]
  node_schema["Schema<br/>sql init<br/>[schema.sql]"]
  node_migrations["Migrations<br/>schema updates<br/>[update_schema.js]"]
  node_kitsu{{"Kitsu API<br/>external api"}}
end

subgraph group_ui["UI"]
  node_layout["Layout<br/>ejs partials<br/>[header.ejs]"]
  node_client["Client JS<br/>browser script<br/>[main.js]"]
  node_styles["Styles<br/>css assets<br/>[main.css]"]
end

subgraph group_flows["User Flows"]
  node_home["Home<br/>discovery page<br/>[home.ejs]"]
  node_browse["Browse<br/>catalog page<br/>[browse.ejs]"]
  node_category["Category<br/>catalog page<br/>[category.ejs]"]
  node_search["Search<br/>query page<br/>[search.ejs]"]
  node_detail["Detail<br/>anime page<br/>[description.ejs]"]
  node_profile["Profile<br/>library page<br/>[profile.ejs]"]
  node_login["Login<br/>auth page<br/>[login.ejs]"]
  node_register["Register<br/>auth page<br/>[register.ejs]"]
  node_recover["Recovery<br/>auth page"]
  node_legal["Legal<br/>content pages<br/>[about.ejs]"]
end

node_index -->|"initializes"| node_auth
node_index -->|"serves"| node_routes
node_index -->|"connects"| node_db
node_index -->|"renders"| node_layout
node_routes -->|"renders"| node_home
node_routes -->|"renders"| node_browse
node_routes -->|"renders"| node_category
node_routes -->|"renders"| node_search
node_routes -->|"renders"| node_detail
node_routes -->|"renders"| node_profile
node_routes -->|"renders"| node_login
node_routes -->|"renders"| node_register
node_routes -->|"renders"| node_recover
node_routes -->|"renders"| node_legal
node_profile -->|"reads/writes"| node_db
node_profile -->|"enriches"| node_kitsu
node_home -->|"fetches"| node_kitsu
node_browse -->|"fetches"| node_kitsu
node_category -->|"fetches"| node_kitsu
node_search -->|"queries"| node_kitsu
node_detail -->|"fetches"| node_kitsu
node_auth -->|"stores"| node_db
node_schema -->|"defines"| node_db
node_migrations -->|"evolves"| node_schema
node_layout -->|"loads"| node_styles
node_layout -->|"boots"| node_client
node_client -->|"enhances"| node_profile
node_client -->|"enhances"| node_search

click node_index "https://github.com/shreyasuday/reccoflix/blob/main/index.js"
click node_db "https://github.com/shreyasuday/reccoflix/blob/main/db.js"
click node_schema "https://github.com/shreyasuday/reccoflix/blob/main/schema.sql"
click node_migrations "https://github.com/shreyasuday/reccoflix/blob/main/update_schema.js"
click node_home "https://github.com/shreyasuday/reccoflix/blob/main/views/home.ejs"
click node_browse "https://github.com/shreyasuday/reccoflix/blob/main/views/browse.ejs"
click node_category "https://github.com/shreyasuday/reccoflix/blob/main/views/category.ejs"
click node_search "https://github.com/shreyasuday/reccoflix/blob/main/views/search.ejs"
click node_detail "https://github.com/shreyasuday/reccoflix/blob/main/views/description.ejs"
click node_profile "https://github.com/shreyasuday/reccoflix/blob/main/views/profile.ejs"
click node_login "https://github.com/shreyasuday/reccoflix/blob/main/views/login.ejs"
click node_register "https://github.com/shreyasuday/reccoflix/blob/main/views/register.ejs"
click node_recover "https://github.com/shreyasuday/reccoflix/blob/main/views/forgot-password.ejs"
click node_legal "https://github.com/shreyasuday/reccoflix/blob/main/views/about.ejs"
click node_layout "https://github.com/shreyasuday/reccoflix/blob/main/views/partials/header.ejs"
click node_client "https://github.com/shreyasuday/reccoflix/blob/main/public/js/main.js"
click node_styles "https://github.com/shreyasuday/reccoflix/blob/main/public/styles/main.css"

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_index,node_auth,node_routes toneBlue
class node_db,node_schema,node_migrations,node_kitsu toneAmber
class node_layout,node_client,node_styles toneMint
class node_home,node_browse,node_category,node_search,node_detail,node_profile,node_login,node_register,node_recover,node_legal toneRose
```

## Components

### Application

Runtime request handling and orchestration

- [Entry](https://github.com/shreyasuday/reccoflix/blob/main/index.js): express app · Application bootstrap and request pipeline · `index.js`
- **Auth**: session login · Local login, Google OAuth, and session handling
- **Pages**: route layer · Page routing and server-side rendering coordination

### Data

Persistence and external content sources

- [Postgres](https://github.com/shreyasuday/reccoflix/blob/main/db.js): database access · Central PostgreSQL connection and queries · `db.js`
- [Schema](https://github.com/shreyasuday/reccoflix/blob/main/schema.sql): sql init · Base database schema definition · `schema.sql`
- [Migrations](https://github.com/shreyasuday/reccoflix/blob/main/update_schema.js): schema updates · Database evolution scripts for new columns and fixes · `update_schema.js`
- **Kitsu API**: external api · Anime catalog and metadata source

### UI

Rendered templates and client assets

- [Layout](https://github.com/shreyasuday/reccoflix/blob/main/views/partials/header.ejs): ejs partials · Shared header and footer chrome · `views/partials/header.ejs`
- [Client JS](https://github.com/shreyasuday/reccoflix/blob/main/public/js/main.js): browser script · Front-end interactivity and UI behavior · `public/js/main.js`
- [Styles](https://github.com/shreyasuday/reccoflix/blob/main/public/styles/main.css): css assets · Shared visual styling and fonts · `public/styles/main.css`

### User Flows

Main page-level experiences

- [Home](https://github.com/shreyasuday/reccoflix/blob/main/views/home.ejs): discovery page · Landing page for featured anime · `views/home.ejs`
- [Browse](https://github.com/shreyasuday/reccoflix/blob/main/views/browse.ejs): catalog page · Broad anime browsing and filtering · `views/browse.ejs`
- [Category](https://github.com/shreyasuday/reccoflix/blob/main/views/category.ejs): catalog page · Genre or category-based listing · `views/category.ejs`
- [Search](https://github.com/shreyasuday/reccoflix/blob/main/views/search.ejs): query page · Title search and result selection · `views/search.ejs`
- [Detail](https://github.com/shreyasuday/reccoflix/blob/main/views/description.ejs): anime page · Anime synopsis, ratings, and related metadata · `views/description.ejs`
- [Profile](https://github.com/shreyasuday/reccoflix/blob/main/views/profile.ejs): library page · Account hub and tracked anime library · `views/profile.ejs`
- [Login](https://github.com/shreyasuday/reccoflix/blob/main/views/login.ejs): auth page · Sign-in form for local and OAuth users · `views/login.ejs`
- [Register](https://github.com/shreyasuday/reccoflix/blob/main/views/register.ejs): auth page · Account creation flow · `views/register.ejs`
- [Recovery](https://github.com/shreyasuday/reccoflix/blob/main/views/forgot-password.ejs): auth page · Password reset request and reset pages · `views/forgot-password.ejs`
- [Legal](https://github.com/shreyasuday/reccoflix/blob/main/views/about.ejs): content pages · About, privacy, and terms pages · `views/about.ejs`

## Connections

- Entry → Auth: initializes · Wires authentication and session flow into the app
- Entry → Pages: serves · Main server entry dispatches page requests
- Entry → Postgres: connects · Uses PostgreSQL for persisted state
- Entry → Layout: renders · All pages share common EJS chrome
- Pages → Home: renders · Serves the landing experience
- Pages → Browse: renders · Serves catalog browsing
- Pages → Category: renders · Serves category views
- Pages → Search: renders · Serves search results
- Pages → Detail: renders · Serves title detail pages
- Pages → Profile: renders · Serves the authenticated account hub
- Pages → Login: renders · Serves sign-in form
- Pages → Register: renders · Serves sign-up form
- Pages → Recovery: renders · Serves reset and recovery pages
- Pages → Legal: renders · Serves informational and policy pages
- Profile → Postgres: reads/writes · Persists user accounts, sessions, and library entries
- Profile → Kitsu API: enriches · Combines saved library data with anime metadata
- Home → Kitsu API: fetches · Loads featured anime lists
- Browse → Kitsu API: fetches · Loads browseable catalog data
- Category → Kitsu API: fetches · Loads category-filtered catalog data
- Search → Kitsu API: queries · Searches anime titles and returns matches
- Detail → Kitsu API: fetches · Loads synopsis, ratings, and related titles
- Auth → Postgres: stores · Persists users and session-linked state
- Schema → Postgres: defines · Initial database structure for the app
- Migrations → Schema: evolves · Updates the database shape over time
- Layout → Styles: loads · Shared templates are styled by the global stylesheet
- Layout → Client JS: boots · Shared chrome includes client-side behavior
- Client JS → Profile: enhances · Supports interactive library actions on the client
- Client JS → Search: enhances · Supports search interaction and UI updates
