# isaluki/nightflare architecture

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

- Interactive diagram: https://gitdiagram.com/isaluki/nightflare
- Repository: https://github.com/isaluki/nightflare
- Video tour (about a minute): https://gitdiagram.com/isaluki/nightflare/video

## Overview

Nightflare is a Cloudflare Workers implementation of the Nightscout CGM platform, pairing a Nightscout-compatible REST backend with its classic dashboard and an optional modern UI. Users and device apps authenticate, read or upload glucose and treatment data, and receive live updates; the platform also supports profile, food, activity, reporting, administration, and importing from an existing Nightscout. The README documents D1, KV, and Durable Objects; the sampled backend entry point confirms route mounting and UI selection, while detailed wiring inside unsampled route and import handlers is not shown.

Main entry points: [`src/index.ts`](https://github.com/isaluki/nightflare/blob/main/src/index.ts) (Worker router), [`src/db/collection.ts`](https://github.com/isaluki/nightflare/blob/main/src/db/collection.ts) (Collection access), [`src/routes/entries.ts`](https://github.com/isaluki/nightflare/blob/main/src/routes/entries.ts) (Glucose entries), [`src/lib/auth.ts`](https://github.com/isaluki/nightflare/blob/main/src/lib/auth.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Request and access"]
  node_worker["Worker router<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_admin["Admin and roles<br/>[authorization2.ts]"]
end

subgraph group_data["Health data"]
  node_entries["Glucose entries<br/>[entries.ts]"]
  node_treatments["Treatments<br/>[treatments.ts]"]
  node_device["Device status<br/>[devicestatus.ts]"]
  node_profile["Profile and food<br/>[profile.ts]"]
  node_food["Food catalog<br/>[food.ts]"]
  node_activity["Activity data<br/>[activity.ts]"]
  node_status["Status and Pebble<br/>[status.ts]"]
  node_collection["Collection access<br/>[collection.ts]"]
  node_db[("D1 database<br/>[index.ts]")]
  node_query["Mongo-style queries<br/>[mongo-query.ts]"]
end

subgraph group_live["Realtime and import"]
  node_realtime["Realtime endpoint<br/>[realtime.ts]"]
  node_hub["Realtime hub<br/>[realtime-hub.ts]"]
  node_import["Nightscout import job<br/>[import-job.ts]"]
end

subgraph group_ui["User interfaces"]
  node_classic["Classic dashboard<br/>[index.js]"]
  node_modern["Modern UI<br/>[app.js]"]
  node_reports["Reports and editors<br/>[reportclient.js]"]
end

node_clients(("Users and apps"))
node_upstream(("Nightscout source"))

node_clients -->|"send requests"| node_worker
node_worker -->|"checks credentials"| node_auth
node_worker -->|"dispatches API"| node_entries
node_worker -->|"dispatches API"| node_treatments
node_worker -->|"dispatches API"| node_device
node_worker -->|"dispatches API"| node_profile
node_worker -->|"dispatches API"| node_food
node_worker -->|"dispatches API"| node_activity
node_worker -->|"dispatches API"| node_status
node_worker -->|"dispatches API"| node_admin
node_worker -->|"dispatches socket"| node_realtime
node_worker -->|"serves by default"| node_classic
node_worker -.->|"serves when enabled"| node_modern
node_auth -->|"checks permissions"| node_admin
node_entries -->|"uses storage"| node_collection
node_treatments -->|"uses storage"| node_collection
node_device -->|"uses storage"| node_collection
node_profile -->|"uses storage"| node_collection
node_food -->|"uses storage"| node_collection
node_activity -->|"uses storage"| node_collection
node_collection -->|"reads and writes"| node_db
node_entries -->|"parses filters"| node_query
node_realtime -->|"forwards connection"| node_hub
node_hub -->|"pushes updates"| node_clients
node_upstream -->|"provides records"| node_import
node_import -->|"imports data"| node_collection
node_classic -->|"calls REST API"| node_worker
node_modern -->|"calls REST API"| node_worker
node_reports -->|"requests reports"| node_worker

click node_worker "https://github.com/isaluki/nightflare/blob/main/src/index.ts"
click node_auth "https://github.com/isaluki/nightflare/blob/main/src/lib/auth.ts"
click node_admin "https://github.com/isaluki/nightflare/blob/main/src/routes/authorization2.ts"
click node_entries "https://github.com/isaluki/nightflare/blob/main/src/routes/entries.ts"
click node_treatments "https://github.com/isaluki/nightflare/blob/main/src/routes/treatments.ts"
click node_device "https://github.com/isaluki/nightflare/blob/main/src/routes/devicestatus.ts"
click node_profile "https://github.com/isaluki/nightflare/blob/main/src/routes/profile.ts"
click node_food "https://github.com/isaluki/nightflare/blob/main/src/routes/food.ts"
click node_activity "https://github.com/isaluki/nightflare/blob/main/src/routes/activity.ts"
click node_status "https://github.com/isaluki/nightflare/blob/main/src/routes/status.ts"
click node_collection "https://github.com/isaluki/nightflare/blob/main/src/db/collection.ts"
click node_db "https://github.com/isaluki/nightflare/blob/main/src/db/index.ts"
click node_query "https://github.com/isaluki/nightflare/blob/main/src/lib/mongo-query.ts"
click node_realtime "https://github.com/isaluki/nightflare/blob/main/src/routes/realtime.ts"
click node_hub "https://github.com/isaluki/nightflare/blob/main/src/durable-objects/realtime-hub.ts"
click node_import "https://github.com/isaluki/nightflare/blob/main/src/durable-objects/import-job.ts"
click node_classic "https://github.com/isaluki/nightflare/blob/main/client/lib/client/index.js"
click node_modern "https://github.com/isaluki/nightflare/blob/main/public/new-ui/app.js"
click node_reports "https://github.com/isaluki/nightflare/blob/main/client/lib/report/reportclient.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_auth,node_admin,node_clients toneBlue
class node_entries,node_treatments,node_device,node_profile,node_food,node_activity,node_status,node_collection,node_db,node_query toneAmber
class node_realtime,node_hub,node_import toneMint
class node_classic,node_modern,node_reports toneRose
class node_upstream toneIndigo
```

## Components

### Request and access

- [Worker router](https://github.com/isaluki/nightflare/blob/main/src/index.ts): `src/index.ts`
- [Authentication](https://github.com/isaluki/nightflare/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Admin and roles](https://github.com/isaluki/nightflare/blob/main/src/routes/authorization2.ts): `src/routes/authorization2.ts`

### Health data

- [Glucose entries](https://github.com/isaluki/nightflare/blob/main/src/routes/entries.ts): `src/routes/entries.ts`
- [Treatments](https://github.com/isaluki/nightflare/blob/main/src/routes/treatments.ts): `src/routes/treatments.ts`
- [Device status](https://github.com/isaluki/nightflare/blob/main/src/routes/devicestatus.ts): `src/routes/devicestatus.ts`
- [Profile and food](https://github.com/isaluki/nightflare/blob/main/src/routes/profile.ts): `src/routes/profile.ts`
- [Food catalog](https://github.com/isaluki/nightflare/blob/main/src/routes/food.ts): `src/routes/food.ts`
- [Activity data](https://github.com/isaluki/nightflare/blob/main/src/routes/activity.ts): `src/routes/activity.ts`
- [Status and Pebble](https://github.com/isaluki/nightflare/blob/main/src/routes/status.ts): `src/routes/status.ts`
- [Collection access](https://github.com/isaluki/nightflare/blob/main/src/db/collection.ts): `src/db/collection.ts`
- [D1 database](https://github.com/isaluki/nightflare/blob/main/src/db/index.ts): `src/db/index.ts`
- [Mongo-style queries](https://github.com/isaluki/nightflare/blob/main/src/lib/mongo-query.ts): `src/lib/mongo-query.ts`

### Realtime and import

- [Realtime endpoint](https://github.com/isaluki/nightflare/blob/main/src/routes/realtime.ts): `src/routes/realtime.ts`
- [Realtime hub](https://github.com/isaluki/nightflare/blob/main/src/durable-objects/realtime-hub.ts): `src/durable-objects/realtime-hub.ts`
- [Nightscout import job](https://github.com/isaluki/nightflare/blob/main/src/durable-objects/import-job.ts): `src/durable-objects/import-job.ts`

### User interfaces

- [Classic dashboard](https://github.com/isaluki/nightflare/blob/main/client/lib/client/index.js): `client/lib/client/index.js`
- [Modern UI](https://github.com/isaluki/nightflare/blob/main/public/new-ui/app.js): `public/new-ui/app.js`
- [Reports and editors](https://github.com/isaluki/nightflare/blob/main/client/lib/report/reportclient.js): `client/lib/report/reportclient.js`

### Other components

- **Users and apps**
- **Nightscout source**

## Connections

- Users and apps → Worker router: send requests
- Worker router → Authentication: checks credentials
- Worker router → Glucose entries: dispatches API
- Worker router → Treatments: dispatches API
- Worker router → Device status: dispatches API
- Worker router → Profile and food: dispatches API
- Worker router → Food catalog: dispatches API
- Worker router → Activity data: dispatches API
- Worker router → Status and Pebble: dispatches API
- Worker router → Admin and roles: dispatches API
- Worker router → Realtime endpoint: dispatches socket
- Worker router → Classic dashboard: serves by default
- Worker router → Modern UI: serves when enabled
- Authentication → Admin and roles: checks permissions
- Glucose entries → Collection access: uses storage
- Treatments → Collection access: uses storage
- Device status → Collection access: uses storage
- Profile and food → Collection access: uses storage
- Food catalog → Collection access: uses storage
- Activity data → Collection access: uses storage
- Collection access → D1 database: reads and writes
- Glucose entries → Mongo-style queries: parses filters
- Realtime endpoint → Realtime hub: forwards connection
- Realtime hub → Users and apps: pushes updates
- Nightscout source → Nightscout import job: provides records
- Nightscout import job → Collection access: imports data
- Classic dashboard → Worker router: calls REST API
- Modern UI → Worker router: calls REST API
- Reports and editors → Worker router: requests reports