# debguin452/yourserver architecture

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

- Interactive diagram: https://gitdiagram.com/debguin452/yourserver
- Repository: https://github.com/debguin452/yourserver

## Overview

yourserver is a configurable Cloudflare Workers server kit. Requests enter the Worker fetch handler, pass through a small router and configured middleware, then reach independently mounted feature routes. Those features cover health and a live landing page, API and WebSocket examples, authentication, key-value and SQL data, files, webhooks, URL shortening, QR codes, and optional Firestore-backed notes. Route-to-helper links follow source-index references; storage capabilities and bindings are documented in the README. Some route implementations and D1 helper details were not excerpted, so those links are documented rather than inferred from unseen calls.

Main entry points: [`src/index.js`](https://github.com/debguin452/yourserver/blob/main/src/index.js) (Worker entry), [`src/lib/kv.js`](https://github.com/debguin452/yourserver/blob/main/src/lib/kv.js) (KV helpers), [`src/routes/notes.js`](https://github.com/debguin452/yourserver/blob/main/src/routes/notes.js) (SQL notes), [`src/routes/firebase-notes.js`](https://github.com/debguin452/yourserver/blob/main/src/routes/firebase-notes.js) (Firestore notes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Request runtime"]
  node_worker["Worker entry<br/>[index.js]"]
  node_router["Router<br/>[router.js]"]
  node_middleware["Request middleware<br/>[middleware.js]"]
  node_config["Feature config<br/>[config.js]"]
end

subgraph group_web["Web features"]
  node_page["Landing page<br/>[page.js]"]
  node_health["Health check<br/>[health.js]"]
  node_api["Example API<br/>[api.js]"]
  node_websocket["WebSocket echo<br/>[ws.js]"]
  node_qr["QR generator<br/>[qr.js]"]
end

subgraph group_data["Data features"]
  node_auth["Login sessions<br/>[auth.js]"]
  node_kvstore["Key-value store<br/>[kv-store.js]"]
  node_notes["SQL notes<br/>[notes.js]"]
  node_shorten["URL shortener<br/>[shorten.js]"]
  node_webhook["Webhook log<br/>[webhook.js]"]
  node_firebase_notes["Firestore notes<br/>[firebase-notes.js]"]
  node_files["File transfer<br/>[files.js]"]
end

subgraph group_integrations["Storage and services"]
  node_kv_helper["KV helpers<br/>[kv.js]"]
  node_db_helper["D1 helper<br/>[db.js]"]
  node_storage_helper["R2 helpers<br/>[storage.js]"]
  node_firebase_helper["Firestore client<br/>[firebase.js]"]
  node_kv[("Workers KV")]
  node_d1[("Cloudflare D1")]
  node_r2[("Cloudflare R2")]
  node_firestore[("Firebase Firestore")]
  node_google_oauth["Google OAuth"]
end

node_clients(("HTTP clients"))

node_clients -->|"sends requests"| node_worker
node_worker -->|"handles requests"| node_router
node_worker -->|"registers middleware"| node_middleware
node_worker -->|"reads settings"| node_config
node_worker -->|"mounts routes"| node_page
node_worker -->|"mounts routes"| node_health
node_worker -->|"mounts routes"| node_api
node_worker -->|"mounts routes"| node_websocket
node_worker -->|"mounts routes"| node_qr
node_worker -->|"mounts routes"| node_auth
node_worker -->|"mounts routes"| node_kvstore
node_worker -->|"mounts routes"| node_notes
node_worker -->|"mounts routes"| node_shorten
node_worker -->|"mounts routes"| node_webhook
node_worker -->|"mounts routes"| node_firebase_notes
node_worker -->|"mounts routes"| node_files
node_router -->|"runs chain"| node_middleware
node_middleware -->|"reads and writes limits"| node_kv
node_auth -->|"uses"| node_kv_helper
node_kvstore -->|"uses"| node_kv_helper
node_api -->|"uses"| node_kv_helper
node_shorten -->|"uses"| node_kv_helper
node_webhook -->|"uses"| node_kv_helper
node_kv_helper -->|"reads and writes"| node_kv
node_notes -->|"uses"| node_db_helper
node_notes -->|"persists notes"| node_d1
node_files -->|"uses"| node_storage_helper
node_files -->|"stores files"| node_r2
node_firebase_notes -->|"uses"| node_firebase_helper
node_firebase_notes -->|"reads and writes notes"| node_firestore
node_firebase_helper -->|"exchanges JWT"| node_google_oauth
node_firebase_helper -->|"calls REST API"| node_firestore

click node_worker "https://github.com/debguin452/yourserver/blob/main/src/index.js"
click node_router "https://github.com/debguin452/yourserver/blob/main/src/lib/router.js"
click node_middleware "https://github.com/debguin452/yourserver/blob/main/src/lib/middleware.js"
click node_config "https://github.com/debguin452/yourserver/blob/main/src/config.js"
click node_page "https://github.com/debguin452/yourserver/blob/main/src/routes/page.js"
click node_health "https://github.com/debguin452/yourserver/blob/main/src/routes/health.js"
click node_api "https://github.com/debguin452/yourserver/blob/main/src/routes/api.js"
click node_websocket "https://github.com/debguin452/yourserver/blob/main/src/routes/ws.js"
click node_qr "https://github.com/debguin452/yourserver/blob/main/src/routes/qr.js"
click node_auth "https://github.com/debguin452/yourserver/blob/main/src/routes/auth.js"
click node_kvstore "https://github.com/debguin452/yourserver/blob/main/src/routes/kv-store.js"
click node_notes "https://github.com/debguin452/yourserver/blob/main/src/routes/notes.js"
click node_shorten "https://github.com/debguin452/yourserver/blob/main/src/routes/shorten.js"
click node_webhook "https://github.com/debguin452/yourserver/blob/main/src/routes/webhook.js"
click node_firebase_notes "https://github.com/debguin452/yourserver/blob/main/src/routes/firebase-notes.js"
click node_files "https://github.com/debguin452/yourserver/blob/main/src/routes/files.js"
click node_kv_helper "https://github.com/debguin452/yourserver/blob/main/src/lib/kv.js"
click node_db_helper "https://github.com/debguin452/yourserver/blob/main/src/lib/db.js"
click node_storage_helper "https://github.com/debguin452/yourserver/blob/main/src/lib/storage.js"
click node_firebase_helper "https://github.com/debguin452/yourserver/blob/main/src/lib/firebase.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_worker,node_router,node_middleware,node_config,node_clients toneBlue
class node_page,node_health,node_api,node_websocket,node_qr toneAmber
class node_auth,node_kvstore,node_notes,node_shorten,node_webhook,node_firebase_notes,node_files toneMint
class node_kv_helper,node_db_helper,node_storage_helper,node_firebase_helper,node_kv,node_d1,node_r2,node_firestore,node_google_oauth toneRose
```

## Components

### Request runtime

- [Worker entry](https://github.com/debguin452/yourserver/blob/main/src/index.js): `src/index.js`
- [Router](https://github.com/debguin452/yourserver/blob/main/src/lib/router.js): `src/lib/router.js`
- [Request middleware](https://github.com/debguin452/yourserver/blob/main/src/lib/middleware.js): `src/lib/middleware.js`
- [Feature config](https://github.com/debguin452/yourserver/blob/main/src/config.js): `src/config.js`

### Web features

- [Landing page](https://github.com/debguin452/yourserver/blob/main/src/routes/page.js): `src/routes/page.js`
- [Health check](https://github.com/debguin452/yourserver/blob/main/src/routes/health.js): `src/routes/health.js`
- [Example API](https://github.com/debguin452/yourserver/blob/main/src/routes/api.js): `src/routes/api.js`
- [WebSocket echo](https://github.com/debguin452/yourserver/blob/main/src/routes/ws.js): `src/routes/ws.js`
- [QR generator](https://github.com/debguin452/yourserver/blob/main/src/routes/qr.js): `src/routes/qr.js`

### Data features

- [Login sessions](https://github.com/debguin452/yourserver/blob/main/src/routes/auth.js): `src/routes/auth.js`
- [Key-value store](https://github.com/debguin452/yourserver/blob/main/src/routes/kv-store.js): `src/routes/kv-store.js`
- [SQL notes](https://github.com/debguin452/yourserver/blob/main/src/routes/notes.js): `src/routes/notes.js`
- [URL shortener](https://github.com/debguin452/yourserver/blob/main/src/routes/shorten.js): `src/routes/shorten.js`
- [Webhook log](https://github.com/debguin452/yourserver/blob/main/src/routes/webhook.js): `src/routes/webhook.js`
- [Firestore notes](https://github.com/debguin452/yourserver/blob/main/src/routes/firebase-notes.js): `src/routes/firebase-notes.js`
- [File transfer](https://github.com/debguin452/yourserver/blob/main/src/routes/files.js): `src/routes/files.js`

### Storage and services

- [KV helpers](https://github.com/debguin452/yourserver/blob/main/src/lib/kv.js): `src/lib/kv.js`
- [D1 helper](https://github.com/debguin452/yourserver/blob/main/src/lib/db.js): `src/lib/db.js`
- [R2 helpers](https://github.com/debguin452/yourserver/blob/main/src/lib/storage.js): `src/lib/storage.js`
- [Firestore client](https://github.com/debguin452/yourserver/blob/main/src/lib/firebase.js): `src/lib/firebase.js`
- **Workers KV**
- **Cloudflare D1**
- **Cloudflare R2**
- **Firebase Firestore**
- **Google OAuth**

### Other components

- **HTTP clients**

## Connections

- HTTP clients → Worker entry: sends requests (evidence: `README.md`)
- Worker entry → Router: handles requests (evidence: `src/index.js`)
- Worker entry → Request middleware: registers middleware (evidence: `src/index.js`)
- Worker entry → Feature config: reads settings (evidence: `src/index.js`)
- Worker entry → Landing page: mounts routes (evidence: `src/index.js`)
- Worker entry → Health check: mounts routes (evidence: `src/index.js`)
- Worker entry → Example API: mounts routes (evidence: `src/index.js`)
- Worker entry → WebSocket echo: mounts routes (evidence: `src/index.js`)
- Worker entry → QR generator: mounts routes (evidence: `src/index.js`)
- Worker entry → Login sessions: mounts routes (evidence: `src/index.js`)
- Worker entry → Key-value store: mounts routes (evidence: `src/index.js`)
- Worker entry → SQL notes: mounts routes (evidence: `src/index.js`)
- Worker entry → URL shortener: mounts routes (evidence: `src/index.js`)
- Worker entry → Webhook log: mounts routes (evidence: `src/index.js`)
- Worker entry → Firestore notes: mounts routes (evidence: `src/index.js`)
- Worker entry → File transfer: mounts routes (evidence: `src/index.js`)
- Router → Request middleware: runs chain (evidence: `src/lib/router.js`)
- Request middleware → Workers KV: reads and writes limits (evidence: `src/lib/middleware.js`)
- Login sessions → KV helpers: uses (evidence: `src/routes/auth.js`)
- Key-value store → KV helpers: uses (evidence: `src/routes/kv-store.js`)
- Example API → KV helpers: uses (evidence: `src/routes/api.js`)
- URL shortener → KV helpers: uses (evidence: `src/routes/shorten.js`)
- Webhook log → KV helpers: uses (evidence: `src/routes/webhook.js`)
- KV helpers → Workers KV: reads and writes (evidence: `src/lib/kv.js`)
- SQL notes → D1 helper: uses (evidence: `src/routes/notes.js`)
- SQL notes → Cloudflare D1: persists notes (evidence: `README.md`)
- File transfer → R2 helpers: uses (evidence: `src/routes/files.js`)
- File transfer → Cloudflare R2: stores files (evidence: `README.md`)
- Firestore notes → Firestore client: uses (evidence: `src/routes/firebase-notes.js`)
- Firestore notes → Firebase Firestore: reads and writes notes (evidence: `README.md`)
- Firestore client → Google OAuth: exchanges JWT (evidence: `src/lib/firebase.js`)
- Firestore client → Firebase Firestore: calls REST API (evidence: `src/lib/firebase.js`)