# nntfb777/99okcode-backend architecture

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

- Interactive diagram: https://gitdiagram.com/nntfb777/99okcode-backend
- Repository: https://github.com/nntfb777/99okcode-backend

## Overview

This is a multi-site code-redemption backend built with Hono. A client submits a code and account name; the server verifies Turnstile, checks eligibility and remaining uses in the selected site database, then records the claim and returns its result. Admin routes support code inventory, accounts, history, and statistics; link/banner administration is delegated to a separate worker. The graph follows the sampled route and server wiring; database bindings are selected in middleware, while the downstream worker’s implementation is outside this repository.

Main entry points: [`src/server.js`](https://github.com/nntfb777/99okcode-backend/blob/main/src/server.js) (Hono app), [`src/routes/adminRoutes.js`](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/adminRoutes.js) (Code management), [`src/routes/clientRoutes.js`](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/clientRoutes.js) (Claim handler), [`src/routes/authRoutes.js`](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/authRoutes.js) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request routing"]
  node_server["Hono app<br/>[server.js]"]
  node_pages["Page routes<br/>[pageRoutes.js]"]
end

subgraph group_redemption["Code redemption"]
  node_claim["Claim handler<br/>[clientRoutes.js]"]
  node_site_db[("Site D1 databases")]
end

subgraph group_administration["Administration"]
  node_auth["Authentication<br/>[authRoutes.js]"]
  node_code_admin["Code management<br/>[adminRoutes.js]"]
  node_account_admin["Account management<br/>[manaRoutes.js]"]
  node_history["Claim history<br/>[historyRoutes.js]"]
  node_links["Link administration<br/>[adminLinks.js]"]
end

subgraph group_integrations["External services"]
  node_worker_client["Worker API client<br/>[workerService.js]"]
  node_turnstile["Cloudflare Turnstile"]
  node_links_worker["Links worker"]
end

node_client(("Client"))

node_client -->|"sends requests"| node_server
node_server -->|"routes requests"| node_pages
node_server -->|"routes requests"| node_auth
node_server -->|"routes requests"| node_code_admin
node_server -->|"routes requests"| node_account_admin
node_server -->|"routes requests"| node_history
node_server -->|"routes requests"| node_links
node_server -->|"routes requests"| node_claim
node_server -->|"selects binding"| node_site_db
node_server -->|"JWT protects"| node_code_admin
node_auth -->|"reads users"| node_site_db
node_account_admin -->|"reads and writes"| node_site_db
node_code_admin -->|"manages codes"| node_site_db
node_code_admin -->|"reads claim stats"| node_site_db
node_history -->|"reads and deletes"| node_site_db
node_claim -->|"verifies captcha"| node_turnstile
node_claim -->|"checks and records"| node_site_db
node_links -->|"calls"| node_worker_client
node_worker_client -->|"forwards requests"| node_links_worker

click node_server "https://github.com/nntfb777/99okcode-backend/blob/main/src/server.js"
click node_pages "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/pageRoutes.js"
click node_auth "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/authRoutes.js"
click node_code_admin "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/adminRoutes.js"
click node_account_admin "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/manaRoutes.js"
click node_history "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/historyRoutes.js"
click node_links "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/adminLinks.js"
click node_worker_client "https://github.com/nntfb777/99okcode-backend/blob/main/src/services/workerService.js"
click node_claim "https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/clientRoutes.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_pages,node_client toneBlue
class node_claim,node_site_db toneAmber
class node_auth,node_code_admin,node_account_admin,node_history,node_links toneMint
class node_worker_client,node_turnstile,node_links_worker toneRose
```

## Components

### Request routing

- [Hono app](https://github.com/nntfb777/99okcode-backend/blob/main/src/server.js): `src/server.js`
- [Page routes](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/pageRoutes.js): `src/routes/pageRoutes.js`

### Code redemption

- [Claim handler](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/clientRoutes.js): `src/routes/clientRoutes.js`
- **Site D1 databases**

### Administration

- [Authentication](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/authRoutes.js): `src/routes/authRoutes.js`
- [Code management](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/adminRoutes.js): `src/routes/adminRoutes.js`
- [Account management](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/manaRoutes.js): `src/routes/manaRoutes.js`
- [Claim history](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/historyRoutes.js): `src/routes/historyRoutes.js`
- [Link administration](https://github.com/nntfb777/99okcode-backend/blob/main/src/routes/adminLinks.js): `src/routes/adminLinks.js`

### External services

- [Worker API client](https://github.com/nntfb777/99okcode-backend/blob/main/src/services/workerService.js): `src/services/workerService.js`
- **Cloudflare Turnstile**
- **Links worker**

### Other components

- **Client**

## Connections

- Client → Hono app: sends requests (evidence: `src/server.js`)
- Hono app → Page routes: routes requests (evidence: `src/server.js`)
- Hono app → Authentication: routes requests (evidence: `src/server.js`)
- Hono app → Code management: routes requests (evidence: `src/server.js`)
- Hono app → Account management: routes requests (evidence: `src/server.js`)
- Hono app → Claim history: routes requests (evidence: `src/server.js`)
- Hono app → Link administration: routes requests (evidence: `src/server.js`)
- Hono app → Claim handler: routes requests (evidence: `src/server.js`)
- Hono app → Site D1 databases: selects binding (evidence: `src/server.js`)
- Hono app → Code management: JWT protects (evidence: `src/server.js`)
- Authentication → Site D1 databases: reads users (evidence: `src/routes/authRoutes.js`)
- Account management → Site D1 databases: reads and writes (evidence: `src/routes/manaRoutes.js`)
- Code management → Site D1 databases: manages codes (evidence: `src/routes/adminRoutes.js`)
- Code management → Site D1 databases: reads claim stats (evidence: `src/routes/adminRoutes.js`)
- Claim history → Site D1 databases: reads and deletes (evidence: `src/routes/historyRoutes.js`)
- Claim handler → Cloudflare Turnstile: verifies captcha (evidence: `src/routes/clientRoutes.js`)
- Claim handler → Site D1 databases: checks and records (evidence: `src/routes/clientRoutes.js`)
- Link administration → Worker API client: calls (evidence: `src/routes/adminLinks.js`)
- Worker API client → Links worker: forwards requests (evidence: `src/services/workerService.js`)
