Architecture & Systems
High-level systemic overview of ClashX monorepo and service layer.
Architecture Topology
ascii
+-----------------------+
| User (Web/Mobile) |
+-----------+-----------+
|
+-----------v-----------+
| Next.js 16 Frontend |
| (React 19 + TW CSS) |
+-----------+-----------+
|
+-----------------+-----------------+
| |
+----------v----------+ +----------v----------+
| Privy Auth Layer | | FastAPI Backend |
| (Wallet Connect) | | (Python 3.11+) |
+---------------------+ +----------+----------+
|
+----------------------------------------+-----------------------------+
| | | | |
+----------v---+ +--------v------+ +-----v------+ +----v--------+ +--------v-------+
| Supabase | | Pacifica REST | | Pacifica | | TrollLLM / | | Telegram Bot |
| PostgreSQL | | API | | WebSocket | | OpenAI API | | (Notifications)|
| (30+ tables) | | (Orders, Mkt) | | (Realtime) | | (Copilot) | | (Notifications)|
+--------------+ +---------------+ +------------+ +-------------+ +----------------+
+----------------------------------------------+
| Background Workers (5) |
| Bot Runtime | Copy | Snapshot | Portfolio |
| Backtest |
+----------------------------------------------+Technology Stack
Frontend
- Next.js 16.1 + React 19
- Tailwind CSS for styling
- xyflow for Bot Builder
- Framer Motion for animations
- Privy for embedded wallets
Backend
- Python 3.11+ backend
- FastAPI web framework
- Pydantic data modeling
- Solders for Solana primitives
Infrastructure
- Supabase Postgres + REST API
- Vercel for Next.js deployments
- Railway for API & Workers
Background Workers
ClashX runs five background workers that handle asynchronous processing using a lease-based coordination system:
BotRuntimeWorker
Core bot execution loop. Evaluates rules and submits orders.
BotCopyWorker
Monitors source bot execution events and replicates them to followers.
BacktestJobWorker
Processes queued backtest jobs asynchronously.
PortfolioAllocatorWorker
Monitors portfolios for drift and triggers automatic rebalancing.