Skip to content

Backend API Overview

The Rego backend is a modern, async Python API built with FastAPI. It provides a complete REST API for managing boards, cards, columns, and related resources, along with real-time WebSocket support for collaborative features.

Technology Stack

  • Framework: FastAPI
  • Database: PostgreSQL with SQLAlchemy ORM (async)
  • Cache/PubSub: Redis for real-time events and rate limiting
  • Authentication: JWT-based auth with fastapi-users
  • Real-time: WebSockets with Redis pub/sub for multi-instance support
  • Migrations: Alembic for database schema management

Architecture

The backend follows a domain-driven design with clear separation of concerns:

backend/rego/src/rego/
├── core/                    # Core infrastructure
│   ├── databases/          # Database connections
│   ├── events/             # WebSocket & pub/sub system
│   ├── middlewares/        # Custom middleware (rate limiting)
│   ├── services/           # Base services and utilities
│   ├── settings/           # Configuration management
│   ├── types/              # Custom types
│   ├── enums/              # Shared enumerations
│   └── models.py           # SQLAlchemy models
│
├── domains/                # Business logic domains
│   ├── auth/              # Authentication & authorization
│   ├── users/             # User management
│   ├── boards/            # Board operations
│   ├── columns/           # Column management
│   ├── cards/             # Card operations
│   ├── labels/            # Label management
│   ├── checklists/        # Checklist & items
│   ├── attachments/       # File attachments
│   ├── automations/       # Automation rules
│   ├── access/            # Access control
│   └── websocket/         # WebSocket connections
│
└── main.py                # Application entry point

Key Features

1. Authentication & Authorization

  • JWT token-based authentication
  • Cookie-based sessions
  • Role-based access control (owner, member)
  • Board-level permissions

2. Real-time Collaboration

  • WebSocket connections per board
  • Redis pub/sub for cross-instance messaging
  • Presence tracking (who's viewing a board)
  • Automatic connection heartbeat/monitoring
  • Event broadcasting for all CRUD operations

3. Performance & Scalability

  • Async/await throughout the stack
  • Connection pooling for PostgreSQL
  • Redis caching for real-time data
  • Rate limiting with configurable limits
  • Lazy loading of relationships
  • Efficient ranking system for drag-and-drop

4. Data Model

The application uses a relational model with the following main entities:

  • Board: Top-level container with members
  • Column: Vertical lists within a board (with ordering)
  • Card: Tasks/items with rich metadata
  • Checklist: Sub-tasks within cards
  • Label: Tags for categorization
  • User: System users with board memberships
  • Attachment: File storage for cards
  • AutomationRule: Automated workflows

5. Ranking System

Cards, columns, and checklists use a sophisticated integer-based ranking system that:

  • Allows O(1) insertion between any two items
  • Automatically rebalances when space runs out
  • Uses 63-bit integer space for virtually unlimited items
  • Supports drag-and-drop with stable ordering

6. Event System

Every mutation publishes events through Redis pub/sub:

  • Enables real-time UI updates across all clients
  • Supports multiple backend instances
  • Decoupled architecture for extensibility
  • Events include user context for activity tracking

7. Automation System

Rule-based automation engine that:

  • Triggers on card movements, creations, or label additions
  • Executes actions like moving cards or assigning members
  • Prevents infinite loops
  • System-triggered events (no user context)

API Conventions

Request/Response Formats

All endpoints use JSON for request bodies and responses. The API follows RESTful conventions:

  • GET /resource - List resources
  • GET /resource/{id} - Get single resource
  • POST /resource - Create resource
  • PATCH /resource/{id} - Update resource
  • DELETE /resource/{id} - Delete resource

Error Handling

Standard HTTP status codes:

  • 200 - Success
  • 201 - Created
  • 204 - No Content (successful deletion)
  • 400 - Bad Request (validation errors)
  • 401 - Unauthorized (no/invalid token)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found
  • 409 - Conflict (constraint violations)
  • 429 - Too Many Requests (rate limit exceeded)

Error responses include structured JSON:

{
  "detail": "Human-readable error message",
  "error_type": "ErrorClassName"
}

Authentication

Most endpoints require authentication via JWT token:

Header-based: 

Authorization: Bearer <token>

Cookie-based: 

Cookie: rego_auth=<token>

Rate Limiting

The API implements rate limiting with different tiers:

  • Read operations (GET): Higher limits
  • Write operations (POST/PUT/PATCH/DELETE): Lower limits
  • Per-user limits for authenticated requests
  • Per-IP limits for anonymous requests

Rate limit info is returned in response headers:

RateLimit-Limit: 100
RateLimit-Remaining: 95
RateLimit-Reset: 45

Base URL

When running locally: 

http://localhost:8000

All API endpoints are relative to this base URL.

Health Check

The API provides a health check endpoint for monitoring:

GET /health

Returns status of all critical services:

{
  "status": "healthy",
  "environment": "development",
  "debug": true,
  "postgres": "connected",
  "redis": "connected",
  "subscriber": "running",
  "websocket": {
    "total_boards": 3,
    "total_connections": 7
  }
}

Next Steps