cgm-remote-monitor/replit.md

Nightscout CGM Remote Monitor

Overview

Nightscout is a web-based CGM (Continuous Glucose Monitor) system allowing caregivers to remotely view a patient's glucose data in realtime. Version 15.0.4 of the cgm-remote-monitor project.

Current State

• Running on Replit with MongoDB local development database
• Server on port 5000 (0.0.0.0)
• Webpack bundling for frontend assets
• Three API versions available (v1, v2, v3)

Project Structure

lib/
├── server/           # Server core (server.js, app.js, env.js)
├── api/              # REST API v1
├── api2/             # REST API v2 (extends v1 + authorization)
├── api3/             # REST API v3 (modern, OpenAPI 3.0)
├── authorization/    # JWT auth, roles, subjects, permissions
├── plugins/          # Feature plugins (ar2, basal, bolus, cob, iob, etc.)
├── storage/          # MongoDB storage adapters
├── client/           # Client-side code
├── data/             # Data loading and processing
└── report_plugins/   # Report generation

static/               # Frontend HTML, CSS, JS, assets
bundle/               # Webpack bundle sources
webpack/              # Webpack configuration
docs/                 # Plugin documentation
start.sh              # Startup script (MongoDB + app)

API Endpoints

API v1 (/api/v1)

Endpoint	Description
/entries/*	CGM entries (sgv, mbg, cal)
/treatments/*	Treatment records
/profile/*	User profiles
/devicestatus/*	Device status
/food/*	Food database
/activity/*	Activity records
/notifications/*	Notifications
/status/*	Server status
/alexa/*	Alexa integration
/googlehome/*	Google Home integration

API v2 (/api/v2)

Extends v1 with:

Endpoint	Description
/authorization/request/{token}	Get JWT token
/authorization/subjects	Manage subjects (CRUD)
/authorization/roles	Manage roles (CRUD)
/authorization/permissions	List permissions
/properties	System properties
/ddata	Data endpoints
/summary	Summary data

API v3 (/api/v3)

Modern REST API with OpenAPI 3.0 spec.

Endpoint	Methods	Description
/{collection}	GET, POST	Search/create documents
/{collection}/{id}	GET, PUT, PATCH, DELETE	CRUD by identifier
/{collection}/history/{lastModified}	GET	Changes since timestamp
/version	GET	API version
/status	GET	API status
/lastModified	GET	Last modification times

Collections: entries, treatments, devicestatus, food, profile, settings

Swagger UI: Available at /api3-docs

Authentication

API v1

• API_SECRET as SHA1 hash in header: api-secret: <sha1-hash>
• Or token parameter: ?token=<sha1-hash>

API v2/v3 (JWT)

1. Create subjects/roles in Admin Tools
2. Get JWT: GET /api/v2/authorization/request/{accessToken}
3. Use in header: Authorization: Bearer <jwt>

Permissions format: api:<collection>:<action>

• Examples: api:entries:read, api:treatments:create, api:*:*

Real-time Data (Socket.IO)

Namespace	Purpose	Auth
/storage	Data updates for collections	accessToken required
/alarm	Alarm notifications	accessToken required

OpenAPI Specifications

File	Version
lib/server/swagger.yaml	API v1 (14.2.3)
lib/api3/swagger.yaml	API v3 (3.0.4)

Environment Variables

Core

Variable	Description	Default
PORT	Server port	1337
HOSTNAME	Bind address	null
MONGO_CONNECTION	MongoDB URI	-
API_SECRET	Auth secret (min 12 chars)	-
INSECURE_USE_HTTP	Allow HTTP (for proxies)	false

API v3

Variable	Description	Default
API3_SECURITY_ENABLE	Enable auth	true
API3_MAX_LIMIT	Max docs per query	1000
API3_DEDUP_FALLBACK_ENABLED	Dedup for legacy docs	true

Display

Variable	Description	Default
DISPLAY_UNITS	mg/dl or mmol	mg/dl
ENABLE	Enabled plugins	-

Replit Configuration

• PORT=5000, HOSTNAME=0.0.0.0
• INSECURE_USE_HTTP=true (required for Replit proxy)
• MongoDB at mongodb://localhost:27017/nightscout
• Data stored in /home/runner/data/db

NPM Scripts

Script	Description
npm start	Production server
npm run bundle	Webpack build
npm run dev	Dev server with nodemon
npm test	Run tests

Security Documentation

• lib/api3/doc/security.md - Auth model
• lib/api3/doc/socket.md - Storage socket
• lib/api3/doc/alarmsockets.md - Alarm socket
• lib/api3/doc/tutorial.md - API tutorial

Agentic Control Plane Proposal (RFC)

A proposal for extending Nightscout with a clean separation between control plane (policy, configuration, intent) and data plane (observations, telemetry, delivery) to enable AI agent collaboration with AID systems.

Proposal Documentation

Document	Description
docs/proposals/agent-control-plane-rfc.md	Main RFC document with full architecture
docs/proposals/integration-questionnaire.md	Questions for Loop/AAPS/Trio implementers
docs/proposals/bridge-rules.md	Legacy devicestatus → event synthesis rules
docs/proposals/conflict-resolution.md	Multi-writer semantics and authority model

JSON Schemas (draft-2020-12)

Located in docs/proposals/schemas/:

Schema	Purpose
event-envelope.schema.json	Wrapper for all control plane events
profile-definition.schema.json	User-authored profile configuration
profile-selection.schema.json	Profile activation events
override-definition.schema.json	Reusable override templates
override-instance.schema.json	Concrete override activations
policy-composition.schema.json	Materialized effective parameters
delivery-request.schema.json	Intent to deliver insulin
delivery-observation.schema.json	Confirmed delivery records
reconciliation.schema.json	Request/observation matching
controller-kind-definition.schema.json	Controller type capabilities
controller-instance-registration.schema.json	Controller instance registry
capability-snapshot.schema.json	Real-time controller state

Key Concepts

• Config vs Runtime vs Computed - Separate user-authored config from runtime activations from computed state
• Events over Snapshots - Append-only event streams with cursor-based sync
• Authority Hierarchy - Human > Agent > Controller for conflict resolution
• Bridge Mode - Synthesize events from legacy devicestatus uploads
• MDI as First-Class - Manual injections are always valid

Testing & Architecture Modernization Proposal

A revised proposal aligning test modernization with broader UI and architecture goals.

Document	Description
docs/proposals/testing-modernization-proposal.md	Three-track modernization plan with scope guardrails

Three-Track Approach

• Track 1 (2 weeks): Testing Foundation - Update mocha/supertest/nyc, migrate hashauth tests with secure jsdom harness
• Track 2 (3 weeks): Logic/DOM Separation - Extract pure logic to lib/client-core/ for fast, DOM-free testing
• Track 3 (4 weeks): UI Modernization Discovery - Technology evaluation, server-side stats API contracts, migration roadmap

Key Decisions

• Keep hashauth tests (security-critical)
• Skip/defer other client tests (UI code may be rewritten)
• Unified Mocha test runner (no Jest migration needed)
• Strict network isolation in test harness (NoNetworkLoader pattern)

Scope Guardrails

• Milestone exit reviews before proceeding
• Out-of-scope items logged and deferred
• No new UI module without test strategy

Comprehensive System Audit Documentation

A complete audit of the Nightscout codebase covering all major subsystems, created to support system understanding and modernization planning.

Audit Documents

Located in docs/:

Document	Description
architecture-overview.md	System diagram, component relationships, data flow, tech stack
security-audit.md	Auth mechanisms, JWT, Shiro permissions, brute-force protection (delaylist.js)
api-layer-audit.md	REST v1/v2/v3 contracts, endpoint inventory, WebSocket protocols
data-layer-audit.md	MongoDB collections, schemas, auto-pruning, sync mechanisms
realtime-systems-audit.md	Socket.IO namespaces, event bus patterns, latency analysis
plugin-architecture-audit.md	Plugin system design, 38 plugins inventory, Pebble integration
dashboard-ui-audit.md	Client bundle structure, D3/jQuery charting, clock displays
messaging-subsystem-audit.md	Pushover, IFTTT Maker, notification flows, acknowledgment
modernization-roadmap.md	Technical debt inventory, phased refactoring plan

Critical Findings

• Auth Brute-Force Protection - Implemented via delaylist.js (IP-based progressive delay)
• General API Rate Limiting - Not implemented, recommended for DoS protection
• Deprecated Dependencies - request library should be replaced with axios
• Bundle Size - ~1MB+ production bundle, optimization opportunities exist
• Node.js Support - Supports ^14.x, ^16.x, ^18.x, ^20.x

Authentication Modernization Direction

• OIDC/OAuth2 plugin for vendor-agnostic identity
• nightscout-roles-gateway integration for consent and delegation
• Ory Hydra/Kratos as identity backend option
• Aligns with Control Plane RFC authority model (Human > Agent > Controller)

Recent Changes

• 2026-01-13: Updated audit docs with accurate rate limiting info (delaylist.js) and OIDC/gateway architecture direction
• 2026-01-13: Created comprehensive 9-document system audit with security findings and modernization roadmap
• 2026-01-13: Revised Testing Modernization Proposal with three-track approach, Logic/DOM separation, and UI Discovery track
• 2026-01-01: Added Agentic Control Plane RFC and JSON schemas
• 2025-12-31: Updated to version 15.0.4 (dev branch)
• Configured for Replit with INSECURE_USE_HTTP=true
• MongoDB 3.6.x driver
• Webpack bundling for frontend