ADR 0001: Station Domain Model

Status: Accepted Date: 2026-05-19

Purpose

Define the Autimit station domain model used by the API, CSMS, dashboard, mobile app, and PostgreSQL database.

Domain Terms

Station Provisioning

Station provisioning starts in the Autimit API.

The API creates a station and returns provisioning data once:

{
  "station": {
    "id": "uuid",
    "stationCode": "AUTIMIT_STATION_CODE",
    "ocppConnectionUrl": "wss://ws.autimit.com/ocpp/1.6/AUTIMIT_STATION_CODE"
  },
  "provisioning": {
    "stationCode": "AUTIMIT_STATION_CODE",
    "ocppConnectionUrl": "wss://ws.autimit.com/ocpp/1.6/AUTIMIT_STATION_CODE",
    "stationSecret": "ONE_TIME_SECRET"
  }
}

Rules:

• stationSecret is shown only once.
• Only stationSecretHash is stored.
• stationCode must be unique.
• A station must belong to an account.
• A station must belong to a location.
• A station may have one or more connectors.

API Surface

Initial API endpoints:

POST /api/stations
GET /api/stations
GET /api/stations/:id

Request fields for station creation:

{
  "accountId": "uuid",
  "locationId": "uuid",
  "stationCode": "AUTIMIT_STATION_CODE",
  "serialNumber": "SERIAL_NUMBER",
  "manufacturer": "MANUFACTURER",
  "model": "MODEL",
  "connectors": 1
}

PostgreSQL Model

Time-series storage and current-state/event-history rules are defined in ADR 0002: Timeseries Data Model.

Initial foundation tables:

accounts
locations
stations
station_connectors
station_runtime_state

accounts

Represents the business owner or tenant that owns locations and stations.

Required fields:

• id
• name
• document
• is_active
• created_at
• updated_at

locations

Represents a physical place where stations are installed.

Required fields:

• id
• account_id
• name
• address
• latitude
• longitude
• is_public
• is_active
• created_at
• updated_at

stations

Stores stable station registration data.

Required fields:

• id
• account_id
• location_id
• station_code
• station_secret_hash
• serial_number
• manufacturer
• model
• connectors
• is_active
• created_at
• updated_at

Rules:

• account_id references accounts.id.
• location_id references locations.id.
• station_code is unique case-insensitively.
• connectors must be greater than zero.
• This table should not store frequently updated online/offline state.

station_connectors

Stores connector configuration for each station.

Required fields:

• id
• station_id
• connector_number
• connector_type
• max_power_kw
• is_active
• created_at
• updated_at

Rules:

• station_id references stations.id.
• connector_number is unique per station.
• max_power_kw must be greater than zero.

station_runtime_state

Stores frequently updated CSMS state for each station.

Required fields:

• station_id
• status
• last_heartbeat_at
• booted_at
• firmware_version
• last_error_code
• updated_at

Rules:

• station_id is the primary key.
• station_id references stations.id.
• status must use a constrained set of values.
• CSMS updates this table on connection lifecycle and station messages.

CSMS Connection Flow

Station connection path:

/ocpp/1.6/{stationCode}

Handshake:

1. Extract stationCode from path.
2. Validate Basic Auth username equals stationCode.
3. Find active station by stationCode.
4. Verify password against stationSecretHash.
5. Accept WebSocket connection.
6. Bind connection to station.id.

Runtime persistence:

Implementation Order

1. Create PostgreSQL foundation tables.
2. Add API station provisioning.
3. Update CSMS station lookup and authentication.
4. Add connector runtime state.
5. Add charging session tables.
6. Add meter values storage.