Local Development Setup

This guide walks you through setting up the fXYZ Network monorepo for local development.

Prerequisites: Node.js 20+, pnpm 9+, Docker (for Neo4j), and a code editor.

Quick Start

Clone the Repository

git clone https://github.com/fxyznetwork/fxallapp.git
cd fxallapp

Install Dependencies

We use pnpm as the package manager in a Turbo monorepo:

# Install pnpm if needed
npm install -g pnpm

# Install all dependencies
pnpm install

Configure Environment

Copy the example environment files:

# Root environment (shared secrets)
cp .env.example .env

# API app environment
cp apps/api/.env.example apps/api/.env.local

# Main app environment
cp apps/app/.env.example apps/app/.env.local

Start Neo4j Database

Using Docker Compose:

docker-compose -f docker-compose.neo4j.yaml up -d

Or using a local Neo4j instance (port 7687).

Run Development Servers

pnpm dev

This starts all apps concurrently via Turbo:

app.localhost:3000 - Main application
api.localhost:3001 - GraphQL API
docs.localhost:3002 - Documentation
web.localhost:3003 - Marketing site

Monorepo Structure

fxallapp/
├── apps/
│   ├── app/          # Main application (Next.js 16)
│   ├── api/          # GraphQL API server
│   ├── docs/         # Documentation (Fumadocs)
│   └── web/          # Marketing website
├── packages/
│   ├── design-system/ # Shared UI components
│   ├── graphql/       # GraphQL queries/mutations
│   ├── neo4j/         # Neo4j client and migrations
│   ├── florin/        # Florin token SDK
│   ├── trading/       # ECN trading package
│   └── types/         # Shared TypeScript types
└── scripts/           # Build and deployment scripts

Environment Variables

Required Variables

Variable	Description	Example
`NEO4J_URI`	Neo4j connection URI	`bolt://localhost:7687`
`NEO4J_USER`	Neo4j username	`neo4j`
`NEO4J_PASSWORD`	Neo4j password	`your-password`
`PRIVY_APP_ID`	Privy application ID	Get from Privy dashboard
`PRIVY_APP_SECRET`	Privy secret key	Get from Privy dashboard

Optional Variables

Variable	Description	Default
`CLUSTER_ENV`	Solana cluster	`devnet`
`HELIUS_API_KEY`	Helius RPC API key	-
`BRIDGE_API_KEY`	Bridge.xyz API key	-
`LETTA_BASE_URL`	Letta AI server URL	`http://localhost:8283`

Development Commands

Common Tasks

# Start development (all apps)
pnpm dev

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

# Type check
./scripts/typecheck.sh

# Format code
pnpm format

Package-Specific

# Run only the main app
pnpm --filter @repo/app dev

# Build only the API
pnpm --filter @repo/api build

# Run Neo4j migrations
pnpm --filter @repo/neo4j migrate

Neo4j Setup

Using Docker

# docker-compose.neo4j.yaml
services:
  neo4j:
    image: neo4j:5.15-enterprise
    ports:
      - "7474:7474"  # Browser
      - "7687:7687"  # Bolt
    environment:
      - NEO4J_AUTH=neo4j/your-password
      - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
      - NEO4J_PLUGINS=["apoc"]

Running Migrations

# Apply all migrations
pnpm --filter @repo/neo4j migrate

# Check migration status
pnpm --filter @repo/neo4j migrate:status

Verify Connection

# Test Neo4j connectivity
curl http://localhost:7474/db/neo4j/tx

Letta AI (Fixies)

Local Letta Server

# Start Letta with Docker
docker-compose -f docker-compose.fixie.yaml up -d

# Server runs on port 8283
# Password: fixie_api_2026

Test Fixie Creation

curl -X POST http://localhost:8283/v1/agents \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fixie_api_2026" \
  -d '{"name": "Test Fixie", "llm_config": {"model": "claude-3-5-haiku-latest"}}'

Solana Development

Network Configuration

Environment	Cluster	RPC
Development	devnet	Default Solana RPC
Staging	devnet	Helius RPC
Production	mainnet-beta	Helius RPC

Test Token Operations

# Airdrop SOL on devnet
solana airdrop 2 --url devnet

# Check balance
solana balance --url devnet

Troubleshooting

Common Issues

pnpm install fails: Ensure you're using pnpm 9+ and Node.js 20+.

Neo4j connection refused:

# Check if Neo4j is running
docker ps | grep neo4j

# View logs
docker logs neo4j

TypeScript errors:

# Regenerate types
pnpm --filter @repo/graphql codegen

# Clean and rebuild
pnpm clean && pnpm install && pnpm build

Port conflicts:

# Find process on port 3000
lsof -i :3000

# Kill process
kill -9 <PID>

IDE Setup

VS Code Extensions

Recommended extensions for development:

ESLint
Prettier
Tailwind CSS IntelliSense
GraphQL (GraphQL Foundation)
Neo4j for VS Code

Settings

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "typescript.preferences.importModuleSpecifier": "relative"
}

Next Steps

After setup, explore:

GraphQL API Reference - Available queries and mutations
Architecture Overview - System design
Privy Setup Guide - Authentication configuration
Token Ecosystem - Understanding the token model

Getting Help

Discord: Join our developer community
GitHub Issues: Report bugs and feature requests
Email: [email protected] for technical assistance

Local Development Setup

On this page