Persistence
--trade and --serve write state under ~/.chartgen/ (Windows:
%USERPROFILE%\.chartgen\). The directory is created on startup if missing. Override by setting $HOME
before launch.
| File | Written by | Format |
|---|---|---|
alerts.json | set_alert, cancel_alert, fired alerts | JSON array, atomic replace |
trades.log | Order lifecycle + alert triggers | Append-only text |
subscriptions.json | subscribe_notifications, unsubscribe_notifications | JSON map keyed by token |
chartgen.db | /register and /token on the HTTP server; sign-in, when configured; scripted indicators, with CHARTGEN_SCRIPTING=1 (any mode); server alerts, with CHARTGEN_SERVER_ALERTS=1; each user’s workspace, with sign-in | SQLite, path from CHARTGEN_DB |
alerts.json
Section titled “alerts.json”Array of alerts awaiting evaluation. Each entry:
[ { "id": "8f3a…", "symbol": "BTCUSDT", "condition": { "PriceAbove": 50000 }, "created_at": "2026-04-19T12:00:00Z" }, { "id": "b21c…", "symbol": "ETHUSDT", "condition": { "IndicatorSignal": { "indicator": "cipher_b", "signal": "gold_buy" } }, "created_at": "2026-04-19T12:05:00Z" }]condition is a tagged enum with three variants:
{ "PriceAbove": <f64> }{ "PriceBelow": <f64> }{ "IndicatorSignal": { "indicator": "<name>", "signal": "<label>" } }
Writes use a .tmp + rename sequence so readers never see a partial file.
The engine only rewrites alerts.json when the set changes (add, remove, or
fire) — idle bars cost zero writes.
See the trading guide for the
valid signal labels.
trades.log
Section titled “trades.log”Append-only audit trail. One line per event, UTC timestamps:
2026-04-19T12:34:56Z SUBMITTED buy BTCUSDT 0.01 market id=abc1232026-04-19T12:34:57Z FILLED buy BTCUSDT 0.01 @ 67432.5 id=abc1232026-04-19T13:00:00Z CANCELLED id=def4562026-04-19T13:15:22Z ALERT_TRIGGERED id=ghi789 cipher_b/gold_buy BTCUSDT 1hEvent types:
| Prefix | Emitted by | Fields |
|---|---|---|
SUBMITTED | place_order | side, symbol, quantity, type, id=<order_id> |
FILLED | Exchange fill | side, symbol, quantity, @ <price>, id=<order_id> |
CANCELLED | cancel_order | id=<order_id> |
ALERT_TRIGGERED | Alert engine | id=<alert_id>, condition summary, symbol, interval |
There is no rotation — rotate or truncate externally if it grows too large.
subscriptions.json
Section titled “subscriptions.json”Persisted SSE push-notification filters, keyed by access token. Only
symbols and alert_types are stored; SSE senders and offline queues are
in-memory and rebuilt on reconnect.
{ "<token>": { "symbols": ["BTCUSDT", "ETHUSDT"], "alert_types": ["price_above", "indicator_signal"] }}Both fields may be null, meaning “match any”. Restarting the server
preserves filters so clients keep their filters across chartgen restarts, but
queued alerts are lost.
chartgen.db (OAuth clients, scripted indicators, server alerts and setups)
Section titled “chartgen.db (OAuth clients, scripted indicators, server alerts and setups)”Holds the registered OAuth clients, with or without CHARTGEN_SCRIPTING=1
(ADR-0036), and
the scripted indicators, which need it
(guide,
ADR-0025). The path is
CHARTGEN_DB, default ~/.chartgen/chartgen.db. The HTTP server opens it at
startup, creating the file and its directory, and applies pending migrations.
PRAGMA user_version counts the migrations applied. If it cannot be opened, the
server logs that and runs with clients in memory only. A migration runs in one transaction, so
one that fails leaves the file as it was: repair the cause and restart, and the clients and
everything else come back. A build without the default scripting cargo feature has no store
at all.
CREATE TABLE user_indicators ( user_id TEXT NOT NULL, -- owner: OAuth client_id, or with sign-in a users.id name TEXT NOT NULL, source TEXT NOT NULL, -- Starlark source as registered meta_json TEXT NOT NULL, -- {title, description, overlay, params} at register source_hash TEXT NOT NULL, -- SHA-256 hex of source (compile-cache key) created_at INTEGER NOT NULL, -- unix seconds updated_at INTEGER NOT NULL, PRIMARY KEY (user_id, name));CREATE TABLE oauth_clients ( client_id TEXT PRIMARY KEY, redirect_uris TEXT NOT NULL, -- JSON array created_at INTEGER NOT NULL, last_token_at INTEGER, -- migration 2; NULL = never got a token client_name TEXT -- migration 5; as registered, for the consent page);-- Migration 5, used with sign-in on (ADR-0044):CREATE TABLE users ( id TEXT PRIMARY KEY, -- github:<id> or google:<sub> name TEXT NOT NULL, -- display only, refreshed at each login created_at INTEGER NOT NULL, last_login_at INTEGER NOT NULL, last_token_at INTEGER -- with the login, what keeps their alerts alive);CREATE TABLE sessions ( token_hash TEXT PRIMARY KEY, -- SHA-256 hex of the cookie value user_id TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL);CREATE TABLE client_grants ( -- clients a user approved user_id TEXT NOT NULL, client_id TEXT NOT NULL, created_at INTEGER NOT NULL, PRIMARY KEY (user_id, client_id));-- Migration 7: refresh tokens (ADR-0058).CREATE TABLE refresh_tokens ( token_hash TEXT PRIMARY KEY, -- SHA-256 hex of the token; the value is never stored family TEXT NOT NULL, -- one authorization: SHA-256 hex of the part its tokens share; at most one row unspent seq INTEGER NOT NULL, -- position in the family client_id TEXT NOT NULL, user_id TEXT, -- users.id, or NULL when issued with sign-in off created_at INTEGER NOT NULL, spent_at INTEGER, -- when it was exchanged; 0: replaced by a retry before it was exchanged; NULL: usable access_hash TEXT -- migration 8; SHA-256 hex of the access token issued with it, while unspent);CREATE INDEX refresh_tokens_family ON refresh_tokens (family);-- Migration 3: server alerts (ADR-0042).CREATE TABLE server_alerts ( id TEXT PRIMARY KEY, owner TEXT NOT NULL, -- OAuth client_id, or with sign-in a users.id record_json TEXT NOT NULL -- definition and state, webhook URL and secret);CREATE TABLE server_alert_events ( -- deliveries not finished yet id TEXT PRIMARY KEY, -- the event id a receiver sees alert_id TEXT NOT NULL, body TEXT NOT NULL, -- the JSON payload created_at INTEGER NOT NULL -- unix seconds);-- Migration 4: browser push (ADR-0045).ALTER TABLE server_alert_events ADD COLUMN device TEXT; -- NULL: the webhookCREATE TABLE push_devices ( id TEXT PRIMARY KEY, owner TEXT NOT NULL, -- OAuth client_id, or with sign-in a users.id endpoint TEXT NOT NULL, p256dh TEXT NOT NULL, auth TEXT NOT NULL, created_at INTEGER NOT NULL, -- unix milliseconds UNIQUE (owner, endpoint));CREATE TABLE server_settings ( -- vapid_private_key, unless set by env name TEXT PRIMARY KEY, value TEXT NOT NULL);-- Migration 6: a signed-in user's workspace (ADR-0050).CREATE TABLE workspace_docs ( user_id TEXT NOT NULL, -- users.id key TEXT NOT NULL, -- the web app's localStorage key value TEXT, -- NULL: deleted, kept 90 days, the newest 1000 per user, -- so other devices learn of it version INTEGER NOT NULL, -- that user's sequence at this write updated_at INTEGER NOT NULL, -- unix seconds PRIMARY KEY (user_id, key));CREATE TABLE workspace_users ( user_id TEXT PRIMARY KEY, seq INTEGER NOT NULL, -- that user's last version bytes INTEGER NOT NULL -- their documents' total, for the limit);CREATE TABLE setups ( -- ADR-0059 id TEXT PRIMARY KEY, owner TEXT NOT NULL, -- OAuth client_id, or with sign-in a users.id record TEXT NOT NULL -- the setup as JSON, its current state);CREATE INDEX setups_owner ON setups (owner);CREATE TABLE setup_revisions ( setup_id TEXT NOT NULL, seq INTEGER NOT NULL, -- 1, 2, 3, ... per setup body TEXT NOT NULL, -- one log entry as JSON PRIMARY KEY (setup_id, seq));-- Three triggers on setup_revisions abort an UPDATE, a DELETE and an INSERT that-- would replace an entry, with "a setup's log is append-only".Setups
Section titled “Setups”A setup is one row in setups, rewritten as its status moves, and
its log is rows in setup_revisions. The log is only ever inserted into: the server has no
statement that updates or deletes an entry, and triggers in the database refuse one from anyone
else, along with a write that would replace an entry. A setup
and the entries it gained are written in one transaction. Closed setups stay; nothing deletes
them for inactivity. A row that cannot be read at startup is left where it is, counted in the
log line [setups] skipped N stored setups that cannot be read, and never scored.
record holds a thesis in clear text. Prices are stored as JSON numbers and read back as
exactly the numbers written.
A replay server keeps everything in memory, its OAuth clients included, and never opens this file.
A fire writes the alert’s new state and its delivery in one transaction, before
anything is sent, so a restart neither fires it again nor loses the delivery. A
delivery older than an hour is dropped. Spent alerts are deleted after 7 days, and those of an
owner with no token for 30 days too, unless the operator listed that owner. A user’s sign-in counts as well. record_json holds webhook URLs,
which may contain tokens, and signing secrets in clear text, because the server needs
them to send and sign. They are never returned or logged, but treat a copy of this file
as holding them.
On Unix, a directory that does not exist yet is created owner-only (0700), and an existing one keeps its mode. The file is created 0600, and an existing file is set to 0600 when the server opens it. These steps are best effort: a failure is not logged and the server carries on, for example when another user owns the file or the filesystem ignores modes. On Windows the server sets no permissions or ACLs, so the directory and file inherit theirs. The file holds client ids, scripts and webhook secrets, so check who can read it, especially on Windows or a mounted volume.
Clients with no token 24 hours after registering are deleted at startup and on each registration, unless they own scripts.
oauth_clients keeps dynamically registered OAuth clients across restarts,
so a client keeps its client_id, and with it any scripts. Access token values stay
in memory: after a restart the web app re-authorizes, and a client with a
refresh token is known again by the hash of
its access token. Clients that received a token
are only deleted when a registration at the
1000 client limit evicts them, which
spares any client with a live token, a refresh token or a row in user_indicators, or, with
CHARTGEN_SERVER_ALERTS=1, in server_alerts. Back up the file like any
SQLite database (sqlite3 chartgen.db ".backup copy.db").
refresh_tokens holds one row per refresh token handed out and not yet forgotten
(ADR-0058). An
authorization unused for 30 days is deleted at startup, as are all but the 2 newest spent
rows of one at each exchange. Rows go with their client, and when a token is
revoked. The table is written with
sign-in on and off. Deleting a client by hand should delete its rows here too; rows left
behind are ignored.
users, sessions and client_grants are empty until
sign-in is configured. Expired sessions, and
approvals of clients no longer registered, are deleted at startup. Provider tokens and
secrets are never stored, and neither are emails, except that a Google account without a
name is shown by its verified email. Deleting a user is by hand, with the server stopped:
their rows in these tables, user_indicators and server_alerts.
To remove a user’s workspace by hand, with the server stopped, delete their rows from both tables. Their devices then send what they still have as new, so sign them out first if it should stay gone:
DELETE FROM workspace_docs WHERE user_id = 'github:123';DELETE FROM workspace_users WHERE user_id = 'github:123';