Quick Start Guide

This guide will help you set up a local development environment for ZServed and deploy your first instance to Cloudflare Workers.

Prerequisites

Before you begin, ensure you have:

• Node.js 18+ installed
• npm or pnpm package manager
• Cloudflare account with Workers access
• Git for version control
• Code editor (VS Code recommended)

Local Development Setup

1. Clone the Repository

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

2. Install Dependencies

# Install root dependencies
npm install

# Install webapp dependencies
cd webapp
npm install
cd ..

3. Configure Environment

Create environment configuration files:

# Copy example environment file
cp .env.example .env

# Edit with your configuration
nano .env

Required Environment Variables:

# Cloudflare Configuration
CLOUDFLARE_ACCOUNT_ID=your_account_id
CLOUDFLARE_API_TOKEN=your_api_token

# Database Configuration
DATABASE_URL=your_d1_database_url

# AI Configuration (Optional)
OPENAI_API_KEY=your_openai_key

# Development Settings
NODE_ENV=development

4. Set Up Cloudflare Resources

Install Wrangler CLI and authenticate:

npm install -g wrangler
wrangler login

Create required Cloudflare resources:

# Create D1 Database
wrangler d1 create zserved-db

# Create R2 Bucket
wrangler r2 bucket create zserved-files

# Create KV Namespaces
wrangler kv:namespace create "TENANTS"
wrangler kv:namespace create "FILE_METADATA"

# Create AutoRAG Instance (if available)
wrangler autorag create zserved-legal-knowledge

5. Update Wrangler Configuration

Update wrangler.jsonc with the resource IDs from the previous step:

{
  "name": "zserved",
  "main": "dist/_worker.js",
  "compatibility_date": "2025-04-15",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "zserved-db",
      "database_id": "your_database_id"
    }
  ],
  "r2_buckets": [
    {
      "binding": "zserved_files",
      "bucket_name": "zserved-files"
    }
  ],
  "kv_namespaces": [
    {
      "binding": "TENANTS",
      "id": "your_tenants_kv_id"
    },
    {
      "binding": "FILE_METADATA",
      "id": "your_file_metadata_kv_id"
    }
  ],
  "autorag": [
    {
      "binding": "LEGAL_RAG",
      "autorag_name": "zserved-legal-knowledge"
    }
  ]
}

6. Initialize Database

Run database migrations:

wrangler d1 execute zserved-db --file=./migrations/schema.sql

7. Start Development Server

Launch the development environment:

# Terminal 1: Start Cloudflare Workers development server
wrangler dev

# Terminal 2: Start Astro frontend development server
cd webapp
npm run dev

Your development environment is now running:

• API: http://localhost:8787
• Frontend: http://localhost:4321

First Steps

1. Create a Tenant

Set up your first law firm tenant:

curl -X POST http://localhost:8787/api/admin/tenants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Smith Legal",
    "slug": "smith-legal",
    "subdomain": "smithlegal",
    "contact_email": "admin@smithlegal.com"
  }'

2. Access the Platform

Visit your tenant’s subdomain:

• Development: http://smithlegal.localhost:4321
• Production: https://smithlegal.your-domain.com

3. Set Up Users

Create admin and client users through the admin interface or API.

4. Test AI Features

If you have AutoRAG configured, seed the knowledge base:

cd scripts
npx tsx seed-knowledge-base.ts smith-legal

Development Workflow

Code Structure

zserved/
├── webapp/                 # Astro frontend application
│   ├── src/
│   │   ├── pages/         # Page routes and API endpoints
│   │   ├── components/    # Reusable UI components
│   │   ├── layouts/       # Page layouts
│   │   └── styles/        # CSS and styling
├── src/                   # Shared utilities and services
│   ├── services/          # Business logic and external integrations
│   └── utils/             # Helper functions
├── migrations/            # Database schema and migrations
├── scripts/              # Utility scripts and tools
└── docs/                 # Documentation (this site)

Key Development Commands

# Backend Development
wrangler dev                    # Start Workers dev server
wrangler tail                   # View real-time logs
wrangler d1 execute DB --file   # Run database migrations

# Frontend Development
cd webapp
npm run dev                     # Start Astro dev server
npm run build                   # Build for production
npm run preview                 # Preview production build

# Mobile Development
cd webapp
npm run cap:ios                 # Open iOS project
npm run cap:android             # Open Android project
npm run copy                    # Copy web assets to mobile

Testing

Run the test suite:

# Unit tests
npm test

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

Common Issues

Wrangler Authentication

If you see authentication errors:

wrangler logout
wrangler login

Database Connection

If database queries fail:

wrangler d1 info zserved-db
# Verify database ID in wrangler.jsonc

CORS Issues

For local development CORS issues, update your development configuration in wrangler.jsonc.

AutoRAG Unavailable

If AutoRAG features don’t work, the platform gracefully falls back to basic processing. Check your AutoRAG instance status:

wrangler autorag list

Next Steps

Now that you have ZServed running locally:

1. Explore the Architecture - Understand how components work together
2. Configure Features - Customize the platform for your needs
3. Set Up AutoRAG - Enable AI-powered features
4. Deploy to Production - Launch your platform

Getting Help

• Documentation: Browse the complete documentation in the sidebar
• API Reference: Check the API documentation for endpoint details
• GitHub Issues: Report bugs or request features
• Community: Join our discussions and get help from other developers

Ready to dive deeper? Check out the configuration guide to customize ZServed for your specific needs.