mirror of
https://github.com/bckelley/cgm-remote-monitor.git
synced 2026-08-24 03:14:12 -05:00
copilot-swe-agent[bot]andbewest
002f34fcda
Co-authored-by: bewest <394179+bewest@users.noreply.github.com>
144 lines
5.2 KiB
Markdown
144 lines
5.2 KiB
Markdown
# Entries Schema Documentation
|
|
|
|
**Document Version:** 1.0
|
|
**Last Updated:** March 2026
|
|
**Status:** Active (2025 Standard)
|
|
**Source:** Code analysis (`lib/server/entries.js`)
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The `entries` collection stores CGM (Continuous Glucose Monitor) sensor readings and related data. This includes SGV (sensor glucose values), MBG (meter blood glucose), and calibration data.
|
|
|
|
**Collection Name:** `entries`
|
|
**Primary Key:** `sysTime` + `type` (composite)
|
|
**Primary Timestamp Field:** `sysTime` (ISO 8601, derived from `dateString` or `date`)
|
|
|
|
---
|
|
|
|
## Core Fields
|
|
|
|
| Field | Type | Required | Constraints | Description |
|
|
|-------|------|----------|-------------|-------------|
|
|
| `_id` | ObjectId | Yes (auto) | MongoDB ObjectId | Primary key, auto-generated by server |
|
|
| `type` | String | Yes | `sgv`, `mbg`, `cal`, etc. | Type of entry |
|
|
| `date` | Number | Yes | Epoch milliseconds | When the reading was taken |
|
|
| `dateString` | String | Yes | ISO 8601 | Same as `date` in string format |
|
|
| `sysTime` | String | Computed | ISO 8601 | Normalized timestamp (computed from `dateString` or `date`) |
|
|
| `utcOffset` | Number | Computed | Minutes | UTC offset parsed from `dateString` |
|
|
|
|
---
|
|
|
|
## SGV Fields (type: "sgv")
|
|
|
|
| Field | Type | Constraints | Description |
|
|
|-------|------|-------------|-------------|
|
|
| `sgv` | Number | mg/dL or mmol/L | Sensor glucose value |
|
|
| `direction` | String | Trend arrows | Glucose trend direction |
|
|
| `noise` | Number | 0-4 | Signal noise level |
|
|
| `filtered` | Number | Raw value | Filtered sensor signal |
|
|
| `unfiltered` | Number | Raw value | Unfiltered sensor signal |
|
|
| `rssi` | Number | dBm | Signal strength (Dexcom) |
|
|
|
|
---
|
|
|
|
## Sync Identity Fields
|
|
|
|
| Field | Type | Source | Description |
|
|
|-------|------|--------|-------------|
|
|
| `identifier` | String | Server-normalized | **Unified client sync identity** (see below) |
|
|
| `device` | String | CGM app | Device/app identifier (e.g., `"xDrip-DexcomG6"`) |
|
|
|
|
### Identifier Field Normalization (REQ-SYNC-072)
|
|
|
|
As of v15.0.7, the server normalizes UUID values in `_id` into the `identifier` field when `UUID_HANDLING=true` (default):
|
|
|
|
| Client | Sends | Server Action (UUID_HANDLING=true) | Server Action (UUID_HANDLING=false) |
|
|
|--------|-------|-------------------------------------|--------------------------------------|
|
|
| **Trio** | UUID in `_id` | Move to `identifier`, assign server ObjectId | Strip `_id`, assign ObjectId (UUID not preserved) |
|
|
| **Loop** (entries) | ObjectId (from cache) | Normal ObjectId behavior | Normal ObjectId behavior |
|
|
|
|
**Note**: The `UUID_HANDLING` env var controls **both** write-path normalization (identifier extraction) and read-path queries (GET/DELETE by UUID).
|
|
|
|
**Important**: For entries, `sysTime + type` is ALWAYS the primary deduplication key. The `identifier` field is for client sync tracking only - it does NOT override the dedup logic.
|
|
|
|
---
|
|
|
|
## Deduplication Behavior
|
|
|
|
Entries use **sysTime + type** as the composite unique key:
|
|
|
|
```javascript
|
|
// Upsert query for entries (lib/server/entries.js)
|
|
{ sysTime: doc.sysTime, type: doc.type }
|
|
```
|
|
|
|
This means:
|
|
- Two SGV readings at the same `sysTime` will be deduplicated (one overwrites the other)
|
|
- Different entry types (SGV vs MBG) at the same time are allowed
|
|
- Re-uploading the same reading updates the existing document
|
|
|
|
### UUID _id Handling
|
|
|
|
When a client sends a UUID as `_id`:
|
|
|
|
1. **Extract**: UUID is copied to `identifier` field (when `UUID_HANDLING=true`)
|
|
2. **Strip**: Non-ObjectId `_id` is removed before database operation
|
|
3. **Upsert**: Server uses `sysTime + type` for matching
|
|
4. **Assign**: Server-generated ObjectId becomes final `_id`
|
|
|
|
This prevents the MongoDB "immutable field '_id'" error while preserving client sync identity (when enabled).
|
|
|
|
---
|
|
|
|
## UUID_HANDLING Feature Flag
|
|
|
|
The `UUID_HANDLING` environment variable controls both **write-path** normalization (identifier extraction) and **read-path** queries (GET/DELETE by UUID).
|
|
|
|
When `UUID_HANDLING=true` (default):
|
|
|
|
| Operation | Behavior |
|
|
|-----------|----------|
|
|
| POST/PUT with UUID `_id` | UUID moved to `identifier`, server assigns ObjectId |
|
|
| GET by UUID | Searches by `identifier` field |
|
|
| DELETE by UUID | Deletes by `identifier` field |
|
|
|
|
When `UUID_HANDLING=false`:
|
|
|
|
| Operation | Behavior |
|
|
|-----------|----------|
|
|
| POST/PUT with UUID `_id` | UUID `_id` stripped, ObjectId assigned (UUID not preserved) |
|
|
| GET by UUID | Returns empty (no crash) |
|
|
| DELETE by UUID | Deletes nothing (no crash) |
|
|
|
|
**Note**: This only affects cases where a UUID is passed as the `_id` field (writes) or as the `_id` parameter in API calls (reads), e.g., `GET /api/v1/entries/{uuid}`.
|
|
|
|
---
|
|
|
|
## Example Entry Document
|
|
|
|
```json
|
|
{
|
|
"_id": "507f1f77bcf86cd799439011",
|
|
"type": "sgv",
|
|
"sgv": 120,
|
|
"direction": "Flat",
|
|
"date": 1704067200000,
|
|
"dateString": "2024-01-01T00:00:00.000Z",
|
|
"sysTime": "2024-01-01T00:00:00.000Z",
|
|
"utcOffset": 0,
|
|
"identifier": "550e8400-e29b-41d4-a716-446655440000",
|
|
"device": "xDrip-DexcomG6",
|
|
"noise": 1
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Related Documents
|
|
|
|
- [Treatments Schema](treatments-schema.md) - Similar identifier normalization
|
|
- [GAP-SYNC-045](../../../traceability/sync-identity-gaps.md#gap-sync-045) - Trio entries UUID issue
|
|
- [REQ-SYNC-072](../../../traceability/sync-identity-requirements.md#req-sync-072) - Identifier normalization requirement
|