Skip to content
ZServed Documentation

Platform Configuration

Platform Configuration

This guide covers all configuration aspects of the ZServed platform, from environment variables to tenant-specific settings and AI service configuration.

Environment Variables

Required Variables

Configure these essential environment variables for production deployment:

Terminal window
# Core Authentication
JWT_SECRET="your-256-bit-secret-key-here"
GITHUB_CLIENT_ID="your-github-oauth-app-id"
GITHUB_CLIENT_SECRET="your-github-oauth-secret"


# AI Services
OPENAI_API_KEY="sk-your-openai-api-key"


# Email & Notifications
RESEND_API_KEY="re_your-resend-api-key"


# Payment Processing (Square)
SQUARE_APPLICATION_ID="your-square-app-id"
SQUARE_ACCESS_TOKEN="your-square-access-token"
SQUARE_LOCATION_ID="your-square-location-id"
SQUARE_WEBHOOK_SIGNATURE_KEY="your-webhook-signature"
SQUARE_ENVIRONMENT="production" # or "sandbox"

Optional Variables

Terminal window
# Analytics & Tracking
PUBLIC_GOOGLE_ANALYTICS_ID="G-XXXXXXXXXX"


# Blockchain Integration
PUBLIC_ONCHAINKIT_API_KEY="your-onchainkit-api-key"
DAO_TREASURY_ADDRESS="0x742d35Cc6635C0532925a3b8D421C8F82e9..."
GOVERNANCE_TOKEN_ADDRESS="0x00000000000000000000000000000000000..."


# Development & Debugging
DEBUG_MODE="false"
LOG_LEVEL="info"

Tenant Configuration

Multi-Tenant Setup

ZServed supports complete tenant isolation with dedicated resources per law firm:

Creating a New Tenant

  1. Generate Tenant Resources:

    Terminal window
    # Deploy isolated tenant worker
    ./scripts/deploy-tenant-worker.sh {tenant-name}

  2. Configure Tenant Database:

    Terminal window
    # Apply schema to tenant database
    wrangler d1 execute "zserved-db-{tenant}" --file=migrations/schema.sql --remote

  3. Set Tenant-Specific Secrets:

    Terminal window
    # Configure tenant worker secrets
    wrangler secret put JWT_SECRET --config wrangler.{tenant}.jsonc
    wrangler secret put GITHUB_CLIENT_ID --config wrangler.{tenant}.jsonc

Tenant Isolation Features

  • Complete Resource Separation: Each tenant gets isolated:

    • Cloudflare Worker instance
    • D1 database
    • KV namespaces
    • R2 storage buckets
    • Vectorize indices

  • Domain Configuration: Set up custom domains:

    {
      "tenant_id": "example-firm",
      "primary_domain": "example-firm.com",
      "worker_subdomain": "example-firm.zserved.com"
    }

AI Service Configuration

OpenAI Integration

Configure AI models and parameters:

// AI Configuration
export const AI_CONFIG = {
  models: {
    chat: "gpt-4-turbo-preview",
    embeddings: "text-embedding-3-large",
    analysis: "gpt-4",
  },
  parameters: {
    temperature: 0.1,
    max_tokens: 4000,
    top_p: 0.95,
  },
  safety: {
    content_filter: true,
    pii_detection: true,
    legal_compliance: true,
  }
};

Vectorize Configuration

Set up document embeddings and search:

Terminal window
# Create vectorize index
wrangler vectorize create document-embeddings \
  --dimensions=1536 \
  --metric=cosine


# Configure for tenant
wrangler vectorize create document-embeddings-{tenant} \
  --dimensions=1536 \
  --metric=cosine

Database Configuration

Main Database Schema

Apply the complete schema in order:

Terminal window
# Core schema
wrangler d1 execute zserved-db --file=migrations/schema.sql --remote


# Authentication & admin
wrangler d1 execute zserved-db --file=migrations/admin-auth-schema.sql --remote


# Pricing & usage enforcement
wrangler d1 execute zserved-db --file=migrations/new-pricing-schema.sql --remote


# Super admin controls
wrangler d1 execute zserved-db --file=migrations/super-admin-schema.sql --remote


# AgentKit integration
wrangler d1 execute zserved-db --file=migrations/agentkit-schema.sql --remote


# DAO backing
wrangler d1 execute zserved-db --file=migrations/dao-backing-schema.sql --remote

Performance Optimization

Configure database performance settings:

-- Enable WAL mode for better concurrent access
PRAGMA journal_mode = WAL;


-- Optimize for read performance
PRAGMA cache_size = -64000; -- 64MB cache


-- Create indexes for common queries
CREATE INDEX IF NOT EXISTS idx_jobs_tenant_status ON jobs(tenant_id, status);
CREATE INDEX IF NOT EXISTS idx_files_tenant_created ON files(tenant_id, created_at);

Security Configuration

Authentication Settings

Configure JWT and OAuth settings:

// JWT Configuration
export const JWT_CONFIG = {
  algorithm: 'HS256',
  expiresIn: '24h',
  issuer: 'zserved.com',
  audience: 'zserved-users',
};


// OAuth Configuration
export const OAUTH_CONFIG = {
  github: {
    scope: 'user:email',
    allow_signup: true,
  },
};

CORS & Security Headers

// Security Headers
export const SECURITY_HEADERS = {
  'X-Frame-Options': 'DENY',
  'X-Content-Type-Options': 'nosniff',
  'Referrer-Policy': 'strict-origin-when-cross-origin',
  'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
};

Storage Configuration

R2 Bucket Setup

Configure file storage buckets:

Terminal window
# Main platform storage
wrangler r2 bucket create serveros-files


# Tenant-specific storage
wrangler r2 bucket create serveros-files-{tenant}

File Upload Limits

export const UPLOAD_CONFIG = {
  maxFileSize: 50 * 1024 * 1024, // 50MB
  allowedTypes: [
    'application/pdf',
    'image/jpeg',
    'image/png',
    'text/plain',
    'application/msword',
    'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
  ],
  virusScan: true,
  encryption: 'AES-256',
};

Monitoring & Logging

Analytics Configuration

export const ANALYTICS_CONFIG = {
  googleAnalytics: {
    measurementId: process.env.PUBLIC_GOOGLE_ANALYTICS_ID,
    tagGateway: true,
  },
  customEvents: {
    jobCreated: true,
    fileUploaded: true,
    aiInteraction: true,
  },
};

Error Tracking

export const ERROR_CONFIG = {
  logLevel: 'info',
  retentionDays: 30,
  alertThresholds: {
    errorRate: 0.05, // 5%
    responseTime: 5000, // 5 seconds
  },
};

Performance Optimization

Caching Configuration

export const CACHE_CONFIG = {
  static: {
    maxAge: 86400, // 1 day
    staleWhileRevalidate: 3600, // 1 hour
  },
  api: {
    maxAge: 300, // 5 minutes
    staleWhileRevalidate: 60, // 1 minute
  },
  cdn: {
    enabled: true,
    regions: ['auto'],
  },
};

Rate Limiting

export const RATE_LIMIT_CONFIG = {
  api: {
    windowMs: 60000, // 1 minute
    max: 100, // requests per window
  },
  auth: {
    windowMs: 900000, // 15 minutes
    max: 5, // login attempts
  },
  upload: {
    windowMs: 3600000, // 1 hour
    max: 20, // file uploads
  },
};

Custom Branding

Tenant Theming

Configure custom branding per tenant:

export const BRANDING_CONFIG = {
  logo: '/tenant-assets/{tenant}/logo.png',
  colors: {
    primary: '#7c3aed',
    secondary: '#3b82f6',
    accent: '#10b981',
  },
  fonts: {
    primary: 'Inter',
    heading: 'Inter',
  },
  customCSS: '/tenant-assets/{tenant}/styles.css',
};

Validation & Testing

Configuration Validation

Terminal window
# Validate configuration
npm run validate-config


# Test tenant setup
npm run test-tenant {tenant-name}


# Health check
curl https://your-domain.com/api/health

Environment-Specific Configs

Terminal window
# Development
cp .env.example .env.development


# Staging
cp .env.example .env.staging


# Production
cp .env.example .env.production

Troubleshooting

Common Configuration Issues

  1. JWT Secret Missing:

    Terminal window
    # Generate secure JWT secret
    openssl rand -base64 32

  2. Database Connection Fails:

    Terminal window
    # Check D1 binding
    wrangler d1 list

  3. Storage Access Denied:

    Terminal window
    # Verify R2 bucket permissions
    wrangler r2 bucket list

Configuration Checklist

  • All environment variables set
  • Database schema applied
  • Storage buckets created
  • AI services configured
  • Security headers enabled
  • Monitoring configured
  • Backup strategy implemented

For additional support, contact the development team or refer to the troubleshooting guide.