binance-trading-bot: Instructions file for Codex

Engineering charter

Charter for any coding agent in this repo (Claude Code, Cursor, Codex, …). Keep it short — architecture, config, and ops live in docs/ (built by mkdocs). Generic engineering principles (think-first, simplicity, goal-driven): .claude/rules/principles.md.

Project

binance-trading-bot: single-operator, multi-account, multi-profile, reliability-first, mobile-first trading platform on Binance. One operator owns N first-class Binance accounts (each = one API key pair + one environment + one user-data stream); each account runs N strategy profiles against its shared wallet. Strategy is a plugin — trailing-trade is the first; source of truth is packages/strategy/trailing-trade/, contract in packages/strategy/core/ + docs/architecture/extensibility.md.

Architecture principles

Correctness first. Before coding, confirm the design is sound: surface tradeoffs, pick the simplest option that holds the invariants below, cite authoritative sources for any version/API claim, and push back rather than guess. Greenfield, not yet deployed — no back-compat debt, so prefer the correct extensible design over the minimal diff and restructure freely; the invariants still bind, and you name a large refactor before starting it.

Core invariants

1. Extensibility. Strategies are plugins behind packages/strategy-core; notifier providers behind @app/notify's ./providers/* subpath exports. apps/api/apps/worker MUST NOT import a specific strategy-* package or an @app/notify/providers/* provider outside their registry bootstrap; apps/web MAY import strategy packages for typed event payloads. Adding a strategy = new package + registry entry; adding a notifier = new provider module + buildNotifyRegistry entry — never an edit to apps/api/apps/worker.
2. Reliability. Crash-only. Idempotent jobs. Per-account Binance-rate isolation. No silent failures.
3. Approachable & responsive. Solo operator, not a finance pro: plain language, gloss a trading term the first time it appears, never assume off-screen knowledge. Mobile-first — every view usable at 375×667 — then scale up.
4. Account-scoped by row, not convention.
   • Model: one operator (users) → many accounts → many profiles. accounts.owner_id → users.id; each account holds one Binance key pair, one binance_mode, one user-data stream. profiles.account_id binds each profile to its account, sharing that account's key/wallet/stream.
   • Branded two-tier scope: AccountScope{db,operatorId,accountId} from scopeAccount, ProfileScope{db,operatorId,accountId,profileId} from scopeProfile — proves the ownership chain in one query. UserId and AccountId are distinct branded types (misplacing one won't compile).
   • Access rule: app code reaches account-scoped data ONLY through profileRepo(...) / profileRepoFromScope(scope) — or accountRepo(...) / accountRepoFromScope for account-level surfaces like api-keys — from @app/db. No manual (db, operatorId, …) threading; every account-scoped repo fn takes an AccountScope/ProfileScope first, minted only by scopeAccount/scopeProfile — ownership proven exactly once at compile time. Flat repo.<x> stays only for operator/global fns (repo.users.*, repo.accounts.create/listForOwner, retention sweeps).
   • Routes: API under /api/accounts/:accountId/..., web under /accounts/$accountId/....
   • Enforcement: packages/db/__tests__/repo/ast-check.test.ts + cross-account integration tests. No DB-side RLS. See docs/architecture/{account-isolation,database}.md.
   • Strategy state is per-(profile, symbol) in storage and in tick() — one slice per symbol per call. Cross-symbol state goes through the per-profile KV store: emit set-kv/delete-kv under a strategy-owned namespaced key and read the merged snapshot back via TickInput.profileKv (opt in with capabilities.needsProfileKv). A KV write lands for sibling symbols on later ticks, never the same tick.