xml-pipeline/bloxserver/README.md

BloxServer API

Backend API for BloxServer (OpenBlox.ai) - Visual AI Agent Workflow Builder.

Quick Start

With Docker Compose (Recommended)

cd bloxserver

# Start PostgreSQL, Redis, and API
docker-compose up -d

# Check logs
docker-compose logs -f api

# API available at http://localhost:8000
# Docs at http://localhost:8000/docs

Local Development

cd bloxserver

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Copy environment variables
cp .env.example .env
# Edit .env with your settings

# Start PostgreSQL and Redis (or use Docker)
docker-compose up -d postgres redis

# Run the API
python -m bloxserver.api.main
# Or with uvicorn directly:
uvicorn bloxserver.api.main:app --reload

API Endpoints

Health

• GET /health - Basic health check
• GET /health/ready - Readiness check (includes DB)
• GET /health/live - Liveness check

Flows

• GET /api/v1/flows - List flows
• POST /api/v1/flows - Create flow
• GET /api/v1/flows/{id} - Get flow
• PATCH /api/v1/flows/{id} - Update flow
• DELETE /api/v1/flows/{id} - Delete flow
• POST /api/v1/flows/{id}/start - Start flow
• POST /api/v1/flows/{id}/stop - Stop flow

Triggers

• GET /api/v1/flows/{flow_id}/triggers - List triggers
• POST /api/v1/flows/{flow_id}/triggers - Create trigger
• GET /api/v1/flows/{flow_id}/triggers/{id} - Get trigger
• DELETE /api/v1/flows/{flow_id}/triggers/{id} - Delete trigger
• POST /api/v1/flows/{flow_id}/triggers/{id}/regenerate-token - Regenerate webhook token

Executions

• GET /api/v1/flows/{flow_id}/executions - List executions
• GET /api/v1/flows/{flow_id}/executions/{id} - Get execution
• POST /api/v1/flows/{flow_id}/executions/run - Manual trigger
• GET /api/v1/flows/{flow_id}/executions/stats - Get stats

Webhooks

• POST /webhooks/{token} - Trigger flow via webhook
• GET /webhooks/{token}/test - Test webhook token

Project Structure

bloxserver/
├── api/
│   ├── __init__.py
│   ├── main.py              # FastAPI app entry point
│   ├── dependencies.py      # Auth, DB session dependencies
│   ├── schemas.py           # Pydantic request/response models
│   ├── models/
│   │   ├── __init__.py
│   │   ├── database.py      # SQLAlchemy engine/session
│   │   └── tables.py        # ORM table definitions
│   └── routes/
│       ├── __init__.py
│       ├── flows.py         # Flow CRUD
│       ├── triggers.py      # Trigger CRUD
│       ├── executions.py    # Execution history
│       ├── webhooks.py      # Webhook handler
│       └── health.py        # Health checks
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

Authentication

Uses Clerk for JWT authentication. All /api/v1/* endpoints require a valid JWT.

curl -H "Authorization: Bearer <clerk-jwt>" \
     http://localhost:8000/api/v1/flows

Environment Variables

See .env.example for all configuration options.

Key variables:

• DATABASE_URL - PostgreSQL connection string
• CLERK_ISSUER - Clerk JWT issuer URL
• STRIPE_SECRET_KEY - Stripe API key
• API_KEY_ENCRYPTION_KEY - Fernet key for encrypting user API keys

Database Migrations

Using Alembic for migrations (not yet set up):

# Initialize (first time)
alembic init alembic

# Create migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

Testing

# Install test dependencies
pip install pytest pytest-asyncio httpx

# Run tests
pytest tests/ -v

Deployment

Railway / Render / Fly.io

1. Connect your repo
2. Set environment variables
3. Deploy

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: bloxserver-api
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: api
        image: your-registry/bloxserver-api:latest
        ports:
        - containerPort: 8000
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: bloxserver-secrets
              key: database-url
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8000
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8000

Next Steps

• Alembic migrations setup
• Stripe webhook handlers
• Redis rate limiting
• Container orchestration integration
• WebSocket for real-time logs