Skip to content

Product and runtime

Baseline reference

This chapter describes the established product and runtime model. The current interface and native Companion boundary are documented on the final architecture page.

Product view

What Steady is designed for

Steady is intended to make change visible without turning everyday life into a mandatory questionnaire. Everything is voluntary. Unanswered values remain unknown and are not interpreted as zero, failure or an uncompleted habit.

Main areas of the interface

flowchart TD
    T[Today] --> J[Journal]
    T --> R[Recovery]
    T --> P[Patterns]
    T --> E[Explorer]
    T --> X[Toolbox / More]

    J:::read -->|chronological review| U[Stored data]
    R:::read -->|Counters, urges, triggers| U
    P:::read -->|possible relationships| U
    E:::read -->|time series| U

    classDef read fill:#eaf6f1,stroke:#5b9b82,color:#173d31
Area Guiding question Role
Today What would I like to record today? Input and autosave
Journal What happened when? Chronological review
Recovery How is my change area developing? Counters, urges, triggers, strategies
Patterns What may be moving together? Life Wheel, people, exercise, correlations
Explorer How does a single metric develop? Freely configurable charts
Toolbox / More What else do I need? Tasks, milestones, export, settings

Product boundaries

  • no diagnosis and no medical device,
  • no automatic relapse decision,
  • no mandatory account,
  • no telemetry and no Steady backend,
  • correlations are not described as causes,
  • the Companion has no write access to tracking data.

Sources in the repository


System architecture

Runtime model

Steady is a React application, built with Vite and packaged as an Android app through Capacitor. The browser serves as a development and test environment; Android is the actual product target.

A build capability boundary in src/product-variant.js creates the general-audience product variant when VITE_PRODUCT_VARIANT=general-audience. It removes the built-in Alcohol and Pornography/compulsive-sexual-behavior profiles, their counters and 12-Step resources from the effective runtime configuration. Inventory, favorite texts and Twelve Steps are also excluded from General Audience navigation and feature chunks. Matching stored records are not passed to the interface in this variant, but they are not deleted. Both variants therefore retain a compatible schema.

The variant boundary also applies to initial configuration: general-audience uses the explicit canonical set in src/initial-user-config.js, with six general sections and 21 active fields. The Recovery variant uses its own canonical set with seven sections and 25 active fields. Browser and Android SQLite receive the same variant-specific seed. An initialConfigurationId marker prevents compatibility normalization from filling the clean Recovery start with absent v5 fields again; historical definitions that are actually present remain preserved.

Sample data follows the same boundary. src/data/demo-data.js contains only the neutral General Audience history. src/data/recovery-demo-data.js adds urges, triggers, urge-free check-ins, relapses and atomically linked resets for Recovery. Both variants provide a 90-day and a 1,095-day history. Every record carries source: "demo" so removal does not touch real data or Companion memories.

flowchart TB
    UI[React views and dialogs]
    APP[App state and application logic]
    SVC[Services: tracking, export, Companion]
    DB[db.js – shared data abstraction]
    IDX[(IndexedDB<br/>browser/test)]
    NATIVE[native-database.js]
    CAP[Capacitor plugin]
    SQL[(encrypted SQLite database)]

    UI --> APP --> SVC --> DB
    DB -->|Browser| IDX
    DB -->|Android| NATIVE --> CAP --> SQL

Phone-hosted HTTPS server

Optional PC entry uses a separately built browser client without IndexedDB, export or sync. PcEntryService serves it over HTTPS on the phone's private Wi-Fi IPv4 address, port 1111. A visible connectedDevice foreground service and CPU/Wi-Fi locks maintain explicitly started access. A self-signed certificate, pairing code, cookie session and CSRF/Host/Origin checks protect the network boundary.

The TLS key manager supplies the same Android Keystore identity through both socket and engine callbacks. Modern Android Conscrypt sockets use the engine callback; missing it aborts the handshake before a browser certificate warning. A loopback instrumentation test verifies TLS 1.2 with the pinned certificate. The v2 RSA identity allows DIGEST_NONE and raw RSA padding so Conscrypt can sign its precomputed TLS digest; RSA decryption is authorized for TLS compatibility. First start replaces the incompatible v1 PC certificate and changes its fingerprint; tracking encryption keys and provider credentials stay intact.

PcEntryCheckins allows current daily fields for today and seven previous days. Definitions, options, date window and weekday rules are validated natively before each write. Weekday numbering uses Monday = 0 through Sunday = 6. The PC uses the phone's same stored filter without converting it; [5, 6] hides Saturday/Sunday, not Friday. Server and Capacitor share the synchronized EncryptedRecordStore abstraction; SQLite schema and AES-GCM are unchanged. A cell write retains other and historical values. Stale revisions or phone autosaves are rejected as conflicts, never silently combined. The additional read route GET /api/analytics returns an allowlist of historical typed field values and field versions, numeric event data, referenced catalog labels/weights and counter start/reset dates for active selected areas. General Audience filtering is retained. Free text is represented only by presence for explicitly enabled text counts; journal content and event notes, reasons and reactions remain outside this analytics route.

Entry also projects contacts, exercise, self-care, urges, triggers and explicit zero check-ins for the eight-day window, including their editable prose. POST /api/event validates event types, section/date rules, selected areas, counter ownership and schema/event revisions. PcEntryEvents commits the event, catalogue creation/reactivation, zero replacement and associated resets in one encrypted-store transaction. Relapse saves require confirmation; relapse deletion is rejected. Stable mutation IDs protect retries against duplicate events and resets. The shared forms have no browser database dependency, and open drafts retain their original preconditions. Standalone counter changes remain on the phone.

Explorer, Life Wheel and correlations use the same React components and calculations as the phone app. CorrelationCacheContext supplies a database cache only on the phone; the PC computes in memory. Shared calendar axes show gaps, and selecting a period opens its recorded values beside the charts. Comparison periods do not overlap. PC selections remain session-only; visible analytics refresh every 15 seconds without reloading history for an unchanged revision. The phone's day determines counters and the default period. Chats, tokens, provider data, backups, Inventory and tasks have no PC API route. Native screen-off reachability has not yet passed acceptance.

PC configuration transaction

The PC Configuration view stages sections, current fields and Life Wheel axes in RAM, with grouped local undo/redo history. The visual workspace has a source library, central wheel/section lanes and an inline inspector. Inspector controls update the shared draft without a modal or second Save step; only Apply commits. Fixed axis targets stay operable without scores, and ambiguous field-to-axis drops require a concrete section choice or creation. GET /api/configuration returns an allowlisted editable projection with a revision, field-version metadata, editor options and derived axis-removal capabilities that protect retained excluded sections. Historical/excluded definitions and unrelated runtime settings are never editable through it. POST /api/configuration checks the session, CSRF, Host/Origin, configuration revision, mutation identity and every definition/reference before writing. Fields, sections and runtime-config groups/axes commit in one encrypted-store transaction; a revision conflict, validation rejection or transaction failure changes nothing. Mutation receipts remain in a bounded server-RAM map.

The server validates new stable IDs and owns replacement IDs/version metadata. A history-sensitive definition change follows field-model.js: retired definitions remain unchanged and a replacement keeps the logical identity. Retry with the same mutation identity and request fingerprint does not repeat a committed change. The browser replaces its baseline only with the canonical confirmed response. Phone refresh loads the updated fields, sections and runtime configuration; stale configuration drafts must not overwrite a concurrent PC change. A phone definition edit that was planned without history also asserts that no value has appeared before its batch commits. A first PC entry arriving meanwhile causes a conflict, preserving both the recorded value and its definition.

Draft scores reuse read-only analytics and the shared scorer. Simulated versions keep historical type, range, goal and section, while importance follows the current logical field. Section-to-axis changes apply to retained section history. No browser database, native encryption/schema change, external provider request or generic metadata writer is added.

Layers and responsibilities

Layer Responsibility Examples
Views Presentation and interaction TodayView, RecoveryView, AnalysisViews
App orchestration Navigation, state, dialogs, data transfer App.jsx
Services Atomic domain operations tracking-service.js, export service
Data abstraction Reading, writing, migration, browser/Android switching db.js
Native boundary SQLite, Keystore, privacy, local AI Capacitor plugins

Why use a generic record store?

The native SQLite database uses logically separated stores but saves the actual objects as encrypted JSON payloads. This fits the configurable field structure: a new field does not automatically require a new SQL column.

Atomic operations

An urge with a relapse can create one event and several counter resets at the same time. These changes are written with applyBatch in one transaction. There is therefore no intermediate state in which the relapse has been stored but the counter has not yet been reset.

Native managed-device tests force failures after writes have already started for putMany, store replacement, applyBatch, full-store import and plaintext migration. All original records must remain unchanged afterwards. A manipulated data-key envelope or a replacement Android Keystore key is rejected; Steady neither overwrites the existing envelope nor resets the database automatically.

sequenceDiagram
    participant UI as Urge dialog
    participant S as tracking-service.js
    participant DB as db.js / applyBatch
    participant Store as events + resets

    UI->>S: store payload
    S->>S: prepare event and reset records
    S->>DB: one batch operation
    DB->>Store: commit everything
    Store-->>UI: success or complete failure

Sources