High-Level System Design

Status: draft for alignment

Audience: product, frontend, backend, design, and ops stakeholders

Related docs: Implementation Roadmap, Backend Overview, User Service + Auth, Terminal Integration, Clash Of Clones Product Spec

Purpose

This document defines the system's high-level domain boundaries: the major components, the logic and state each owns, and the interfaces between them.

It is intentionally high level. The goal is to align on domain ownership and system shape without locking detailed API contracts or storage schemas.

System Map

Pump Party should be one product surface backed by one application backend. The frontend should go through the backend API for product state, and backend modules should own domain truth behind that API.

Source diagram: Pump Party High-Level System Design

Detailed Operational View

The diagram below is a more detailed companion view of the same system shape. It expands the prop trading, audition lifecycle, frontend API, and high-security service boundaries that are summarized in the high-level map above.

Interpret this diagram with two boundary clarifications:

• Frontend blockchain interactions are wallet-signed user actions, but backend product state still flows through the Backend API. Purchases, eligibility, clone state, contest state, and payouts must be observed, validated, and reconciled by backend-owned services.
• The internal platform/orchestration service coordinates flows across competitions, but product money rules belong to EconomyService. The platform layer should provide runtime primitives and orchestration glue, not become the source of truth for purchases, betting, payout, or settlement logic.

Main Components

These are conceptual boundaries first. They do not imply separately deployed services.

Component	Owns	State
Frontend Web App	Product UI, wallet connection UI, workflow editing, dashboards, and local interactions.	Local drafts, cached API responses, and ephemeral UI state.
Backend API	The single frontend-facing API boundary for auth, product state, trading views, lifecycle views, and admin operations.	Minimal durable state; request logs and audit metadata where needed.
UserService + Auth	Backend user identity, wallet signing auth, sessions/JWTs, wallet mappings, and ownership checks.	Users, linked wallets, auth challenges, sessions, and ownership references.
TerminalIntegrationService	MegaETH Terminal profile linking, authorization status, optional points/rank display, and broad Terminal messaging.	Terminal connections, encrypted OAuth token metadata, profile snapshots, and sync timestamps.
EconomyService	Purchases, clone purchase rules, audition retries, future tickets, prize pools, rewards, and settlement accounting.	Purchases, balances/credits, tickets, prize pools, payouts, fees, and settlement ledger entries.
CloneService	Clone records, user ownership, public clone identity, private strategy configuration, and strategy versions.	Clones, ownership links, strategy configs, strategy versions, and public clone profiles.
ContestLifecycleService	Auditions, arena/race lifecycle, promotion, qualification, retirement, Hall of Fame transitions, and result consumption.	Auditions, contests/races, entries, lifecycle status, qualification state, and finalized results.
DataIngestionService	Market/source data ingestion, source health, asset registry, derived market features, and market memory.	Source snapshots, asset registry, source health, normalized market data, and derived features.
AITradingEngine	Decision context assembly, model calls, decision runs, and proposed trading actions.	Decision runs, context snapshots, prompt/model outputs, and proposed actions.
Prop Trading Interface	Contract boundary for creating/reading prop accounts, submitting decision actions, and reading prop-owned results.	Contract types, endpoint shapes, and compatibility expectations; minimal durable state.
PropTradingEngine	Prop accounts, execution validation, simulated fills, positions, equity, PnL, ledgers, and trading results.	Prop accounts, orders/fills, positions, balances, PnL, ledgers, and account result summaries.
Platform Layer	Runtime concerns shared by all modules: routing, jobs, migrations, idempotency, config, secrets, logs, metrics, backups, and adapters.	Config, migrations, job metadata, idempotency records, logs/metrics, backup metadata, and adapter credentials.
Operational Store	Source of record for compact backend-owned operational state.	Database files/records and backup snapshots.
External Systems	Wallet/MOSS, blockchain rails, market APIs, LLM providers, object storage, and future payment providers.	External provider state and immutable artifacts referenced by backend-owned records.

Boundary Rules

• The frontend talks to the Backend API, not directly to backend storage or core provider accounts.
• The HLD defines the API boundary, not full route contracts. Detailed route paths, request/response DTOs, pagination, and error codes should be defined per vertical slice.
• Domain modules own product meaning; external systems are adapters unless explicitly promoted to a source of truth.
• UserService + Auth converts wallet proof into backend identity. Other modules should mostly depend on backend IDs, not raw wallet addresses.
• TerminalIntegrationService links Pump Party users to MegaETH Terminal profiles for points attribution and display. It should not own Pump Party sessions or product authorization.
• CloneService owns canonical clone and strategy configuration. AITradingEngine may snapshot config for execution traces, but it should not own the source config.
• ContestLifecycleService coordinates auditions and races. It can ask the prop engine to create or run accounts, but it should not own fills, balances, or PnL.
• EconomyService owns money-like product accounting: purchases, retries, tickets, pools, rewards, and settlement obligations.
• Prop Trading Interface is the contract boundary that lets AI and lifecycle work integrate with prop accounts without depending on prop engine internals.
• PropTradingEngine owns the authoritative trading ledger and result calculations for simulated/prop accounts.
• The platform layer provides shared runtime primitives; it should not accumulate product rules.

State Ownership

The backend should be the system of record for product and runtime state.

• Use backend-owned IDs such as userId, cloneId, strategyVersionId, decisionRunId, propAccountId, and contestId.
• Use wallet addresses as identity inputs, not as the universal primary key across the system.
• Store large immutable artifacts, raw payloads, prompt/model archives, and backups outside SQLite.

Prototype Infrastructure Direction

Prototype with a single backend instance and SQLite as the operational store.

After the domain boundaries, integration flows, and performance profile are clearer, re-evaluate whether any data or service boundary should move into a separate service, managed database, or independently scalable infrastructure.