mirror of
https://github.com/bckelley/cgm-remote-monitor.git
synced 2026-08-24 03:14:12 -05:00
docs: add entries schema documentation with UUID handling
Document entries collection fields, sysTime+type dedup behavior, and identifier normalization for Trio/xDrip+ UUID _id uploads. Refs: DOC-API-002, REQ-SYNC-072, GAP-SYNC-045 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Ben West
Copilot
@@ -0,0 +1,138 @@
|
||||
# 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 **automatically normalizes** client sync identities into the `identifier` field:
|
||||
|
||||
| Client | Sends | Server Action |
|
||||
|--------|-------|---------------|
|
||||
| **Trio** | UUID in `_id` | Extract to `identifier`, assign server ObjectId |
|
||||
| **xDrip+** | `uuid` or `identifier` | Copy to `identifier` if present |
|
||||
| **Loop** | ObjectId (from cache) | Normal ObjectId behavior |
|
||||
|
||||
**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
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## UUID_HANDLING Feature Flag
|
||||
|
||||
When `UUID_HANDLING=true` environment variable is set:
|
||||
|
||||
| Operation | Behavior |
|
||||
|-----------|----------|
|
||||
| GET by UUID | Searches by `identifier` field |
|
||||
| DELETE by UUID | Deletes by `identifier` field |
|
||||
|
||||
When `UUID_HANDLING=false` (default):
|
||||
|
||||
| Operation | Behavior |
|
||||
|-----------|----------|
|
||||
| GET by UUID | Returns empty (no crash) |
|
||||
| DELETE by UUID | Deletes nothing (no crash) |
|
||||
|
||||
See [uuid-identifier-lookup specification](../../docs/backlogs/uuid-identifier-lookup.md) for details.
|
||||
|
||||
---
|
||||
|
||||
## Example Entry Document
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": {"$oid": "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
|
||||
Reference in New Issue
Block a user