Architecture Decisions & Migration Guide
AI Translation Notice
This page is an English translation of the authoritative Chinese ADR & migration guide. Refer to the Chinese version in case of discrepancies.
Key Architecture Decisions (ADRs)
- ADR-001 — Single State Authority: Each deployment binds exclusively to either native
AppConfigStoreDO or a remote state host (MODELBRIDGE_STATE_URL). Missing bindings/secrets fail closed with503instead of falling back across authorities. Remote RPC caps payloads at2 MiB(STATE_REQUEST_LIMIT) /16 MiB(STATE_RESPONSE_LIMIT). - ADR-002 — One-Time KV Bootstrap:
KVis checked only during initialAppConfigStore(app-config-v1) startup to import legacyconfig; all ongoing mutations serialize inside DO storage or SQLite WAL (synchronous = FULL,BEGIN IMMEDIATE). - ADR-003 — Explicit-Rejection Failover Only:
shouldRetryUpstreamtries at most 3 shuffled accounts exclusively on401/403/404/429. Timeouts (120s),5xx,> 32 MiBresponses, and invalid200payloads abort immediately, paired with Caddylb_retries 0. - ADR-004 — Explicit Platform Budgets:
PLATFORM_LIMITSinjects1 MiBbody caps (Makers) and4-fetch /9s/115slimits (ESA) into the request runtime so limits fail cleanly before isolate termination. - ADR-005 — Hardened Self-Hosted State:
src/self-hosted/server.mjsbinds loopback127.0.0.1:8788, verifiesnlink === 1andAPPLICATION_ID = 0x4d425331, enforcesMODELBRIDGE_STATE_TOKENXOR_FILE, and validates exact HTTPSMODELBRIDGE_STATE_ORIGINS.
Migration Runbook: Cloudflare state-service / DO -> Self-Hosted SQLite
sh
# 1. Export full config from the running remote state endpoint
MODELBRIDGE_STATE_URL="https://state.example/_modelbridge/state" \
MODELBRIDGE_STATE_TOKEN="<32-to-512-char-token>" \
MODELBRIDGE_STATE_EXPORT_ORIGIN="https://gateway.example" \
node tools/state-admin.mjs export-remote --out ./migration-config.json
# 2. Import into a fresh, empty SQLite database (<= 16 MiB + 1 KiB file envelope)
node tools/state-admin.mjs import \
--db ./data/modelbridge.sqlite \
--file ./migration-config.json
# 3. Create an online consistent snapshot (DELETE-mode single file) for routine backups
node tools/state-admin.mjs backup \
--db ./data/modelbridge.sqlite \
--out ./backups/modelbridge-snapshot.sqliteExport files contain plaintext upstream secrets and
apiKeys; store in restricted paths and remove after import.
- Start
dist/self-hosted-state/behind your HTTPS proxy, add all gateway HTTPS origins toMODELBRIDGE_STATE_ORIGINS, pointMODELBRIDGE_STATE_URLon each edge deployment to the new endpoint, and verify/adminplus one live key-revocation cycle.