Architecture Overview

API version: v1 Estimated reading time: 10 minutes Audience: Integrators and backend developers

Booga Enterprise is a multi-tenant SaaS platform built on a Django REST Framework backend, a Next.js frontend, and an asynchronous task layer powered by Celery. This document describes how the major components fit together, how requests flow through the system, and where the API surface you integrate against lives within that architecture.

Platform Components

The platform runs as four cooperating services behind a global entry point:

Service	Technology	Role
Frontend (web)	Next.js (React)	Server-side rendered UI, client-side interactions, API proxy routes
Backend (api)	Django + Uvicorn (ASGI)	REST API, WebSocket endpoints, authentication, business logic
Worker	Celery + FastAPI sidecar	Async task execution — file processing, AI inference, sync pipelines, infrastructure provisioning
Beat	Celery Beat	Periodic task scheduling — report generation, sync schedules, cleanup jobs

All four services share the same codebase. The backend serves the HTTP API that external integrations call. The worker processes long-running jobs enqueued by the backend. Beat triggers scheduled tasks on configurable intervals.

Deployment Topology

Each environment (development, beta, production) is a fully isolated stack:

                     Internet
                        |
              +---------v----------+
              |   Azure Front Door  |
              |   (Global CDN/WAF)  |
              +----+----------+----+
                   |          |
              beta.example.com   app.example.com
                   |          |
         +---------v--+  +---v----------+
         | Beta Stack  |  | Prod Stack   |
         |             |  |              |
         | web (Next)  |  | web (Next)   |
         | api (Django) | | api (Django)  |
         | worker      |  | worker       |
         | beat        |  | beat         |
         |             |  |              |
         | PostgreSQL  |  | PostgreSQL   |
         | Redis       |  | Redis        |
         | Key Vault   |  | Key Vault    |
         | Blob Storage|  | Blob Storage |
         | Service Bus |  | Service Bus  |
         +-------------+  +--------------+

Key architectural properties:

• Azure Front Door handles TLS termination, hostname-based routing, WAF policies, and WebSocket upgrades
• Container Apps host all four services with autoscaling — the backend scales on HTTP concurrency and CPU, workers scale via KEDA based on Redis queue depth
• PostgreSQL Flexible Server provides the relational data store with VNet-integrated private networking
• Redis Cache serves as the Celery broker, caching layer, and rate-limit store
• Azure Blob Storage stores uploaded files, static assets, and centralised logs
• Azure Service Bus powers the event delivery pipeline for webhooks and notifications

Production adds zone-redundant high availability for PostgreSQL and Redis, geo-redundant backups, and higher autoscaling ceilings.

Multi-Tenancy Model

Every API request is scoped to a tenant. Tenants are isolated at the database level — each tenant's data is stored in the same database but filtered by tenant ownership on every query.

There are two tenant types:

Type	Description	API Key Access
Corporate	Enterprise B2B organisations with dedicated resources and full API management capabilities	Yes — full API key CRUD, scopes, analytics
Developer	Individual developer accounts on shared infrastructure	No — API management UI and key endpoints return 403

Corporate tenants can provision dedicated infrastructure stacks (vector databases, AI services) via the platform's resource manager. Developer tenants share a common infrastructure stack to keep costs low.

When you integrate via API keys, you operate within the corporate tenant that created the key. All resource access, rate limits, and scope enforcement are tenant-scoped.

API Surface

The backend exposes a REST API organised by plugin. Each plugin provides a set of endpoints under /api/{plugin_name}/:

Plugin	Base Path	Capabilities
Files	/api/files/	Upload, download, browse, share, embed files
Chat	/api/chat/	Create sessions, send messages, stream AI responses
Agents	/api/agents/	Configure, execute, and monitor AI agent workflows
Knowledge	/api/knowledge/	Search, categorise, and manage knowledge base content
Reports	/api/reports/	Generate, schedule, and retrieve reports
Analytics	/api/analytics/	Query dashboards, metrics, and anomaly detection data
Organizations	/api/organizations/	Manage organisational units and memberships
Integrations	/api/integrations/	Configure connectors, sync pipelines, and inbound webhooks
Scheduler	/api/scheduler/	Create and manage scheduled tasks
API Management	/api/api-management/	API key CRUD, endpoint registry, usage analytics, OpenAPI schema

Endpoint behaviour and parameters are documented using structured docstrings on each Django REST Framework view. These docstrings are the single source of truth — they feed the API Management plugin's discovery engine, the interactive API Explorer, and the OpenAPI schema used for this documentation site's API reference.

OpenAPI and API Discovery

The platform maintains a live API Endpoint Registry that catalogues every available endpoint with its HTTP method, plugin, required capability, parameters, and response shapes. The registry is populated by an automated discovery process that scans Django URL patterns and parses structured view docstrings.

From the registry, the platform generates OpenAPI 3.0.3 specifications:

• Per-plugin specs — one YAML file per plugin, used by the API reference pages on this documentation site (rendered with Redoc)
• Combined spec — a single schema covering all plugins, available for download from the API Management UI or via the /api/api-management/openapi-schema/ endpoint

The OpenAPI schema is suitable for code generation, contract testing, and import into tools like Postman or Insomnia. You can also generate ready-to-use client SDKs in Python, TypeScript, JavaScript, cURL, and Postman collection format directly from the API Management plugin.

Request Flow

A typical API request follows this path:

1. Client sends an HTTPS request to the API hostname (e.g., api.boogaenterprise.com)
2. Front Door terminates TLS, applies WAF rules and rate limiting, and forwards the request to the backend Container App
3. Django middleware authenticates the request (API key, session, or JWT), resolves the tenant, and checks permissions
4. API key middleware (if using an API key) validates the key hash, checks scopes against the endpoint's required permissions, enforces IP restrictions, applies per-key rate limits, and logs the request to the usage analytics pipeline
5. View processes the request, interacts with the database and any required services, and returns a JSON response
6. For long-running operations, the view enqueues a Celery task and returns immediately with a task ID or status URL

Response headers on API-key-authenticated requests include rate-limit information:

Header	Description
X-RateLimit-Limit-Minute	Maximum requests per minute for this key
X-RateLimit-Remaining-Minute	Remaining requests in the current minute window
X-RateLimit-Limit-Hour	Maximum requests per hour for this key
X-RateLimit-Remaining-Hour	Remaining requests in the current hour window
X-Request-ID	Unique identifier for the request (useful for support)
X-Response-Time	Server-side processing time in milliseconds

Event System and Webhooks

The platform includes a built-in event system for real-time notifications. When significant actions occur (file uploads, agent completions, user changes, etc.), the backend publishes events to the event pipeline.

Event subscriptions let you receive these events as webhook deliveries to your endpoints. Each delivery is signed with HMAC-SHA256 so you can verify authenticity. Failed deliveries are retried with exponential backoff.

For details on setting up webhooks and handling events, see the Webhooks & Events guide.

Security Architecture

Security is layered throughout the platform:

• Network isolation — all services communicate within private VNets; the database and Redis are not publicly accessible
• TLS everywhere — TLS 1.2+ for all connections including internal service-to-service communication
• Managed identities — Container Apps use Azure Managed Identities to access Key Vault, storage, and the container registry without storing credentials
• API key security — keys are hashed with PBKDF2-HMAC and per-key salt; the plaintext key is shown only once at creation
• Scope-based access control — API keys are limited to explicitly granted scopes that map to RBAC permissions
• Rate limiting — configurable per-key minute and hour windows, enforced at the middleware layer
• WAF protection — Azure Front Door applies OWASP 3.2 rules, bot protection, and global rate limiting

Next Steps

• Using the API — base URL, conventions, pagination, and error handling
• Authentication & Authorization — API keys, sessions, scopes, and security best practices
• Integration Getting Started — set up your first API integration end-to-end
• Webhooks & Events — subscribe to platform events and handle webhook deliveries
• API Reference — interactive OpenAPI documentation for every endpoint

Related Topics

• Using the API
• Authentication & Authorization
• Integration Getting Started

---

⏱️ Read time: 10 minutes | 📊 Difficulty: intermediate