Skip to Content
Getting Started

Getting Started

Overview

This guide will walk you through setting up the Strategy Execution Platform on your local machine. By the end, you’ll have a fully functional development environment with all services running.

Prerequisites

Before you begin, ensure you have the following installed:

  • Docker and Docker Compose - For running infrastructure services
  • Python 3.13+ - The main backend language
  • Rust toolchain - Via rustup for the performance core
  • uv - The Python package manager (pip install uv)
  • Node.js 18+ - For the frontend development server

Quick Start

Step 1: Clone the Repository

git clone <repository_url>
cd <repository_directory>

Step 2: Configure Environment

Copy the example environment file and customize it:

cp .env.example .env

Open the .env file and ensure the default ports for the database, Redis, etc., are free. You will also need to add an Ethereum RPC URL (e.g., from Infura or Alchemy) for the chain monitor to connect to.

Step 3: Start Infrastructure

This command uses Docker Compose to spin up TimescaleDB, Redis, NATS, and Ray:

make docker-up

You can verify that all containers are running with docker ps.

Step 4: Install Dependencies & Build Rust Core

This command will install all Python dependencies using uv and then compile the Rust extensions via maturin:

make build

Step 5: Run the Platform

This command starts the main FastAPI application:

python main.py

You should now be able to access the API at http://localhost:8000 and the auto-generated docs at http://localhost:8000/docs.

Step 6: Run the Frontend

Navigate to the frontend directory and start the development server:

cd <frontend_directory>
npm install
npm run dev

You can now access the dashboard at http://localhost:3000.

Development Environment Details

Infrastructure Services

The platform uses several infrastructure services that are managed via Docker Compose:

  • TimescaleDB: PostgreSQL extension optimized for time-series data
  • Redis: High-performance in-memory data store for caching and read models
  • NATS: Lightweight messaging system for real-time communication
  • Ray.io: Framework for distributed Python applications

Backend Services

The backend consists of several Python services:

  • API Server: FastAPI application serving REST and WebSocket endpoints
  • Intent Manager: Handles intent submission and validation
  • Execution Planner: Creates execution plans from intents
  • Execution Orchestrator: Executes plans step-by-step
  • State Coordinator: Manages system state and event persistence

Frontend Application

The frontend is a Next.js 14 application with:

  • Real-time Dashboard: Live trading interface with WebSocket updates
  • Strategy Management: Interface for creating and monitoring strategies
  • Portfolio View: Real-time portfolio tracking and analysis
  • Intent Submission: Forms for submitting new trading intents

Project Structure

platform/
├── app/                    # Next.js frontend application
├── content/               # Documentation (this directory)
├── platform/              # Python backend code
│   ├── api/              # FastAPI routes and handlers
│   ├── core/             # Core business logic
│   ├── strategies/       # Strategy framework and examples
│   ├── types/            # Pydantic data models
│   └── streaming/        # Event streaming and NATS integration
├── src/                   # Rust performance core
├── docker-compose.yml     # Infrastructure services
├── .env.example          # Environment configuration template
├── main.py               # Backend entry point
├── next.config.mjs       # Next.js configuration
├── package.json          # Frontend dependencies
└── pyproject.toml        # Python dependencies

Configuration

Environment Variables

Key environment variables you may need to configure:

  • ETHEREUM_RPC_URL: RPC endpoint for Ethereum network access
  • DATABASE_URL: Connection string for TimescaleDB
  • REDIS_URL: Connection string for Redis
  • NATS_URL: Connection string for NATS messaging
  • JWT_SECRET: Secret for JWT token generation
  • PRIVATE_KEY: Private key for transaction signing (development only)

Docker Compose Configuration

The docker-compose.yml file defines the infrastructure services:

  • TimescaleDB: Port 5432
  • Redis: Port 6379
  • NATS: Port 4222
  • Ray Dashboard: Port 8265

Running Tests

Backend Tests

# Run all tests
pytest
 
# Run specific test file
pytest tests/test_intent_manager.py
 
# Run with coverage
pytest --cov=platform

Frontend Tests

cd app
npm test

Integration Tests

# Run integration tests that require infrastructure
pytest tests/integration/ --docker

Development Workflow

1. Start Infrastructure

make docker-up

2. Start Backend

# Terminal 1
python main.py

3. Start Frontend

# Terminal 2
cd app
npm run dev

4. Monitor Services

Common Development Tasks

Adding New API Endpoints

  1. Create a new route file in platform/api/
  2. Define your Pydantic models in platform/types/
  3. Add the route to the main FastAPI app
  4. Write tests in tests/

Creating New Strategies

  1. Inherit from BaseStrategy in platform/strategies/
  2. Implement the required abstract methods
  3. Add configuration schema to your strategy
  4. Test with the strategy framework

Adding New Market Venues

  1. Create a new adapter inheriting from VenueAdapter
  2. Implement the required interface methods
  3. Add venue configuration to the system
  4. Update tests and documentation

Troubleshooting

Common Issues

Issue: make build fails with Rust compilation errors

Solution: Ensure your Rust toolchain is up to date (rustup update). Run cargo clean inside the src/ directory to clear any cached artifacts and try the build again.

Issue: Application starts but cannot connect to NATS or Redis

Solution: Verify the infrastructure containers are running (docker ps). Use docker logs <container_name> to check for any startup errors within the services themselves.

Issue: Ray actors are failing to start

Solution: The Ray dashboard is accessible at http://localhost:8265. This UI provides detailed logs for each actor and can help diagnose resource allocation issues.

Issue: Frontend shows “offline” or WebSocket does not connect

Solution: Check the browser’s developer console for errors. This is often a CORS issue if the frontend and backend are on different origins.

Getting Help

  • Documentation: This documentation site
  • Code Issues: Check the GitHub repository issues
  • Community: Join our Discord or Slack channels
  • Logs: Check service logs for detailed error information

Next Steps

Now that you have the platform running locally:

  1. Explore the API: Visit http://localhost:8000/docs  to see all available endpoints
  2. Try the Frontend: Navigate to http://localhost:3000  to see the dashboard
  3. Read the Code: Start with the main entry points and follow the flow
  4. Build Something: Try creating a simple strategy or adding a new feature

Continue reading the documentation to understand:

Last updated on
Integration & OperationsDevelopment Guide