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