Developer Quick Start

Get your Zzyra development environment up and running in minutes. This guide covers the essential steps to start developing with our monorepo architecture.

1. Clone and Setup

Clone Repository

git clone https://github.com/your-org/zzyra.git
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

2. Verify Installation

✅ Check Your Setup

Frontend

URL:http://localhost:3000

Status:✅ Running

API Server

URL:http://localhost:3001

Status:🚧 In Development

Worker Service

URL:http://localhost:3005

Status:✅ Running

3. Project Structure

📁 Understanding the Monorepo

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

apps/ ├── ui/ # Next.js Frontend (port 3000) │ ├── app/ # Next.js

App Router │ ├── components/ # React Components │ └── lib/ # Core Services
├── api/ # NestJS API Server (port 3001) │ ├── src/ # Source Code │ └──
test/ # Tests └── zzyra-worker/ # NestJS Worker Service (port 3002) ├──
src/ # Source Code └── test/ # Tests ```
</Tab>

<Tab title='Packages'>
```bash packages/ ├── database/ # Prisma Client & Repositories │ ├──
prisma/ # Database Schema │ └── src/ # Database Services ├── types/ #
Shared TypeScript Types │ └── src/ # Type Definitions └── blocks/ # Block
Library └── src/ # Block Definitions ```
</Tab>

</Tabs>
</div>

## 4. Essential Commands

<div className='essential-commands'>
<h3>🚀 Development Commands</h3>

<CardGroup cols={2}>
<Card title='Development' icon='code'>
<div className='command-list'>
  <div className='command'>
    <span className='cmd'>pnpm dev</span>
    <span className='desc'>Start all services</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm dev:ui</span>
    <span className='desc'>Frontend only</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm dev:api</span>
    <span className='desc'>API server only</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm dev:worker</span>
    <span className='desc'>Worker service only</span>
  </div>
</div>
</Card>

<Card title='Database' icon='database'>
<div className='command-list'>
  <div className='command'>
    <span className='cmd'>pnpm prisma studio</span>
    <span className='desc'>Open database browser</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm prisma generate</span>
    <span className='desc'>Generate Prisma client</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm prisma migrate dev</span>
    <span className='desc'>Create migration</span>
  </div>
  <div className='command'>
    <span className='cmd'>pnpm prisma db seed</span>
    <span className='desc'>Seed database</span>
  </div>
</div>
</Card>

</CardGroup>
</div>

## 5. Environment Variables

<div className="environment-setup">
<h3>🔧 Essential Environment Variables</h3>

<Alert type="warning">
**Important**: Create `.env` files in each app directory before starting development
</Alert>

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

# Authentication

NEXT*PUBLIC_MAGIC_PUBLISHABLE_KEY=pk_live*...

# Web3

NEXT_PUBLIC_ALCHEMY_API_KEY=...
NEXT_PUBLIC_INFURA_API_KEY=...

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

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

# Magic SDK
MAGIC_SECRET_KEY="sk_live_..."

# 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-..."

6. First Steps

🎯 What to Do Next

Explore the UI

1. Visit http://localhost:3000

2. Create a new account

3. Explore the dashboard

4. Try the workflow builder

Check the API

1. Visit http://localhost:3001/health

2. Check Swagger docs

3. Test API endpoints

4. Review API structure

Database Exploration

1. Run pnpm prisma studio

2. Explore the schema

3. Check sample data

4. Understand relationships

Worker Service

1. Check worker logs

2. Monitor RabbitMQ

3. Test workflow execution

4. Review worker code

7. Common Issues

🔧 Quick Fixes

Port Already in Use

# Find and kill process
lsof -i :3000
kill -9 <PID>

# Or use different port

PORT=3001 pnpm dev:ui

Database Connection Failed

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

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

Prisma Client Issues

# Regenerate client
cd packages/database
pnpm prisma generate

# Clear and reinstall
rm -rf node_modules
pnpm install

Dependencies Not Found

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

# Rebuild packages
pnpm build:packages

8. Next Steps

🚀 Continue Your Journey

Full Setup Guide

Detailed environment setup

API Documentation

Complete API reference

Custom Blocks

Build custom automation

This quick start guide covers the essentials to get you developing. For detailed information about each component, architecture, and advanced features, explore the full documentation.

Getting Started

Database

Advanced

Developer Quick Start