Development Environment Setup

Get your Zzyra development environment up and running with this comprehensive setup guide. Our monorepo structure uses modern tools for optimal development experience.

Quick Start

Clone Repository

git clone <repository-url>
cd zzyra

Install Dependencies

pnpm install

Start Infrastructure

docker-compose -f setup-compose.yml up -d

Setup Database

cd packages/database
pnpm prisma generate
pnpm prisma migrate dev --name init

Start Development

pnpm dev

Prerequisites

Node.js

v20.3.0+

# Using nvm (recommended)
nvm install 20.3.0
nvm use 20.3.0

pnpm

v9.15.2+

npm install -g [email protected]

Docker

Latest

# macOS
brew install --cask docker

# Ubuntu

sudo apt-get install docker.io docker-compose

Git

Latest

# macOS
brew install git

# Ubuntu
sudo apt-get install git

Repository Structure

📁 Monorepo Organization

Organized with Turbo for optimal development experience

zzyra/ ├── apps/ │ ├── ui/ # Next.js Frontend │ │ ├── app/ # Next.js

App Router │ │ ├── components/ # React Components │ │ ├── lib/ # Core Services
│ │ └── package.json │ ├── api/ # NestJS API Server │ │ ├── src/ # Source Code
│ │ ├── test/ # Tests │ │ └── package.json │ └── zzyra-worker/ # NestJS Worker
Service │ ├── src/ # Source Code │ ├── test/ # Tests │ └── package.json ├──
packages/ │ ├── database/ # Prisma Client & Repositories │ │ ├── prisma/ #
Database Schema │ │ ├── src/ # Database Services │ │ └── package.json │ ├──
types/ # Shared TypeScript Types │ │ ├── src/ # Type Definitions │ │ └──
package.json │ └── blocks/ # Block Library │ ├── src/ # Block Definitions │
└── package.json ├── docker-compose.yml # Development Infrastructure ├──
turbo.json # Turbo Configuration ├── package.json # Root Package └──
pnpm-workspace.yaml # Workspace Configuration ```
</div>

## Environment Configuration

<div className="environment-setup">
<h3>🔧 Environment Variables</h3>
<p>Configure environment variables for each application</p>

<Tabs>
  <Tab title="Frontend (.env.local)">
```bash
# Database
NEXT_PUBLIC_API_URL=http://localhost:3001

# Authentication

NEXT*PUBLIC_MAGIC_PUBLISHABLE_KEY=pk_live*...
NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID=...

# Web3

NEXT_PUBLIC_ALCHEMY_API_KEY=...
NEXT_PUBLIC_INFURA_API_KEY=...

# AI Services

NEXT_PUBLIC_OPENROUTER_API_KEY=...

API Server (.env)
Worker Service (.env)

# Database
DATABASE_URL="postgresql://zzyra:zzyra@localhost:5433/zzyra?schema=public"

# JWT
JWT_SECRET="your-super-secret-jwt-key-here"
JWT_EXPIRES_IN="7d"

# Magic SDK
MAGIC_SECRET_KEY="sk_live_..."

# AI Services
OPENROUTER_API_KEY="sk-or-v1-..."

# RabbitMQ
RABBIT_MQ_URL="amqp://guest:guest@localhost:5672"

# Database
DATABASE_URL="postgresql://zzyra:zzyra@localhost:5433/zzyra?schema=public"

# RabbitMQ
RABBIT_MQ_URL="amqp://guest:guest@localhost:5672"

# AI Services
OPENROUTER_API_KEY="sk-or-v1-..."
OLLAMA_BASE_URL="http://localhost:11434"

# Blockchain
ALCHEMY_API_KEY="..."
INFURA_API_KEY="..."

Infrastructure Setup

🐳 Docker Infrastructure

Local development infrastructure using Docker Compose

PostgreSQL

Port:5433

Database:zzyra

User:zzyra

RabbitMQ

Port:5672

Management:15672

User:guest

Redis

Port:6379

Purpose:Caching

Ollama

Port:11434

Purpose:Local AI Models

Start Infrastructure
Stop Infrastructure
Database Management

# Start all services
docker-compose -f setup-compose.yml up -d

# Check status

docker-compose -f setup-compose.yml ps

# View logs

docker-compose -f setup-compose.yml logs -f

# Stop all services
docker-compose -f setup-compose.yml down

# Stop and remove volumes
docker-compose -f setup-compose.yml down -v

# Access PostgreSQL
docker exec -it zzyra-postgres psql -U zzyra -d zzyra

# Reset database
docker-compose -f setup-compose.yml down -v
docker-compose -f setup-compose.yml up -d postgres

Database Setup

🗄️ Database Configuration

PostgreSQL with Prisma ORM setup and management

Generate Prisma Client

cd packages/database
pnpm prisma generate

Run Migrations

# Create initial migration
pnpm prisma migrate dev --name init

# Apply migrations

pnpm prisma migrate deploy

Seed Database

# Run seed script
pnpm prisma db seed

# Or manually seed
pnpm tsx prisma/seed.ts

Verify Setup

# Open Prisma Studio
pnpm prisma studio

# Check database connection
pnpm prisma db pull

Prisma Studio

Visual database browser
Data inspection and editing
Relationship visualization
Query building

Database Migrations

Version control for schema
Automatic migration generation
Rollback capabilities
Environment-specific migrations

Development Commands

🚀 Development Scripts

Essential commands for development workflow

Development
Building
Testing
Linting & Formatting

# Start all services
pnpm dev

# Start individual services

pnpm dev:ui # Frontend (port 3000)
pnpm dev:api # API Server (port 3001)
pnpm dev:worker # Worker Service (port 3002)

# Start with specific environment

NODE_ENV=development pnpm dev

# Build all packages
pnpm build

# Build specific package
pnpm build:ui
pnpm build:api
pnpm build:worker

# Build for production
pnpm build:prod

# Run all tests
pnpm test

# Run specific test suites
pnpm test:ui
pnpm test:api
pnpm test:worker

# Run tests with coverage
pnpm test:coverage

# Run E2E tests
pnpm test:e2e

# Lint all packages
pnpm lint

# Fix linting issues
pnpm lint:fix

# Format code
pnpm format

# Type checking
pnpm type-check

IDE Configuration

💻 IDE Setup

Recommended IDE configuration for optimal development experience

VS Code

TypeScript and JavaScript
Prisma
Tailwind CSS IntelliSense
ESLint
Prettier
Docker
GitLens

WebStorm

TypeScript support
Database tools
Docker integration
Git integration
Code completion
Refactoring tools

VS Code Settings

{
  "typescript.preferences.importModuleSpecifier": "relative",
  "typescript.suggest.autoImports": true,
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "tailwindCSS.includeLanguages": {
    "typescript": "javascript",
    "typescriptreact": "javascript"
  },
  "prisma.format.enable": true,
  "files.associations": {
    "*.prisma": "prisma"
  }
}

Troubleshooting

🔧 Common Issues

Solutions to common development environment issues

Port Already in Use

Port 3000, 3001, or 5433 is already in use

# Find process using port
lsof -i :3000

# Kill process

kill -9 <PID>

# Or use different ports

PORT=3001 pnpm dev:ui

Database Connection Failed

Cannot connect to PostgreSQL database

# Check if Docker containers are running
docker-compose -f setup-compose.yml ps

# Restart database
docker-compose -f setup-compose.yml restart postgres

# Check database logs
docker-compose -f setup-compose.yml logs postgres

Prisma Client Not Generated

Prisma client not found or outdated

# Regenerate Prisma client
cd packages/database
pnpm prisma generate

# Clear node_modules and reinstall
rm -rf node_modules
pnpm install

Dependencies Not Found

Module not found errors in monorepo

# Clean install
rm -rf node_modules
rm -rf packages/*/node_modules
pnpm install

# Rebuild packages
pnpm build:packages

Next Steps

API Development

Learn about API development and endpoints

Custom Blocks

Create custom automation blocks

Database Schema

Understand the database structure

The development environment is designed to be consistent across all team members. If you encounter issues not covered here, please check the troubleshooting guide or reach out to the development team.

Getting Started

Database

Advanced

Development Environment Setup