Domain Model - jbrucker/home-log GitHub Wiki

Initial domain model

classDiagram
    User --> "*" DataSource: owns
    DataSource <-- "*" Reading: values from
    DataSource --> "0..1" Location

    class User {
        email: EmailStr
        username: string
        created_at: Datetime
        updated_at: Datetime

    }
    class DataSource {
        name: string
        description: string
        owner: User
        metrics: Map[string,string]
    }
    class Reading {
        timestamp: Datetime
        created_by: User
        values: Map[string,Any]
    }
    class Location {
        name
        address
        coordinates?
    }

The implementation of these models also has an id attribute that isn't shown here (not part of domain model).

The metrics in DataSource is a dict of measurement_name: unit_name for values read from the data source. Use a dict even if there is only one value per reading, e.g. electric meter.

Reading.values is a dict of measurement_name: value, where value is the actual (numeric) value of some measurement, and measurement_name matches one of the keys in the corresponding DataSource.metrics dict.

The timestamp is the date/time of the reading value, which may not be same as when the values were entered (created_at).

Possible Names for the Reading Values Descriptor Field in DataSource

Suggested Name	Rationale
value_units	Clear, concise. Maps "value name" → "unit".
units	Emphasizes that the dict contains the unit for each measurement.
measurement_units	Semantically clear; aligns with concept of "measured values and their units".
reading_units	Suitable if each value is a readout from a device or sensor.
value_definitions	General but semantically appropriate if additional metadata might be added.
metrics	Very concise, though slightly abstract; common in telemetry contexts.
reading_format	Suggests how readings are structured; suitable if used for validation.
value_schema	Indicates both the names and expected units, with potential extensibility.
reading_schema	Same intent as value_schema.
schema	If the dict defines the structure of readings, this is a semantically rich choice.

Which to Choose?

• value_schema or reading_schema clearly describe the purpose of the dictionary, and good if the schema is expanded to include metadata, e.g. valid range of values.
• metrics has advantage of being short and unique in the application. Easy to code or refactor.