# orebenson/pixel_patches architecture

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

- Interactive diagram: https://gitdiagram.com/orebenson/pixel_patches
- Repository: https://github.com/orebenson/pixel_patches

## Overview

Pixel Patches is a web app for creating and sharing unique 8×8 pixel-art patches, with user accounts and password-reset flows. Users create or browse patches in the frontend; its API services issue HTTP requests to the Express backend, which routes and validates requests, applies authentication, and delegates to patch or user services backed by MongoDB. Account management also includes reset tokens and email delivery. Frontend-to-backend HTTP links are shown as unverified because the excerpts show matching endpoint paths but not deployment or client/server wiring; unsampled page behavior is not inferred.

Main entry points: [`backend/src/api/routes/patch-router.ts`](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/patch-router.ts) (Patch routes), [`backend/src/api/routes/user-router.ts`](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/user-router.ts) (User routes), [`backend/src/api/middleware/auth.ts`](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/middleware/auth.ts) (Authentication and reset flows), [`backend/src/app.ts`](https://github.com/orebenson/pixel_patches/blob/main/backend/src/app.ts) (Express app and sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_patch_ui["Patch editor and gallery<br/>[canvas-scripts.js]"]
  node_patch_page["Patch list UI<br/>[patches-scripts.js]"]
  node_login_ui["Login and registration UI<br/>[login-scripts.js]"]
  node_account_ui["Account UI<br/>[account-scripts.js]"]
  node_password_ui["Password reset UI"]
  node_navbar["Navbar state<br/>[navbar-utils.js]"]
  node_conversion["Pixel conversion"]
  node_patch_api["Patch API client<br/>[patches-service.js]"]
  node_login_api["Account API client<br/>[login-service.js]"]
  node_api_transport["HTTP transport<br/>[api.js]"]
end

subgraph group_routing["Backend routing"]
  node_api_routes["API route mounting<br/>[routes.ts]"]
  node_patch_routes["Patch routes<br/>[patch-router.ts]"]
  node_user_routes["User routes<br/>[user-router.ts]"]
  node_hello_routes["Hello route<br/>[hello-router.ts]"]
  node_request_utils["Request and response helpers<br/>[api-utils.ts]"]
  node_validation["Request validation<br/>[validation.ts]"]
  node_app["Express app and sessions<br/>[app.ts]"]
  node_logger["Logger<br/>[log-utils.ts]"]
end

subgraph group_accounts["Accounts and security"]
  node_auth["Authentication and reset flows<br/>[auth.ts]"]
  node_user_service["User operations<br/>[user-service.ts]"]
  node_token_service["Reset-token operations<br/>[token-service.ts]"]
  node_email["Reset email delivery<br/>[email-utils.ts]"]
  node_user_schema[("User model<br/>[user-schema.ts]")]
  node_token_schema[("Token model<br/>[token-schema.ts]")]
end

subgraph group_domain["Patch domain and storage"]
  node_patch_service["Patch operations<br/>[patch-service.ts]"]
  node_patch_schema[("Patch model<br/>[patch-schema.ts]")]
  node_db_utils["Database utilities<br/>[db-utils.ts]"]
end

node_visitor(("Visitor"))
node_mongo[("MongoDB")]
node_mail_service["Email service"]

node_visitor -.->|"creates or browses"| node_patch_ui
node_visitor -.->|"manages account"| node_login_ui
node_patch_ui -->|"requests patches"| node_patch_api
node_patch_page -->|"requests patches"| node_patch_api
node_patch_ui -->|"converts pixels"| node_conversion
node_login_ui -->|"sends account requests"| node_login_api
node_account_ui -->|"sends account requests"| node_login_api
node_password_ui -.->|"sends reset request"| node_login_api
node_login_ui -->|"updates navigation"| node_navbar
node_account_ui -->|"updates navigation"| node_navbar
node_patch_ui -->|"updates navigation"| node_navbar
node_patch_page -->|"updates navigation"| node_navbar
node_patch_api -->|"uses HTTP"| node_api_transport
node_login_api -->|"uses HTTP"| node_api_transport
node_api_transport -.->|"calls patch endpoints"| node_patch_routes
node_api_transport -.->|"calls user endpoints"| node_user_routes
node_app -->|"mounts routes"| node_api_routes
node_api_routes -->|"mounts router"| node_patch_routes
node_api_routes -->|"mounts router"| node_user_routes
node_api_routes -->|"mounts router"| node_hello_routes
node_patch_routes -->|"checks session"| node_auth
node_patch_routes -->|"validates input"| node_validation
node_patch_routes -->|"dispatches operations"| node_patch_service
node_patch_routes -->|"wraps service requests"| node_request_utils
node_user_routes -->|"handles account flows"| node_auth
node_user_routes -->|"validates input"| node_validation
node_user_routes -->|"registers users"| node_user_service
node_user_routes -->|"wraps service requests"| node_request_utils
node_auth -->|"reads and updates users"| node_user_service
node_auth -->|"manages reset tokens"| node_token_service
node_auth -->|"sends reset email"| node_email
node_user_service -->|"reads and writes"| node_user_schema
node_token_service -->|"reads and writes"| node_token_schema
node_patch_service -->|"reads and writes"| node_patch_schema
node_email -.->|"delivers email"| node_mail_service
node_app -->|"connects and stores sessions"| node_mongo
node_app -->|"cleans collections"| node_db_utils
node_db_utils -.->|"operates on database"| node_mongo
node_app -->|"logs requests"| node_logger

click node_patch_ui "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/canvas-scripts.js"
click node_patch_page "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/patches-scripts.js"
click node_login_ui "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/login-scripts.js"
click node_account_ui "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/account-scripts.js"
click node_password_ui "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/newpassword-scripts.js"
click node_navbar "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/utils/navbar-utils.js"
click node_conversion "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/utils/conversion-utils.js"
click node_patch_api "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/patches-service.js"
click node_login_api "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/login-service.js"
click node_api_transport "https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/api.js"
click node_api_routes "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/routes.ts"
click node_patch_routes "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/patch-router.ts"
click node_user_routes "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/user-router.ts"
click node_hello_routes "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/hello-router.ts"
click node_request_utils "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/api-utils.ts"
click node_validation "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/middleware/validation.ts"
click node_auth "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/middleware/auth.ts"
click node_user_service "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/user-service.ts"
click node_token_service "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/token-service.ts"
click node_email "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/email-utils.ts"
click node_user_schema "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/user-schema.ts"
click node_token_schema "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/token-schema.ts"
click node_patch_service "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/patch-service.ts"
click node_patch_schema "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/patch-schema.ts"
click node_app "https://github.com/orebenson/pixel_patches/blob/main/backend/src/app.ts"
click node_db_utils "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/db-utils.ts"
click node_logger "https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/log-utils.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_patch_ui,node_patch_page,node_login_ui,node_account_ui,node_password_ui,node_navbar,node_conversion,node_patch_api,node_login_api,node_api_transport toneBlue
class node_api_routes,node_patch_routes,node_user_routes,node_hello_routes,node_request_utils,node_validation,node_app,node_logger,node_mongo toneAmber
class node_auth,node_user_service,node_token_service,node_email,node_user_schema,node_token_schema toneMint
class node_patch_service,node_patch_schema,node_db_utils toneRose
class node_visitor,node_mail_service toneIndigo
```

## Components

### Frontend

- [Patch editor and gallery](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/canvas-scripts.js): `frontend/src/js/scripts/canvas-scripts.js`
- [Patch list UI](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/patches-scripts.js): `frontend/src/js/scripts/patches-scripts.js`
- [Login and registration UI](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/login-scripts.js): `frontend/src/js/scripts/login-scripts.js`
- [Account UI](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/account-scripts.js): `frontend/src/js/scripts/account-scripts.js`
- [Password reset UI](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/scripts/newpassword-scripts.js): `frontend/src/js/scripts/newpassword-scripts.js`
- [Navbar state](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/utils/navbar-utils.js): `frontend/src/js/utils/navbar-utils.js`
- [Pixel conversion](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/utils/conversion-utils.js): `frontend/src/js/utils/conversion-utils.js`
- [Patch API client](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/patches-service.js): `frontend/src/js/api/patches-service.js`
- [Account API client](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/login-service.js): `frontend/src/js/api/login-service.js`
- [HTTP transport](https://github.com/orebenson/pixel_patches/blob/main/frontend/src/js/api/api.js): `frontend/src/js/api/api.js`

### Backend routing

- [API route mounting](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/routes.ts): `backend/src/api/routes/routes.ts`
- [Patch routes](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/patch-router.ts): `backend/src/api/routes/patch-router.ts`
- [User routes](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/user-router.ts): `backend/src/api/routes/user-router.ts`
- [Hello route](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/routes/hello-router.ts): `backend/src/api/routes/hello-router.ts`
- [Request and response helpers](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/api-utils.ts): `backend/src/api/utils/api-utils.ts`
- [Request validation](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/middleware/validation.ts): `backend/src/api/middleware/validation.ts`
- [Express app and sessions](https://github.com/orebenson/pixel_patches/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Logger](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/log-utils.ts): `backend/src/api/utils/log-utils.ts`

### Accounts and security

- [Authentication and reset flows](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/middleware/auth.ts): `backend/src/api/middleware/auth.ts`
- [User operations](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/user-service.ts): `backend/src/api/services/user-service.ts`
- [Reset-token operations](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/token-service.ts): `backend/src/api/services/token-service.ts`
- [Reset email delivery](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/email-utils.ts): `backend/src/api/utils/email-utils.ts`
- [User model](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/user-schema.ts): `backend/src/api/schemas/user-schema.ts`
- [Token model](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/token-schema.ts): `backend/src/api/schemas/token-schema.ts`

### Patch domain and storage

- [Patch operations](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/services/patch-service.ts): `backend/src/api/services/patch-service.ts`
- [Patch model](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/schemas/patch-schema.ts): `backend/src/api/schemas/patch-schema.ts`
- [Database utilities](https://github.com/orebenson/pixel_patches/blob/main/backend/src/api/utils/db-utils.ts): `backend/src/api/utils/db-utils.ts`

### Other components

- **Visitor**
- **MongoDB**
- **Email service**

## Connections

- Visitor → Patch editor and gallery: creates or browses (evidence: `README.md`)
- Visitor → Login and registration UI: manages account (evidence: `README.md`)
- Patch editor and gallery → Patch API client: requests patches (evidence: `frontend/src/js/scripts/canvas-scripts.js`)
- Patch list UI → Patch API client: requests patches (evidence: `frontend/src/js/scripts/patches-scripts.js`)
- Patch editor and gallery → Pixel conversion: converts pixels (evidence: `frontend/src/js/scripts/canvas-scripts.js`)
- Login and registration UI → Account API client: sends account requests (evidence: `frontend/src/js/scripts/login-scripts.js`)
- Account UI → Account API client: sends account requests (evidence: `frontend/src/js/scripts/account-scripts.js`)
- Password reset UI → Account API client: sends reset request
- Login and registration UI → Navbar state: updates navigation (evidence: `frontend/src/js/scripts/login-scripts.js`)
- Account UI → Navbar state: updates navigation (evidence: `frontend/src/js/scripts/account-scripts.js`)
- Patch editor and gallery → Navbar state: updates navigation (evidence: `frontend/src/js/scripts/canvas-scripts.js`)
- Patch list UI → Navbar state: updates navigation (evidence: `frontend/src/js/scripts/patches-scripts.js`)
- Patch API client → HTTP transport: uses HTTP (evidence: `frontend/src/js/api/patches-service.js`)
- Account API client → HTTP transport: uses HTTP (evidence: `frontend/src/js/api/login-service.js`)
- HTTP transport → Patch routes: calls patch endpoints
- HTTP transport → User routes: calls user endpoints
- Express app and sessions → API route mounting: mounts routes (evidence: `backend/src/app.ts`)
- API route mounting → Patch routes: mounts router (evidence: `backend/src/api/routes/routes.ts`)
- API route mounting → User routes: mounts router (evidence: `backend/src/api/routes/routes.ts`)
- API route mounting → Hello route: mounts router (evidence: `backend/src/api/routes/routes.ts`)
- Patch routes → Authentication and reset flows: checks session (evidence: `backend/src/api/routes/patch-router.ts`)
- Patch routes → Request validation: validates input (evidence: `backend/src/api/routes/patch-router.ts`)
- Patch routes → Patch operations: dispatches operations (evidence: `backend/src/api/routes/patch-router.ts`)
- Patch routes → Request and response helpers: wraps service requests (evidence: `backend/src/api/routes/patch-router.ts`)
- User routes → Authentication and reset flows: handles account flows (evidence: `backend/src/api/routes/user-router.ts`)
- User routes → Request validation: validates input (evidence: `backend/src/api/routes/user-router.ts`)
- User routes → User operations: registers users (evidence: `backend/src/api/routes/user-router.ts`)
- User routes → Request and response helpers: wraps service requests (evidence: `backend/src/api/routes/user-router.ts`)
- Authentication and reset flows → User operations: reads and updates users (evidence: `backend/src/api/middleware/auth.ts`)
- Authentication and reset flows → Reset-token operations: manages reset tokens (evidence: `backend/src/api/middleware/auth.ts`)
- Authentication and reset flows → Reset email delivery: sends reset email (evidence: `backend/src/api/middleware/auth.ts`)
- User operations → User model: reads and writes (evidence: `backend/src/api/services/user-service.ts`)
- Reset-token operations → Token model: reads and writes (evidence: `backend/src/api/services/token-service.ts`)
- Patch operations → Patch model: reads and writes (evidence: `backend/src/api/services/patch-service.ts`)
- Reset email delivery → Email service: delivers email
- Express app and sessions → MongoDB: connects and stores sessions (evidence: `backend/src/app.ts`)
- Express app and sessions → Database utilities: cleans collections (evidence: `backend/src/app.ts`)
- Database utilities → MongoDB: operates on database
- Express app and sessions → Logger: logs requests (evidence: `backend/src/app.ts`)
