ADR 0002: Timeseries Data Model

Status: Accepted Date: 2026-05-19

Purpose

Define how Autimit stores current operational state and historical time-series data for stations, connectors, sessions, and meter values.

Storage Pattern

Autimit uses two storage patterns:

1. Current state tables.
2. Event/history hypertables.

Current state tables store the latest known value and are optimized for dashboard, app, and CSMS lookup.

Event/history hypertables store append-only telemetry and operational history.

Current State Tables

Current state tables are regular PostgreSQL tables.

They are updated by the CSMS whenever the latest known state changes.

Initial current state tables:

station_runtime_state
connector_runtime_state
charging_sessions

station_runtime_state

Stores the latest known station state.

Examples:

• online/offline/faulted status
• last heartbeat
• boot timestamp
• firmware version
• last error code

connector_runtime_state

Stores the latest known connector state.

Examples:

• available
• occupied
• charging
• suspended
• faulted
• unavailable

charging_sessions

Stores the operational and financial state of a charging session.

Examples:

• active session status
• user
• station
• connector
• meter start
• meter stop
• started at
• stopped at
• billing state

Hypertables

Hypertables are used for append-only time-series data.

Initial hypertables:

station_heartbeat_events
station_boot_events
connector_status_events
meter_values
session_events

station_heartbeat_events

Stores heartbeat history.

Partition time column:

occurred_at

station_boot_events

Stores station boot history.

Partition time column:

occurred_at

connector_status_events

Stores connector status transition history.

Partition time column:

occurred_at

meter_values

Stores charging telemetry sent by stations.

Partition time column:

sampled_at

Expected measurements:

• energy Wh
• power W
• voltage V
• current A
• state of charge %

session_events

Stores charging session lifecycle events.

Partition time column:

occurred_at

CSMS Write Rules

CSMS writes both current state and history when needed.

Heartbeat:

UPDATE station_runtime_state
INSERT station_heartbeat_events

Boot notification:

UPDATE station_runtime_state
INSERT station_boot_events

Connector status change:

UPDATE connector_runtime_state
INSERT connector_status_events

Meter values:

INSERT meter_values

Session lifecycle event:

UPDATE charging_sessions
INSERT session_events

Retention And Compression

Retention and compression are configured per hypertable.

Initial policy:

Aggregated billing records must not depend only on raw telemetry retention.

Query Rules

Use current state tables for:

• map availability
• dashboard status
• station online/offline checks
• connector availability checks
• active session lookup

Use hypertables for:

• charts
• historical reports
• uptime analysis
• fault analysis
• energy analytics
• billing evidence

Implementation Order

1. Add regular current state tables.
2. Add TimescaleDB extension in infrastructure.
3. Create hypertables for station and connector events.
4. Create meter_values hypertable.
5. Add compression and retention policies.
6. Add continuous aggregates after dashboard/reporting queries are known.