Local Development

This guide provides step-by-step instructions for setting up the TradeX platform for local development.

Prerequisites

• Docker and Docker Compose for infrastructure
• Node.js 18+ and Bun for TypeScript services
• Go 1.25+ for Go services
• Python 3.10+ and uv for Python services
• Rust (latest stable) for matching engine
• PostgreSQL 14+ (or use Docker)
• MongoDB (or use Docker)
• Redis (or use Docker)
• Kafka (or use Docker)

Quick Start

1. Clone Repository

git clone https://github.com/your-org/tradex.git
cd tradex

2. Start Infrastructure

cd infra
docker-compose up -d

This starts:

• PostgreSQL
• MongoDB
• Redis
• Kafka cluster
• Schema Registry
• Zookeeper

3. Initialize Services

# Run initialization script
./init.sh

4. Start Services

Each service can be started individually:

# Market Data Service (Go)
cd apps/marketdata-service
make run

# Order Service (TypeScript)
cd apps/order-service
bun run dev

# Auth Service (Python)
cd apps/auth-service
uv run uvicorn app.main:app --reload

# User Service (Python)
cd apps/user-service
uv run uvicorn app.main:app --reload

# Wallet Service (Python)
cd apps/wallet-service
uv run python -m app.main

# Metadata Service (Go)
cd apps/metadata-service
make run

# Matching Engine (Rust)
cd apps/matching-engine-rust
cargo run

# Backend Service (TypeScript)
cd apps/backend
bun run dev

Service-Specific Setup

Market Data Service

cd apps/marketdata-service

# Install dependencies
make deps

# Apply database schema
make atlas-schema-apply

# Generate SQLc code
make sqlc-generate

# Generate Avro code
make avro-generate

# Run service
make run

Order Service

cd apps/order-service

# Install dependencies
bun install

# Run database migrations
bun run migrate

# Run service
bun run dev

Python Services (Auth, User, Wallet)

cd apps/auth-service  # or user-service, wallet-service

# Install dependencies
uv sync

# Setup environment
cp sample.env .env
# Edit .env with your configuration

# Run migrations
alembic upgrade head

# Run service
uv run uvicorn app.main:app --reload

Metadata Service

cd apps/metadata-service

# Install dependencies
go mod download

# Generate protobuf code
buf generate

# Run migrations
make migrate

# Run service
make run

Matching Engine

cd apps/matching-engine-rust

# Build
cargo build

# Run
cargo run

Environment Configuration

Service Environment Variables

Each service has a sample.env file. Copy and configure:

cp sample.env .env
# Edit .env with your local configuration

Common Variables

# Database
POSTGRES_URL=postgres://user:pass@localhost:5432/tradex
MONGODB_URL=mongodb://localhost:27017/tradex

# Redis
REDIS_URL=redis://localhost:6379

# Kafka
KAFKA_BROKERS=localhost:9092,localhost:9093,localhost:9094
SCHEMA_REGISTRY_URL=http://localhost:8081

# Service URLs
AUTH_SERVICE_URL=http://localhost:8000
ORDER_SERVICE_URL=http://localhost:3000
# ... etc

Database Setup

PostgreSQL

# Create databases
createdb tradex
createdb marketdata
createdb metadata
createdb auth
createdb user
createdb wallet

# Run migrations for each service
cd apps/marketdata-service && make migrate
cd apps/metadata-service && make migrate
cd apps/auth-service && alembic upgrade head
# ... etc

MongoDB

MongoDB is typically auto-configured via Docker. For manual setup:

# MongoDB is ready after Docker Compose starts
# No additional setup needed

Kafka Setup

Register Schemas

# Register all schemas
./shared/scripts/kafka/schema/push.sh \
  shared/kafka-schema/engine/engine.event.v1.avsc \
  engine.event.v1-value

# Repeat for all schemas

Create Topics

Topics are typically created automatically. For manual creation:

docker exec -it tradex-kafka-1-dev kafka-topics --create \
  --topic engine.event.v1 \
  --bootstrap-server kafka-1:29092 \
  --replication-factor 3 \
  --partitions 3

Development Tools

Code Formatting

# Format all code
npx ultracite format

# Lint all code
npx ultracite lint

Type Checking

# TypeScript services
cd apps/order-service
bun run type-check

# Go services
cd apps/marketdata-service
go vet ./...

Testing

# Run tests for a service
cd apps/marketdata-service
make test

# Run all tests
# (varies by service)

Hot Reload

Go Services

Use air for hot reload:

cd apps/marketdata-service
make dev  # Uses air for hot reload

TypeScript Services

Use Bun’s built-in watch mode:

cd apps/order-service
bun run dev  # Watches for changes

Python Services

Use uvicorn’s reload flag:

cd apps/auth-service
uv run uvicorn app.main:app --reload

Debugging

Go Services

# Use Delve debugger
dlv debug ./cmd/marketdata/main.go

TypeScript Services

# Use Node.js debugger
node --inspect-brk index.ts

Python Services

# Use Python debugger
python -m pdb -m uvicorn app.main:app

Common Issues

Port Conflicts

If ports are already in use:

# Find process using port
lsof -i :8080

# Kill process or change port in .env

Database Connection Issues

# Check if database is running
docker ps | grep postgres

# Check connection
psql $POSTGRES_URL

Kafka Connection Issues

# Check if Kafka is running
docker ps | grep kafka

# Check Kafka logs
docker logs tradex-kafka-1-dev

Related Documentation

• Testing Guide
• Debugging Guide
• Contributing Guide