Backend Overview

Overview

The backend is one modular Node.js app with SQLite storage. Modules are ownership boundaries inside the same deployable runtime, not separate services.

HTTP code adapts requests into module calls. SQLite db/ code owns connections and migrations. Product/runtime rules should live in backend/src/modules/*.

Use this page for the high-level backend map. Use the module pages for the technical details that matter when changing or debugging a specific area.

Responsibilities

Area	Code location	Owns
User/Auth	backend/src/modules/user	Wallet identity, SIWE challenges, JWT sessions, refresh rotation, user resolution.
Clone Service	backend/src/modules/clone	Clone records, strategy drafts/versions, effective entitlements, public profiles, reports, moderation.
Data Ingestion	backend/src/modules/data-ingestion	Global market memory, source clients, ingestion run rows, source health summaries.
AI Trading	backend/src/modules/ai-trading	Strategy compilation, context packets, prompts/model calls, decision runs, proposed actions.
Backtesting	backend/src/modules/backtesting	Replay jobs, queue leases, usage policy, metrics, artifacts, retention.
Prop Trading	backend/src/modules/prop-trading	Synthetic accounts, safety gates, fills, positions, balances, ledger, mark-to-market, admin audit.
Economy	backend/src/modules/economy	Audition-fee quotes, SignedVault deposit verification, purchase facts, entitlement grants.
Lifecycle	backend/src/modules/lifecycle	Paid auditions, evaluation, retry/void/refund authorization, Promotion Queue, Arena admission.
Operations/Workers	backend/src/workers, backend/src/index.ts, backend/src/observability	Worker entrypoints, command routing, migrations, heartbeat health.

Boundary Rules

• api/ parses HTTP input, authenticates callers, maps errors to responses, and calls modules.
• api/routes/* can own route-family parsing, but durable state changes and product decisions belong in modules/*.
• db/ owns SQLite setup and migrations only; module repositories should sit beside the module that owns the tables.
• data-ingestion owns market memory. AI Trading and Prop Trading read it instead of opening their own source clients.
• ai-trading proposes decisions and records decision audit. It does not mutate balances, fills, positions, lifecycle results, or payment facts.
• backtesting can reuse AI Trading and Prop Trading logic, but it writes to backtest-owned jobs, metrics, and artifacts, not production prop-account truth.
• prop-trading owns synthetic execution truth. Lifecycle and future race code should use its services instead of mutating prop_* tables directly.
• economy owns payment and entitlement-grant facts. Clone Service owns the effective entitlement projection consumed by runtime guards.
• lifecycle owns competition state transitions. It should consume Prop Trading snapshots/results rather than duplicate execution math.

Runtime Flow

The current paid-audition runtime path is:

Global source ingestion
-> SQLite market memory
-> Clone strategy graph compile
-> Entitlement and topology checks
-> Per-asset context resolution
-> Prompt/model decision
-> Prop Trading safety gates
-> Paper fill, position, balance, ledger updates
-> Mark-to-market snapshots
-> Audition evaluation
-> Promotion Queue / Arena admission

The important split is that AI Trading decides, Prop Trading executes, and Lifecycle evaluates competition outcomes.

Main Code Paths

Path	Role
backend/src/index.ts	CLI command router for API, migrations, workers, and one-off commands.
backend/src/app/env.ts	Environment parsing and runtime defaults, including worker intervals.
backend/src/app/*	App-level dependency composition.
backend/src/api/server.ts	HTTP server composition and route dispatch.
backend/src/api/routes/*	Route-family adapters for auth, economy, lifecycle, prop trading/admin, public profiles, moderation.
backend/src/api/auth.ts	Bearer-session and service-token authentication helpers.
backend/src/db/*	SQLite connection and migration runner.
backend/src/db/migrations/*	Durable schema history.
backend/src/modules/*	Module services, repositories, policies, and domain logic.
backend/src/workers/*	Long-running and run-once worker entrypoints.
backend/src/observability/worker-heartbeats.ts	Worker heartbeat writes and health records.

State And Tables

Table ownership follows module ownership:

Module	Main table family
User/Auth	users, user_wallets, auth_challenges, sessions
Clone Service	clones, clone_strategy_*, clone_capacity_entitlements, clone_public_profiles, clone_reports
Data Ingestion	hyperliquid_*, polymarket_*, defillama_*, ingestion_runs
AI Trading	clone_decision_runs, clone_decision_actions, decision_artifacts
Backtesting	backtest_jobs, backtest_job_metrics, backtest_usage_days, backtest_artifacts
Prop Trading	prop_accounts, prop_orders, prop_fills, prop_positions, prop_account_balances, prop_ledger_events, prop_admin_audit_log
Economy	economy_purchases; grants write through Clone Service entitlement rows
Lifecycle	audition_runs, audition_refund_authorizations, promotion_queue_entries, arena_clone_memberships
Operations	worker_heartbeats

Routes And Workers

High-level route families:

Route family	Owner
/api/v1/auth/*, /api/v1/me	User/Auth
/api/v1/clone/*, /api/v1/public/clones/*, /api/v1/admin/moderation/*	Clone Service
/api/v1/assets, /api/v1/ingestion/*, /api/v1/polymarket/*, /api/v1/defillama/*	Data Ingestion
/api/v1/clones/:id/decision-runs, clone decision dry-run routes	AI Trading
/api/v1/clone/clones/:id/decision-backtest*	Backtesting behind clone-scoped compatibility routes
/api/v1/prop/*, /api/v1/admin/prop/*	Prop Trading
/api/v1/economy/*	Economy
/api/v1/lifecycle/*	Lifecycle
/api/v1/internal/health/workers	Operations

Primary worker commands:

cd backend
npm run ingest:local
npm run decisions:worker
npm run prop:decisions:worker
npm run prop:mark-to-market:worker
npm run backtests:worker
npm run lifecycle:auditions:worker
npm run lifecycle:arena-entry:worker

Run-once variants exist for decisions, prop decisions, mark-to-market, backtests, audition evaluation, and Arena Entry sync.

Failure Behavior

• Most long-running workers run migrations on boot, execute one cycle immediately, then sleep on their configured interval.
• Worker heartbeat rows track running, succeeded, or failed, last start/completion/error timestamps, latency, totals, and consecutive error count.
• GET /api/v1/internal/health/workers is service-token guarded and reports heartbeat staleness plus error counts.
• Backtest jobs use queue leases so expired running jobs can be requeued.
• Prop decision/action idempotency prevents duplicate execution for the same decision action.
• Economy purchase idempotency is keyed by SignedVault resolver address and deposit nonce.
• Ingestion source failures are recorded per source/channel in ingestion_runs; source schedulers continue where possible.

Debugging Notes

• Start with doc/index.md for docs navigation and doc/implementation-roadmap.md for shipped/missing status.
• Use backend/RUNBOOK.md for local process commands and operational checks.
• Check worker_heartbeats for worker process health and ingestion_runs for source/channel health.
• Check clone_decision_runs and decision_artifacts for AI decision audit before looking at Prop Trading execution state.
• Check prop_ledger_events when account balance, fill, or lifecycle state looks wrong.

Tests

cd backend
npm run typecheck
npm run test

Use narrower module test commands from each module page when touching one area.

Known Gaps

• Race lifecycle tables and workers for launch, live trading windows, settlement, retirement, and Hall of Fame.
• Economy V2 ticket purchase, race settlement, payout authorization, creator royalty, and protocol rake facts.
• Production worker supervision, alert routing, backup/restore checks, and reconciliation dashboards.
• Retry/dead-letter policy beyond current idempotency, heartbeat health, and backtest leases.
• Legacy clone-scoped execution/debug tables still exist for workflow debug compatibility.