Pump Party Docs

This is the front door for Pump Party product specs, backend module docs, the frontend API contract, and data-source reference material.

Use product specs to understand what should exist. Use module docs to understand what the code currently does.

Start Here

Need	Read
Run the local app stack	Development Quick Start
Frontend onboarding	Frontend Integration Guide
What is shipped and what is next	Implementation Roadmap
Backend code ownership	Backend Overview
Product loop and economy rules	Clash Of Clones Product Spec

Quick Start

For local app development, start the backend API and rewritten frontend as separate processes:

cd backend && npm run db:migrate && npm run api
cd frontend && pnpm run dev

See Development Quick Start for install steps, frontend env, optional workers, VitePress docs commands, and verification checks.

For a fuller local runtime, start market ingestion and the remaining background worker group in separate terminals:

cd backend && npm run workers:all
cd backend && npm run ingest:local

workers:all starts prop decisions, mark-to-market, backtests, audition evaluation, and Arena Entry sync in one terminal. Run market ingestion separately with npm run ingest:local for local development or npm run ingest for production.

In production, long-running workers should be deployed as supervised processes, not started manually in one shell. A typical enabled stack is frontend, backend API, full ingestion, prop decisions, mark-to-market, backtests, audition evaluation, and Arena Entry sync. npm run decisions:worker is clone-scoped/debug-oriented; prefer npm run prop:decisions:worker for production prop-account trading unless clone-scoped decisions are intentionally enabled.

Run one instance of each cadence worker unless the worker has explicit lease/concurrency controls. Monitor worker process health through GET /api/v1/internal/health/workers; ingestion source health is tracked separately through ingestion status/check commands.

Product Specs

These docs describe product language, user-facing controls, and target behavior.

• Clash Of Clones Product Spec
• Domain Language
• Product Controls
• Capacity And Model Tiers

Module Docs

These pages are code-aligned backend references. They should answer what a module owns, how its runtime flow works, which files/tables/routes/workers matter, how failures/retries/idempotency behave, known gaps, and tests to run.

Module	Current responsibility
Backend Overview	Backend module map, runtime files, and boundary rules.
User/Auth	Wallet identity, SIWE challenges, sessions, and user resolution.
Clone Service	Clone records, strategy drafts/versions, entitlements, public profile, moderation.
Data Ingestion	Global market memory, source clients, ingestion runs, and health APIs.
AI Trading	Strategy compilation, market context, prompts/model calls, decision runs, proposed actions.
Backtesting	Replay job state, metrics, usage policy, artifacts, and cost-control boundaries.
Prop Trading	Prop accounts, safety gates, paper fills, positions, balances, ledger, snapshots.
Economy	Economy V1 audition fee/payment facts now; Economy V2 competition tickets/settlement later.
Lifecycle	Paid audition orchestration now; races, tickets, settlement, and retirement later.
Operations/Workers	Worker entrypoints, migrations, heartbeat health, and run commands.

Frontend API

The top-level API contract is only the frontend/client HTTP boundary. Module-specific contracts live in the owning module docs above.

• Client API Contract
• Client API Reference

Data Sources

V1 market context comes from three source families:

Source	Stored context
Hyperliquid	OHLCV, mid prices, funding, liquidity, volatility, positioning, indicators.
Polymarket	Live/upcoming market discovery and asset-linked market context.
DefiLlama	TVL/base capital, flow changes, DEX volume, fees, revenue, open interest.

Supporting ingestion references:

• Data Sources Overview
• SQLite + R2 Market Memory
• Ingestion Operations Runbook
• Runtime Contract
• Data Source API And UX Spec

Architecture / Design

These docs capture higher-level design decisions and integration direction.

• High-Level System Design
• User Service + Auth
• Economy Service
• Terminal Integration
• OpenAPI Contract Migration

Current Backend Status

Area	Status	Remaining
Data ingestion	Hyperliquid, Polymarket, DefiLlama storage, scheduled feature channels, and source health APIs are in place.	Prod prep tracked in Production Readiness.
Clone Service	Clone create/list/read/update, strategy drafts/versions, graph persistence, layout metadata, entitlement enforcement, public profile, reporting, and moderation are in place.	Frontend integration.
AI trading	Context resolver, model/no-op engines, prompt v1, decision rows/actions, dry-run debug, prop-account per-asset cadence/audit, prop-action submission, token usage, artifact store, and topology guardrails are in place.	Prod prep tracked in Production Readiness.
Backtesting	Durable async jobs, worker queue leases, global/per-user concurrency controls, comparable metrics, daily usage counters, tier-aware quotas, preflight/history APIs, per-run caps, artifact retention, and Prop Trading fill-math reuse are in place behind clone-scoped compatibility routes.	Frontend history/comparison UI and final pricing policy.
Prop trading	Prop accounts, safety gates, paper fills, positions, balances, mark-to-market, snapshots, admin controls, and decision-action intake are in place.	Ops hardening and race-mode result consumption.
Economy V1 (Audition)	Audition fee quotes, post-transaction deposit confirmation, purchase idempotency, and entitlement grants are in place.	Prod prep tracked in Production Readiness.
Lifecycle V1 (Audition)	Paid audition submit/evaluate/retry/void is in place; owner-safe audition routes use backend user auth; due-audition evaluator worker exists.	Frontend status/retry UI and production evaluator monitoring are tracked separately.
Competition Manager V1 (Arena Entry)	Promotion Queue and Arena membership tables, public read routes, service-token sync, worker cadence, approved-profile admission gates, and admin removal/retirement controls are in place.	Backend-complete for Arena Entry V1; race launch belongs to later competition lifecycle work.

Runtime Pipeline

The current audition/runtime path is:

1. Global source ingestion
2. SQLite market memory
3. Clone strategy graph compilation
4. Per-strategy asset expansion
5. Deterministic context retrieval
6. Trading prompt assembly
7. Prop-account decision worker creates one due run per asset
8. Decision engine proposes an action for that asset
9. Prop Trading validates or rejects the action with safety gates
10. Valid executable actions paper-fill against latest Hyperliquid mid prices
11. SQLite decision/action/order/fill/position/ledger storage
12. Decision artifact store archives large audit payloads when configured

Local worker commands:

cd backend
npm run workers:all
npm run decisions:run-once -- --clone-id=42 --force
npm run decisions:worker
npm run prop:decisions:run-once
npm run prop:decisions:worker
npm run prop:mark-to-market:once
npm run prop:mark-to-market:worker
npm run backtests:run-once
npm run backtests:worker
npm run lifecycle:auditions:evaluate-due
npm run lifecycle:auditions:worker
npm run lifecycle:arena-entry:run-once
npm run lifecycle:arena-entry:worker