bckelley/cgm-remote-monitor
1
0
Fork 0
mirror of https://github.com/bckelley/cgm-remote-monitor.git synced 2026-08-24 03:14:12 -05:00
Code Issues Packages Projects Releases Wiki Activity

Add project documentation progress tracker and update README

Browse Source 
Create `docs/DOCUMENTATION-PROGRESS.md` to track requirements and test specification efforts, including progress, priorities, lessons learned, and guidance for collaborators. Update `replit.md` to reference this new progress tracker.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 055897c4-83a5-4136-93d8-ff61ec1a77a8
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: 5af50b7b-7741-43cb-9f57-56a3635f46b7
Replit-Helium-Checkpoint-Created: true
This commit is contained in:
bewest
2026-01-19 13:14:21 -08:00
committed by Ben West
parent 12961ed0a2
commit 06beef94ba
2 changed files with 224 additions and 296 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DOCUMENTATION-PROGRESS.md
+186
View File
@@ -0,0 +1,186 @@
# Nightscout Documentation Progress Tracker
## Overview
This document tracks the ongoing effort to produce comprehensive product requirements and test specifications following the component system audits. The goal is to formalize existing behaviors, map tests to requirements, and identify coverage gaps across all major subsystems.
**Started:** January 2026
**Approach:** Audit-first methodology - review component audits, then create formal requirements specs and test specifications with traceability matrices.
---
## Progress Summary
### Completed Documentation
| Area | Requirements Doc | Test Spec | Status | Notes |
|------|------------------|-----------|--------|-------|
| Data Shape Handling | `requirements/data-shape-requirements.md` | `test-specs/shape-handling-test-spec.md` | ✅ Complete | MongoDB 5.x migration work, 38 tests |
| API v1 Compatibility | `requirements/api-v1-compatibility-spec.md` | (integrated) | ✅ Complete | Client compatibility (AAPS, Loop, xDrip) |
| Authorization/Security | `requirements/authorization-security-spec.md` | `test-specs/authorization-test-spec.md` | ✅ Complete | 21 tests mapped, coverage gaps identified |
### System Audits (Reference Documents)
These audits provide the foundation for requirements extraction:
| Audit Document | Subsystem | Req/Test Status |
|----------------|-----------|-----------------|
| `architecture-overview.md` | System-wide | Reference only |
| `security-audit.md` | Auth, brute-force, JWT | ✅ Extracted to specs |
| `api-layer-audit.md` | REST v1/v2/v3, WebSocket | Partial (v1 done, v3 needed) |
| `data-layer-audit.md` | MongoDB, collections, sync | ✅ Shape handling extracted |
| `realtime-systems-audit.md` | Socket.IO, event bus | ❌ Not started |
| `plugin-architecture-audit.md` | 38 plugins, Pebble | ❌ Not started |
| `dashboard-ui-audit.md` | Client bundle, D3/jQuery | ❌ Not started (may defer) |
| `messaging-subsystem-audit.md` | Pushover, IFTTT, notifications | ❌ Not started |
| `modernization-roadmap.md` | Tech debt, refactoring | Reference only |
---
## Priority Queue
### Tier 1: High Priority (Security/Data Critical)
| Area | Why Important | Estimated Effort | Blocking Issues |
|------|---------------|------------------|-----------------|
| **API v3 Security** | Distinct auth model from v1/v2, health data access | Medium | Need to review `lib/api3/security.js` and `tests/api3.*.test.js` |
| **WebSocket Auth** | Real-time data streams need auth coverage | Medium | Currently identified as coverage gap in auth-test-spec |
| **Core Calculations (IOB/COB)** | Critical for diabetes management decisions | High | Complex algorithms, requires domain expertise |
### Tier 2: Medium Priority (Functional Coverage)
| Area | Why Important | Estimated Effort | Blocking Issues |
|------|---------------|------------------|-----------------|
| **Plugin System** | 38 plugins, extensibility foundation | High | Large surface area, many plugins undocumented |
| **Real-time Event Bus** | Data synchronization between components | Medium | Need to trace event flows |
| **Notification/Messaging** | Alerts for dangerous glucose levels | Medium | Multiple providers (Pushover, IFTTT, etc.) |
### Tier 3: Lower Priority (UI/UX or Deferred)
| Area | Why Important | Estimated Effort | Blocking Issues |
|------|---------------|------------------|-----------------|
| **Dashboard UI** | User-facing but may be rewritten | Low (defer) | Testing Modernization Proposal suggests UI rewrite |
| **Report Plugins** | Secondary to real-time monitoring | Low | Depends on plugin system work |
| **Pebble Integration** | Legacy smartwatch support | Very Low | Pebble discontinued |
---
## Lessons Learned
### Documentation Patterns That Work
1. **Start with code, not assumptions** - Every requirement must cite a source file and line number. Initial assumptions about JWT using API_SECRET were wrong; code review revealed dedicated signing key.
2. **Separate requirements from implementation details** - Requirements state "what" and "why"; implementation notes explain "how" the code does it. This distinction helps future refactoring.
3. **Test ID conventions** - Using prefixed IDs (SEC-001, HASH-002, etc.) makes traceability matrices scannable and enables automated coverage checks.
4. **Coverage gaps are as valuable as coverage** - Documenting what's NOT tested is critical for security audits and prioritization.
### Technical Discoveries
| Discovery | Impact | Source |
|-----------|--------|--------|
| JWT uses dedicated signing key, not API_SECRET | Corrected security model understanding | `lib/server/enclave.js` |
| Brute-force cleanup is one-shot setTimeout | Potential long-running server issue | `lib/authorization/delaylist.js` |
| Both SHA-1 and SHA-512 accepted for API_SECRET | Migration path but potential confusion | `lib/hashauth.js` |
| Access token = SHA-1(apiKeySHA1 + subject._id) | Not direct API_SECRET derivative | `lib/server/enclave.js:getSubjectHash()` |
| devicestatus.js had race condition with arrays | Fixed in PR #8314 | `lib/server/devicestatus.js` |
| WebSocket insertOne() with array creates single doc | MongoDB driver behavior, not intuitive | `lib/server/websocket.js` |
### Process Improvements
- **Architect reviews catch accuracy issues** - Multiple review cycles improved documentation accuracy significantly
- **Traceability matrices expose gaps visually** - Easy to spot "Not Covered" in a table
- **Quirks/Barriers sections prevent future frustration** - Document the weird stuff so others don't rediscover it
---
## Open Questions
### Requiring Domain Expert Input
1. **IOB/COB algorithm correctness** - Are the calculation algorithms clinically validated? What are acceptable error bounds?
2. **Alarm threshold safety margins** - What are the clinical requirements for glucose alarm thresholds? Are current defaults evidence-based?
3. **Plugin interaction edge cases** - When multiple plugins modify the same data, what's the expected precedence?
### Requiring Architecture Decisions
1. **API v3 vs v1/v2 long-term** - Should v1/v2 be deprecated? What's the migration timeline?
2. **Rate limiting addition** - Security audit identified missing general rate limiting. Priority?
3. **OIDC/OAuth2 integration** - Modernization roadmap mentions this. Does it supersede current auth model?
### Requiring More Investigation
1. **Socket.IO namespace isolation** - Do `/storage` and `/alarm` properly isolate data by authorization level?
2. **MongoDB transaction support** - With MongoDB 5.x, should multi-document writes use transactions?
3. **Event bus memory leaks** - Are there cleanup mechanisms for event subscriptions on disconnect?
---
## For the Next Collaborator
Welcome! If you're picking up this documentation effort, here's how to get started:
### Quick Start
1. **Read the audits first** - The `docs/*.audit.md` files provide system understanding before diving into specs
2. **Pick from the priority queue** - Tier 1 items are most impactful
3. **Follow the established pattern**:
- Create `docs/requirements/<area>-spec.md` for formal requirements
- Create `docs/test-specs/<area>-test-spec.md` for test mappings
- Update this progress document when done
### Template Structure
Requirements documents should include:
- Purpose and scope
- Terminology (be precise, cite code)
- Numbered requirements with IDs (REQ-XXX-NNN format)
- Implementation references (file:line)
- Security considerations
Test specifications should include:
- Existing test inventory with unique IDs
- Test case descriptions with expected behavior
- Requirement traceability matrix
- Coverage gaps (high/medium/low priority)
- Discovered quirks and barriers
### Key Files to Understand
- `lib/authorization/index.js` - Main auth entry point
- `lib/server/env.js` - Environment/configuration loading
- `lib/server/bootevent.js` - Server initialization sequence
- `lib/plugins/index.js` - Plugin loading system
- `tests/*.test.js` - Existing test suite
### What NOT to Change
This effort is documentation-only. Do not:
- Modify source code (log bugs separately)
- Add new tests (document gaps for future work)
- Refactor existing tests (conflicts with testing modernization proposal)
### Communication
- Update `replit.md` with significant discoveries
- Add findings to Lessons Learned section
- Note any blocking issues in the priority queue
Good luck, and thank you for contributing!
---
## Revision History
| Date | Author | Changes |
|------|--------|---------|
| 2026-01-15 | Agent | Initial document, completed auth/security specs |
| 2026-01-15 | Agent | Added lessons learned, open questions, priority queue |
replit.md
+38 -296
View File
@@ -1,305 +1,47 @@
# 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.
Nightscout is a web-based Continuous Glucose Monitor (CGM) system designed to allow caregivers to remotely view a patient's glucose data in real-time. The project aims to provide robust, real-time glucose monitoring, data visualization, and alert capabilities, supporting both patient care and clinical research. Key capabilities include multiple API versions for data access, comprehensive data storage, and a plugin-based architecture for extensibility. Future ambitions include enhanced AI agent collaboration through a dedicated control plane, modernized testing frameworks, and advanced authentication mechanisms.
## 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)
## User Preferences
I want iterative development. Ask before making major architectural changes. Provide detailed explanations for complex technical decisions.
## 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
## System Architecture
The Nightscout system is built around a Node.js server with a MongoDB database. It features a modular structure, separating server core, API versions (v1, v2, v3), authorization, plugins, and client-side code.
static/ # Frontend HTML, CSS, JS, assets
bundle/ # Webpack bundle sources
webpack/ # Webpack configuration
docs/ # Plugin documentation
start.sh # Startup script (MongoDB + app)
```
### UI/UX Decisions
The frontend utilizes Webpack for asset bundling and features charting with D3/jQuery, providing a dynamic dashboard experience.
## API Endpoints
### Technical Implementations
- **API Versions:**
- **API v1 (`/api/v1`):** Provides core CGM data, treatments, profiles, and device status. Uses `API_SECRET` for basic authentication.
- **API v2 (`/api/v2`):** Extends v1 with advanced authorization, including JWT tokens, roles, subjects, and permissions management.
- **API v3 (`/api/v3`):** A modern REST API based on OpenAPI 3.0, offering comprehensive CRUD operations for collections like entries, treatments, and devicestatus. Swagger UI is available at `/api3-docs`.
- **Authentication:**
- **API v1:** SHA1 hash of `API_SECRET` in headers or as a query parameter.
- **API v2/v3:** JWT-based authentication with `Bearer` tokens, managed through an authorization subsystem that defines subjects, roles, and fine-grained permissions (e.g., `api:entries:read`).
- **Real-time Data:** Implemented using Socket.IO for real-time updates on data storage and alarm notifications.
- **Plugin Architecture:** A robust plugin system (e.g., ar2, basal, bolus, cob, iob) allows for extending functionality.
- **Agentic Control Plane (Proposed):** A clean separation between control plane (policy, configuration, intent) and data plane (observations, telemetry, delivery) to facilitate AI agent collaboration with AID systems. This includes JSON schemas for event envelopes, profile definitions, override instances, and delivery requests/observations. Key concepts include event-driven architecture, authority hierarchy (Human > Agent > Controller), and bridge modes for legacy data.
- **Testing & Modernization (Proposed):** A three-track approach for modernizing testing:
1. **Testing Foundation:** Update core testing libraries (Mocha, Supertest, NYC) and secure existing tests.
2. **Logic/DOM Separation:** Extract pure logic into `lib/client-core/` for isolated, DOM-free testing.
3. **UI Modernization Discovery:** Evaluate new UI technologies and define a migration roadmap.
- **Security:** Brute-force protection for authentication is implemented via `delaylist.js` (IP-based progressive delay).
- **MongoDB Driver 5.x Compatibility:** Updates to handle multi-document writes and race conditions, ensuring correct processing of array inputs for `devicestatus` and WebSocket `dbAdd` operations.
### 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 |
### System Design Choices
- **Event-driven architecture** for control plane interactions.
- **Append-only event streams** with cursor-based synchronization.
- **Config vs Runtime vs Computed** separation for clarity and maintainability.
- **Monorepo structure** for managing various components.
- **Environment variables** for flexible configuration, including `PORT`, `MONGO_CONNECTION`, `API_SECRET`, and `DISPLAY_UNITS`.
### 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
## Documentation Structure
### Requirements & Specifications
Located in `docs/requirements/` and `docs/test-specs/`:
| Document | Description |
|----------|-------------|
| `requirements/data-shape-requirements.md` | Formal requirements for single vs array input handling |
| `requirements/api-v1-compatibility-spec.md` | Client compatibility requirements (AAPS, Loop, xDrip) |
| `requirements/authorization-security-spec.md` | Auth requirements: API_SECRET, JWT, Shiro permissions, brute-force protection |
| `test-specs/shape-handling-test-spec.md` | Test case specifications with requirement traceability |
| `test-specs/authorization-test-spec.md` | Security test cases mapped to auth requirements, coverage gaps identified |
## 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)
## MongoDB Driver 5.x Migration Testing (PR #8314)
### Critical Findings - Multi-Document Write Support
**Test Suite:** `tests/api.shape-handling.test.js`, `tests/websocket.shape-handling.test.js`, `tests/storage.shape-handling.test.js`
#### Issue 1: devicestatus.js Race Condition (FIXED)
- **Problem:** `create()` function had a closure variable capture bug in async for-loop causing data loss with array inputs
- **Root Cause:** Loop variable captured by reference in callback, race condition between iterations
- **Fix:** Refactored to use `async.eachSeries()` for sequential processing
- **File:** `lib/server/devicestatus.js`
#### Issue 2: WebSocket dbAdd Array Handling (FIXED)
- **Problem:** `insertOne()` with array creates single document containing the array, NOT multiple documents
- **Root Cause:** MongoDB driver behavior - `insertOne([a,b])` stores `{0: a, 1: b}` as one document
- **Fix:** Added `processSingleDbAdd()` helper that iterates array items and processes each sequentially
- **File:** `lib/server/websocket.js`
### Shape Handling Behavior Matrix
| Interface | Single Object | Array Input | Status |
|-----------|---------------|-------------|--------|
| REST API v1 treatments | ✅ | ✅ | Works correctly |
| REST API v1 entries | ✅ | ✅ | Works correctly |
| REST API v1 devicestatus | ✅ | ✅ | Fixed (was race condition) |
| WebSocket dbAdd | ✅ | ✅ | Fixed (was insertOne issue) |
| Storage treatments.create | ✅ | ✅ | Works correctly |
| Storage devicestatus.create | ✅ | ✅ | Fixed |
| Storage entries.create | ✅ | ✅ | Works correctly |
| Storage activity.create | ❌ | ✅ | Expects array only |
### Test Results
- 38 passing tests documenting all shape handling behaviors
- Tests cover API v1, WebSocket storage namespace, and direct storage layer
### Key Implementation Details
- UPDATE_THROTTLE (15 seconds) in `bootevent.js` intentionally debounces data updates
- AAPS/Loop clients may send batch arrays via WebSocket - now properly supported
- All changes preserve backward compatibility with single-object inputs
## Recent Changes
- 2026-01-15: Added authorization-security-spec.md and authorization-test-spec.md with formal requirements and test traceability for auth subsystem
- 2026-01-15: Fixed devicestatus.js race condition and WebSocket array handling for MongoDB 5.x compatibility
- 2026-01-15: Added comprehensive shape-handling test suite (38 tests) for multi-document write validation
- 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
## External Dependencies
- **MongoDB:** Primary database for data storage.
- **Socket.IO:** For real-time data communication.
- **Webpack:** For bundling frontend assets.
- **Nodemon:** For development server auto-restarts.
- **Mocha, Supertest, NYC:** Testing frameworks.
- **Pushover, IFTTT Maker:** Messaging and notification services.
- **Alexa, Google Home:** Integrations for voice assistant interaction.