🌌 Zoo Universe

Unified development environment for all Zoo ecosystem apps.

Overview

Zoo Universe is a meta-repository that orchestrates all Zoo applications for local development. It provides:

• Unified setup: Clone and install all apps with one command
• Parallel development: Run all apps simultaneously
• Easy management: Start/stop all services with simple scripts
• Docker support: Alternative Docker Compose setup

Apps Included

App	Port	Description
zoo.ngo	3000	Main Zoo AI/ML Platform
zoo.exchange	3001	Zoo Exchange (ZX) - DEX trading platform
zoo.network	3002	Network info and node management
zoo.computer	3003	Zoo Computer desktop app
zoo.lab	3004	Zoo Labs - Experimental AI research
zoo.fund	3005	Grants and funding platform
zoo.vote	3006	DAO governance and voting
zoo.foundation	3007	Zoo Labs Foundation website
zoo.voyage	3008	Travel and volunteer booking for conservation

Quick Start

Prerequisites

• Node.js 20+
• npm or pnpm
• Git
• GitHub CLI (gh) or SSH keys configured

Setup

# 1. Clone all repos
./setup.sh

# 2. Install all dependencies
./install-all.sh

# 3. Start all apps
./start.sh

# 4. Check status
./status.sh

All apps will be running on their respective ports. Visit http://localhost:3000 (zoo.ngo), http://localhost:3005 (zoo.fund), etc.

Stop All Apps

./stop.sh

Docker Compose (Alternative)

If you prefer Docker:

# Start all apps with Docker Compose
docker compose up

# Start in background
docker compose up -d

# View logs
docker compose logs -f

# Stop all apps
docker compose down

Development Workflow

Working on a Single App

cd zoo.ngo
npm run dev

Working on Multiple Apps

# Terminal 1: Start zoo.ngo
cd zoo.ngo && npm run dev

# Terminal 2: Start zoo.fund
cd zoo.fund && npm run dev

# Or use the unified start script
./start.sh

Viewing Logs

# All logs
tail -f logs/*.log

# Specific app
tail -f logs/zoo.exchange.log

# Real-time status
watch -n 1 ./status.sh

Scripts Reference

Script	Description
setup.sh	Clone all Zoo app repositories
install-all.sh	Install dependencies for all apps
start.sh	Start all apps in development mode
stop.sh	Stop all running apps
status.sh	Check which apps are running

Port Mapping

All apps run on localhost with the following ports:

• 3000: zoo.ngo (main platform)
• 3001: zoo.exchange (ZX - DEX trading)
• 3002: zoo.network
• 3003: zoo.computer
• 3004: zoo.lab (zoolabs.io)
• 3005: zoo.fund
• 3006: zoo.vote
• 3007: zoo.foundation
• 3008: zoo.voyage (travel/volunteer booking)

Backend Services

Zoo Exchange API

The Zoo Exchange (ZX) includes a backend API server that requires:

• PostgreSQL database
• Redis cache
• Blockchain RPC (Hardhat or Lux Network)

See BACKEND_SERVICES.md for complete setup instructions.

API Port: 3010 (separate from frontend on 3001)

Project Structure

zoo/universe/ (zoo-labs/universe)
├── zoo.ngo/              # Main platform
├── zoo.exchange/         # DEX trading (frontend + API)
├── zoo.network/          # Network tools
├── zoo.computer/         # Desktop app
├── zoo.lab/              # Research interface (zoolabs.io)
├── zoo.fund/             # Funding platform + smart contracts
├── zoo.vote/             # DAO governance
├── zoo.foundation/       # Foundation site
├── zoo.voyage/           # Travel/volunteer booking
├── logs/                 # App logs
├── setup.sh              # Setup script
├── install-all.sh        # Install dependencies
├── start.sh              # Start all apps
├── stop.sh               # Stop all apps
├── status.sh             # Check app status
├── compose.yml           # Docker Compose config
├── Dockerfile.dev        # Development Dockerfile
├── RUNNING.md            # Current status documentation
├── BACKEND_SERVICES.md   # Backend setup guide
├── DEPLOYMENT_COMPLETE.md # Deployment summary
└── README.md             # This file

Smart Contracts

The zoo.fund/contracts directory contains governance contracts:

• ZooToken.sol: ERC20 governance token (1 billion ZOO)
• ZooGovernor.sol: OpenZeppelin Governor with timelock
• TimelockController.sol: 2-day timelock for governance

Deploy locally:

cd zoo.fund/contracts
npx hardhat node &
npx hardhat run scripts/deploy-governance.js --network localhost

Troubleshooting

Port Already in Use

If a port is already in use, kill the process:

# Find process using port 3001
lsof -ti:3001 | xargs kill -9

# Or stop all Node processes
killall node

App Won't Start

Check the logs:

tail -f logs/zoo.exchange.log

Reinstall dependencies:

cd zoo.exchange
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

Out of Sync with GitHub

Pull latest changes:

cd zoo.ngo
git pull origin main
npm install

OpenSSL Error (zoo.lab)

If you encounter OpenSSL errors with Node v20:

cd zoo.lab
echo "NODE_OPTIONS=--openssl-legacy-provider" >> .env
echo "SKIP_PREFLIGHT_CHECK=true" >> .env

E2E Tests

Playwright E2E tests verify Zoo blockchain health, explorer, exchange, and cross-chain connectivity with the parent Lux network.

Prerequisites

npm install
npx playwright install chromium

Running Tests

# Run all tests (default: production mainnet)
npm test

# Individual test suites
npm run test:health      # Zoo chain RPC, health, latency benchmarks
npm run test:explorer    # Zoo explorer API + frontend (explore-zoo.lux.network)
npm run test:exchange    # zoo.exchange UI (skips if not deployed)
npm run test:parent      # Cross-chain verification with Lux

# Target a specific network
LUX_NETWORK=mainnet npm test
LUX_NETWORK=testnet npm test
LUX_NETWORK=devnet npm test

# Test against local node
ENV=local npm test

# Interactive UI mode
npm run test:ui

Zoo Chain Details

Network	Zoo Chain ID	RPC
Mainnet	200200	api.lux.network/mainnet/ext/bc/zoo/rpc
Testnet	200201	api.lux-test.network/testnet/ext/bc/zoo/rpc
Devnet	200202	api.lux-dev.network/devnet/ext/bc/zoo/rpc

Contributing

Each app is a separate repository under the zoo-labs GitHub organization.

To contribute to a specific app:

1. Make changes in the app's directory
2. Commit and push to GitHub
3. Create a pull request

Links

• GitHub Org: https://github.com/zoo-labs
• Main Site: https://zoo.ngo
• Zoo Labs: https://zoolabs.io
• Documentation: See individual repositories

License

Each app has its own license. See individual repositories for details.

---

Built with ❤️ by Zoo Labs Foundation Powered by Lux Network & Hanzo AI