Golden Age Hub - MVP Data Dictionary¶

1. Core Entities¶

1.1 Agency¶

• id (UUID): Unique identifier
• name (String): Agency name
• contact_email (String, email): Primary contact email
• created_at (Timestamp): When the agency was registered
• public_key (String): Agency's public key for verification

1.2 Caregiver¶

• id (UUID): Unique identifier
• agency_id (UUID): Reference to Agency
• first_name (String)
• last_name (String)
• email (String, email): Login email
• phone (String): Contact number
• role (Enum): [admin, caregiver]
• created_at (Timestamp)
• last_login (Timestamp, nullable)

1.3 Patient¶

• id (UUID): Unique identifier
• agency_id (UUID): Reference to Agency
• first_name (String)
• last_name (String)
• date_of_birth (Date): YYYY-MM-DD
• emergency_contacts (Array[Object]):
• name (String): Contact name
• phone (String): Contact number
• relationship (String): Relationship to patient
• geofence (Object, nullable):
• center_lat (Number): Latitude of geofence center
• center_lng (Number): Longitude of geofence center
• radius_m (Number): Radius in meters
• assigned_device_id (UUID, nullable): Reference to Device
• created_at (Timestamp)
• updated_at (Timestamp)

1.4 Device¶

• id (UUID): Unique identifier
• serial_number (String): Hardware serial number (format: GA-XXXXXX)
• firmware_version (String)
• public_key (String): Device's public key
• last_seen_at (Timestamp, nullable)
• battery_level (Integer, nullable): Percentage (0-100)
• status (Enum): [active, inactive, maintenance, retired]
• created_at (Timestamp)
• updated_at (Timestamp)

2. Event Data¶

2.1 Event¶

• id (UUID): Unique identifier
• patient_id (UUID): Reference to Patient
• device_id (UUID): Reference to Device that detected the event
• timestamp (DateTime): ISO 8601 timestamp
• event_type (Enum):
• fall: Fall detection event
• wandering: Wandering alert
• confidence (Number, 0-1): Detection confidence score
• location (Object, nullable):
• lat (Number): Latitude
• lng (Number): Longitude
• accuracy_m (Number): Accuracy in meters
• sensor_data (Object): Raw sensor data
• signature (String): Cryptographic signature
• status (Enum): [pending, acknowledged, resolved, false_positive]
• acknowledged_by (UUID, nullable): Reference to Caregiver
• acknowledged_at (Timestamp, nullable)
• notes (String, nullable): Caregiver notes
• created_at (Timestamp)

2.2 Proof Log¶

• id (UUID): Unique identifier
• event_id (UUID): Reference to Event
• merkle_root (String): Root hash of the Merkle tree
• previous_root (String): Previous Merkle root for chaining
• signer_id (UUID): Reference to Caregiver
• signed_at (Timestamp)
• signature (String): Digital signature
• block_height (BigInt): Position in the ledger

2.3 Sensor Data (Event Payload)¶

• accelerometer (Array[Float]): [x, y, z] in m/s²
• gyroscope (Array[Float], nullable): [x, y, z] in rad/s
• battery_level (Integer, 0-100): Device battery percentage
• signal_strength (Integer, 0-100): Signal strength percentage
• firmware_version (String): Device firmware version
• sampling_rate (Integer): Samples per second

3. Ledger & Exports¶

3.1 Ledger Entry¶

• id (UUID): Unique identifier
• previous_hash (String): Hash of the previous entry
• patient_id (UUID): Reference to Patient
• event_id (UUID, nullable): Reference to Event
• event_type (String): Type of event
• timestamp (Timestamp)
• data_hash (String): Hash of the event data
• signed_by (UUID): Reference to Caregiver
• signature (String): Digital signature
• merkle_root (String): Current Merkle root
• block_height (BigInt): Position in the ledger

4. Export Formats¶

4.1 EVV Export (CSV/JSON)¶

• patient_name (String): Full name
• patient_dob (Date): Date of birth
• caregiver_name (String): Full name
• event_type (String): Type of event
• event_time (DateTime): When the event occurred
• location (String): Address or coordinates
• status (String): Event status
• notes (String, nullable): Additional information

4.2 RPM Export (CSV/JSON)¶

• patient_name (String): Full name
• patient_id (String): Unique identifier
• date (Date): Service date
• time (Time): Service time
• duration_minutes (Integer): Duration in minutes
• service_type (String): Type of service
• device_used (String): Device identifier
• location (String): Service location

5. Audit Logs¶

5.1 Access Log¶

• id (UUID): Unique identifier
• user_id (UUID): Reference to Caregiver
• action (String): Action performed
• resource_type (String): Type of resource accessed
• resource_id (String): ID of the resource
• ip_address (String): IP address of the request
• user_agent (String): User agent string
• timestamp (Timestamp): When the action occurred
• status (Enum): [success, failure, denied]
• metadata (JSON, nullable): Additional context

6. Relationships¶

6.1 Patient-Caregiver¶

• One-to-many (one patient has one primary caregiver)
• Includes assignment history with timestamps
• Tracks active assignments only for MVP

6.2 Device-Patient¶

• One-to-one relationship when active
• Tracks current assignment only for MVP
• Includes assignment timestamps and reason

7. Data Retention¶

7.1 Raw Sensor Data¶

• Retention: 30 days
• Compression: GZIP
• Storage: Hot storage for 7 days, then cold storage

7.2 Event Data¶

• Retention: 2 years
• Immutable storage for all events
• Regular backups with integrity checks

7.3 Audit Logs¶

• Retention: 7 years
• Immutable storage
• Regular integrity verification
• Data formats
• Compression algorithms

8.2 Processing¶

• Data validation rules
• Transformation pipelines
• Quality metrics
• Error handling

8.3 Storage¶

• Database schemas
• Indexing strategy
• Partitioning scheme
• Backup procedures

9. Compliance Documentation¶

9.1 Data Protection¶

• Encryption standards
• Key management
• Access controls
• Audit requirements

9.2 User Consent¶

• Consent forms
• Data usage policies
• Withdrawal procedures
• Data portability

10. API Endpoints¶

10.1 Device API¶

• Device registration
• Data submission
• Configuration updates
• Status reporting

10.2 Caregiver API¶

• Patient management
• Schedule management
• Alert management
• Reporting

10.3 Family API¶

• Access requests
• Notifications
• Care updates
• Messaging

11. Webhook Events¶

11.1 Alert Webhooks¶

• Fall detection
• Wandering alert
• Emergency button press
• Device offline

11.2 Care Webhooks¶

• Visit started/ended
• Medication administered
• Care plan updated
• New message

12. Integration Points¶

12.1 EHR Integration¶

• HL7/FHIR standards
• Data mapping
• Authentication
• Rate limiting

12.2 Emergency Services¶

• Integration protocols
• Data sharing agreements
• Response procedures
• Testing schedule

13. Data Quality Metrics¶

13.1 Completeness¶

• Missing data rates
• Timeliness
• Coverage

13.2 Accuracy¶

• Validation rules
• Error rates
• Correction procedures

13.3 Consistency¶

• Cross-validation rules
• Data reconciliation
• Version control