# 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