# landercor/willpig_studio architecture

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

- Interactive diagram: https://gitdiagram.com/landercor/willpig_studio
- Repository: https://github.com/landercor/willpig_studio

## Overview

1. **Overall shape**  
   Willpig Studio is a server-rendered Node.js application built with Express and modern ESM imports. It follows a classic MVC split: HTTP routes in `src/routes`, request handling in `src/controllers`, persistence models in `src/models`, and EJS views in `src/views`.

2. **Application entry and composition**  
   The startup path is split between `server.js` and `src/app.js`. This usually means `server.js` boots the process, while `src/app.js` assembles middleware, session/auth setup, routes, and static assets into one Express app.

3. **Presentation layer**  
   The UI is rendered on the server with EJS templates, not a SPA. Reusable layout pieces live under `src/views/layouts` and `src/views/partials`. The main user-facing pages cover landing, login/register, library/search, story reading, chapter editing, profiles, and story management.

4. **Static frontend assets**  
   All browser-delivered assets sit under `public/`: modular CSS, page-specific styles, JavaScript, fonts, and images. The CSS structure suggests a componentized design system with shared base/layout/utilities plus view-specific styles for auth, editor, home, profile, and story pages.

5. **Route boundaries**  
   The route layer is separated by feature area: `auth`, `home`, `story`, `chapter`, and `user`. This indicates domain-based request routing rather than a single monolithic router, which helps keep flows isolated by subsystem.

6. **Controller layer and business flow**  
   Controllers implement the application logic for each domain: authentication, story browsing/management, chapter editing, home/library views, and user profile actions. The controllers are the main bridge between form submissions/page requests and the underlying data models.

7. **Data model and persistence**  
   The model layer contains entities named `Cuento`, `Capitulo`, `CuentaUsuario`, `Categoria`, `Etiqueta`, and `Notificacion`. `src/models/index.js` likely wires model associations. The domain is clearly relational: users own or interact with stories, stories contain chapters, and stories can be organized by categories/tags and surfaced through notifications.

8. **Database and backend services**  
   `src/config/db.js` plus the README indicate Supabase as the backend platform, with PostgreSQL as the primary database. There is also a separate test DB config, so the app supports at least one non-production environment. The architecture depends on a hosted relational database rather than local file storage for core content.

9. **Authentication and session management**  
   Auth is a mixed system: local password handling uses `bcrypt`, sessions are managed server-side with `express-session`, and Google login is configured through Passport.js in `src/config/passport.js`. This creates two auth entry paths: traditional email/password and Google OAuth2.

10. **Media upload and storage**  
    Story cover images are handled through `multer` in `src/middlewares/upload.js`, then stored outside the app runtime in Supabase Storage. There are also bucket-creation scripts in `scripts/` and `src/scripts/`, which suggests storage setup is part of the project lifecycle.

11. **Content editing flow**  
    The chapter editor is a notable subsystem: server-side pages for `editor`, `chapter_editor`, and related story edit screens are paired with Quill JS on the client. The flow is likely create/edit chapter content in the browser, submit it to Express, then persist it to the database.

12. **Operational utilities**  
    Environment configuration is managed with `dotenv`, and the presence of `config/test.js` plus `config/testDB.js` suggests environment-specific settings. The repository also contains a `node_modules`-driven Node toolchain and likely uses Nodemon for local development, but the architectural center remains a server-rendered Express app backed by Supabase/Postgres.

Main entry points: [`src/app.js`](https://github.com/landercor/willpig_studio/blob/main/src/app.js) (App setup), [`src/config/db.js`](https://github.com/landercor/willpig_studio/blob/main/src/config/db.js) (DB config), [`src/models/index.js`](https://github.com/landercor/willpig_studio/blob/main/src/models/index.js) (Model index), [`src/views`](https://github.com/landercor/willpig_studio/tree/main/src/views) (Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_server["server.js<br/>bootstrap<br/>[server.js]"]
  node_app["App setup<br/>express app<br/>[app.js]"]
end

subgraph group_web["Web layer"]
  node_routes_auth["Auth routes<br/>router<br/>[auth.routes.js]"]
  node_routes_home["Home routes<br/>router<br/>[home.routes.js]"]
  node_routes_story["Story routes<br/>router<br/>[story.routes.js]"]
  node_routes_chapter["Chapter routes<br/>router<br/>[chapter.routes.js]"]
  node_routes_user["User routes<br/>router<br/>[user.routes.js]"]
  node_ctrl_auth["Auth controller<br/>[auth.controller.js]"]
  node_ctrl_content["Content controllers"]
  node_ctrl_user["User controller<br/>[user.controller.js]"]
  node_views_pages["Pages<br/>ejs views"]
  node_views_layouts["Layouts<br/>ejs partials"]
end

subgraph group_data["Data layer"]
  node_models_index["Model index<br/>orm wiring<br/>[index.js]"]
  node_model_stories["Stories<br/>entity<br/>[Cuento.js]"]
  node_model_chapters["Chapters<br/>entity<br/>[Capitulo.js]"]
  node_model_accounts["Accounts<br/>entity<br/>[CuentaUsuario.js]"]
  node_model_taxonomy["Tags<br/>entity bundle<br/>[Categoria.js]"]
  node_db_config["DB config<br/>database config<br/>[db.js]"]
  node_passport_config["Passport config<br/>auth config<br/>[passport.js]"]
  node_test_config["Test config<br/>env config<br/>[test.js]"]
end

subgraph group_assets["Static assets"]
  node_public_css["Styles<br/>css bundle"]
  node_public_js["Client JS<br/>browser script<br/>[script.js]"]
  node_public_media["Media"]
end

subgraph group_ops["Operations"]
  node_bucket_script["Bucket setup<br/>script<br/>[create-bucket.js]"]
end

node_server -->|"boots"| node_app
node_app -->|"mounts"| node_routes_auth
node_app -->|"mounts"| node_routes_home
node_app -->|"mounts"| node_routes_story
node_app -->|"mounts"| node_routes_chapter
node_app -->|"mounts"| node_routes_user
node_routes_auth -->|"delegates"| node_ctrl_auth
node_routes_home -->|"delegates"| node_ctrl_content
node_routes_story -->|"delegates"| node_ctrl_content
node_routes_chapter -->|"delegates"| node_ctrl_content
node_routes_user -->|"delegates"| node_ctrl_user
node_ctrl_auth -->|"uses"| node_passport_config
node_ctrl_auth -->|"reads/writes"| node_model_accounts
node_ctrl_content -->|"reads/writes"| node_model_stories
node_ctrl_content -->|"reads/writes"| node_model_chapters
node_ctrl_content -->|"reads/writes"| node_model_taxonomy
node_ctrl_user -->|"reads/writes"| node_model_accounts
node_models_index -->|"wires"| node_model_stories
node_models_index -->|"wires"| node_model_chapters
node_models_index -->|"wires"| node_model_accounts
node_models_index -->|"wires"| node_model_taxonomy
node_model_stories -->|"persists to"| node_db_config
node_model_chapters -->|"persists to"| node_db_config
node_model_accounts -->|"persists to"| node_db_config
node_model_taxonomy -->|"persists to"| node_db_config
node_views_pages -->|"styled by"| node_public_css
node_views_pages -->|"enhanced by"| node_public_js
node_views_layouts -->|"composed into"| node_views_pages
node_app -->|"configures"| node_db_config
node_app -->|"renders"| node_views_pages
node_app -->|"serves"| node_public_css
node_app -->|"serves"| node_public_js
node_app -->|"serves"| node_public_media
node_bucket_script -->|"provisions"| node_db_config

click node_server "https://github.com/landercor/willpig_studio/blob/main/server.js"
click node_app "https://github.com/landercor/willpig_studio/blob/main/src/app.js"
click node_routes_auth "https://github.com/landercor/willpig_studio/blob/main/src/routes/auth.routes.js"
click node_routes_home "https://github.com/landercor/willpig_studio/blob/main/src/routes/home.routes.js"
click node_routes_story "https://github.com/landercor/willpig_studio/blob/main/src/routes/story.routes.js"
click node_routes_chapter "https://github.com/landercor/willpig_studio/blob/main/src/routes/chapter.routes.js"
click node_routes_user "https://github.com/landercor/willpig_studio/blob/main/src/routes/user.routes.js"
click node_ctrl_auth "https://github.com/landercor/willpig_studio/blob/main/src/controllers/auth.controller.js"
click node_ctrl_user "https://github.com/landercor/willpig_studio/blob/main/src/controllers/user.controller.js"
click node_views_pages "https://github.com/landercor/willpig_studio/tree/main/src/views"
click node_views_layouts "https://github.com/landercor/willpig_studio/tree/main/src/views/layouts"
click node_models_index "https://github.com/landercor/willpig_studio/blob/main/src/models/index.js"
click node_model_stories "https://github.com/landercor/willpig_studio/blob/main/src/models/Cuento.js"
click node_model_chapters "https://github.com/landercor/willpig_studio/blob/main/src/models/Capitulo.js"
click node_model_accounts "https://github.com/landercor/willpig_studio/blob/main/src/models/CuentaUsuario.js"
click node_model_taxonomy "https://github.com/landercor/willpig_studio/blob/main/src/models/Categoria.js"
click node_db_config "https://github.com/landercor/willpig_studio/blob/main/src/config/db.js"
click node_passport_config "https://github.com/landercor/willpig_studio/blob/main/src/config/passport.js"
click node_test_config "https://github.com/landercor/willpig_studio/blob/main/src/config/test.js"
click node_public_css "https://github.com/landercor/willpig_studio/tree/main/public/css"
click node_public_js "https://github.com/landercor/willpig_studio/blob/main/public/js/script.js"
click node_public_media "https://github.com/landercor/willpig_studio/tree/main/public/fonts"
click node_bucket_script "https://github.com/landercor/willpig_studio/blob/main/scripts/create-bucket.js"

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_server,node_app toneBlue
class node_routes_auth,node_routes_home,node_routes_story,node_routes_chapter,node_routes_user,node_ctrl_auth,node_ctrl_content,node_ctrl_user,node_views_pages,node_views_layouts toneAmber
class node_models_index,node_model_stories,node_model_chapters,node_model_accounts,node_model_taxonomy,node_db_config,node_passport_config,node_test_config toneMint
class node_public_css,node_public_js,node_public_media toneRose
class node_bucket_script toneIndigo
```

## Components

### Runtime

Process bootstrap and Express composition

- [server.js](https://github.com/landercor/willpig_studio/blob/main/server.js): bootstrap · Process entrypoint · `server.js`
- [App setup](https://github.com/landercor/willpig_studio/blob/main/src/app.js): express app · Middleware, sessions, routes, and static assets · `src/app.js`

### Web layer

Routes, controllers, and rendered pages

- [Auth routes](https://github.com/landercor/willpig_studio/blob/main/src/routes/auth.routes.js): router · Login, registration, password recovery, OAuth · `src/routes/auth.routes.js`
- [Home routes](https://github.com/landercor/willpig_studio/blob/main/src/routes/home.routes.js): router · Landing and library/search pages · `src/routes/home.routes.js`
- [Story routes](https://github.com/landercor/willpig_studio/blob/main/src/routes/story.routes.js): router · Story browsing and management · `src/routes/story.routes.js`
- [Chapter routes](https://github.com/landercor/willpig_studio/blob/main/src/routes/chapter.routes.js): router · Chapter editing and reading flows · `src/routes/chapter.routes.js`
- [User routes](https://github.com/landercor/willpig_studio/blob/main/src/routes/user.routes.js): router · Profile and account actions · `src/routes/user.routes.js`
- [Auth controller](https://github.com/landercor/willpig_studio/blob/main/src/controllers/auth.controller.js): controller · Authentication and session logic · `src/controllers/auth.controller.js`
- **Content controllers**: controller · Home, story, and chapter business flow
- [User controller](https://github.com/landercor/willpig_studio/blob/main/src/controllers/user.controller.js): controller · Profile and account management · `src/controllers/user.controller.js`
- [Pages](https://github.com/landercor/willpig_studio/tree/main/src/views): ejs views · Server-rendered screens for landing, auth, reading, and editing · `src/views`
- [Layouts](https://github.com/landercor/willpig_studio/tree/main/src/views/layouts): ejs partials · Shared header, footer, and utilities · `src/views/layouts`

### Data layer

Persistence models and database/auth configuration

- [Model index](https://github.com/landercor/willpig_studio/blob/main/src/models/index.js): orm wiring · Associations and model composition · `src/models/index.js`
- [Stories](https://github.com/landercor/willpig_studio/blob/main/src/models/Cuento.js): entity · Story records · `src/models/Cuento.js`
- [Chapters](https://github.com/landercor/willpig_studio/blob/main/src/models/Capitulo.js): entity · Chapter records · `src/models/Capitulo.js`
- [Accounts](https://github.com/landercor/willpig_studio/blob/main/src/models/CuentaUsuario.js): entity · User accounts · `src/models/CuentaUsuario.js`
- [Tags](https://github.com/landercor/willpig_studio/blob/main/src/models/Categoria.js): entity bundle · Categories, labels, and notifications · `src/models/Categoria.js`
- [DB config](https://github.com/landercor/willpig_studio/blob/main/src/config/db.js): database config · Supabase/PostgreSQL connection settings · `src/config/db.js`
- [Passport config](https://github.com/landercor/willpig_studio/blob/main/src/config/passport.js): auth config · Google login strategy setup · `src/config/passport.js`
- [Test config](https://github.com/landercor/willpig_studio/blob/main/src/config/test.js): env config · Test environment settings · `src/config/test.js`

### Static assets

Browser-delivered styles, scripts, fonts, and images

- [Styles](https://github.com/landercor/willpig_studio/tree/main/public/css): css bundle · Base, layout, component, and view-specific CSS · `public/css`
- [Client JS](https://github.com/landercor/willpig_studio/blob/main/public/js/script.js): browser script · Front-end behavior including editor support · `public/js/script.js`
- [Media](https://github.com/landercor/willpig_studio/tree/main/public/fonts): static media · Fonts and images · `public/fonts`

### Operations

Setup and maintenance scripts

- [Bucket setup](https://github.com/landercor/willpig_studio/blob/main/scripts/create-bucket.js): script · Supabase storage bucket creation · `scripts/create-bucket.js`

## Connections

- server.js → App setup: boots · Server starts the Express application
- App setup → Auth routes: mounts · Registers auth routing
- App setup → Home routes: mounts · Registers home and library routing
- App setup → Story routes: mounts · Registers story routing
- App setup → Chapter routes: mounts · Registers chapter routing
- App setup → User routes: mounts · Registers user routing
- Auth routes → Auth controller: delegates · Routes hand off to auth logic
- Home routes → Content controllers: delegates · Routes hand off to page logic
- Story routes → Content controllers: delegates · Routes hand off to story logic
- Chapter routes → Content controllers: delegates · Routes hand off to chapter logic
- User routes → User controller: delegates · Routes hand off to profile logic
- Auth controller → Passport config: uses · OAuth and session strategy
- Auth controller → Accounts: reads/writes · Authenticates and updates user accounts
- Content controllers → Stories: reads/writes · Story browsing and management
- Content controllers → Chapters: reads/writes · Chapter editing and reading
- Content controllers → Tags: reads/writes · Categorization and notifications
- User controller → Accounts: reads/writes · Profile and account actions
- Model index → Stories: wires · Defines model relations
- Model index → Chapters: wires · Defines model relations
- Model index → Accounts: wires · Defines model relations
- Model index → Tags: wires · Defines model relations
- Stories → DB config: persists to · Stored in PostgreSQL via Supabase
- Chapters → DB config: persists to · Stored in PostgreSQL via Supabase
- Accounts → DB config: persists to · Stored in PostgreSQL via Supabase
- Tags → DB config: persists to · Stored in PostgreSQL via Supabase
- Pages → Styles: styled by · Rendered pages consume shared and page CSS
- Pages → Client JS: enhanced by · Client-side interactions and editor behavior
- Layouts → Pages: composed into · Shared header/footer pieces wrap pages
- App setup → DB config: configures · Loads database connection and environment settings
- App setup → Pages: renders · Express serves EJS pages
- App setup → Styles: serves · Static CSS delivery
- App setup → Client JS: serves · Static JS delivery
- App setup → Media: serves · Static fonts and images
- Bucket setup → DB config: provisions · Creates storage bucket for uploads
