Skip to content

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.

FileWritten byFormat
alerts.jsonset_alert, cancel_alert, fired alertsJSON array, atomic replace
trades.logOrder lifecycle + alert triggersAppend-only text
subscriptions.jsonsubscribe_notifications, unsubscribe_notificationsJSON 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-inSQLite, path from CHARTGEN_DB

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.

Append-only audit trail. One line per event, UTC timestamps:

2026-04-19T12:34:56Z SUBMITTED buy BTCUSDT 0.01 market id=abc123
2026-04-19T12:34:57Z FILLED buy BTCUSDT 0.01 @ 67432.5 id=abc123
2026-04-19T13:00:00Z CANCELLED id=def456
2026-04-19T13:15:22Z ALERT_TRIGGERED id=ghi789 cipher_b/gold_buy BTCUSDT 1h

Event types:

PrefixEmitted byFields
SUBMITTEDplace_orderside, symbol, quantity, type, id=<order_id>
FILLEDExchange fillside, symbol, quantity, @ <price>, id=<order_id>
CANCELLEDcancel_orderid=<order_id>
ALERT_TRIGGEREDAlert engineid=<alert_id>, condition summary, symbol, interval

There is no rotation — rotate or truncate externally if it grows too large.

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 webhook
CREATE 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".

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';