Architecture Overview - MQUAD Platform

MQUAD is a multi-tenant survey management platform built on a microservices architecture. The system is designed for horizontal scalability, tenant isolation, and integration with ODK-based data collection workflows.

Technology Stack

Layer	Technology
Backend Framework	FastAPI (Python 3.13+) with Uvicorn
Frontend	React 19, Vite 7, Tailwind CSS 4, Radix UI
Database	PostgreSQL 15 (per-service databases)
Cache & Message Broker	Redis
API Gateway	Traefik v3.0
Task Queue	Celery
Object Storage	MinIO (S3-compatible)
Observability	OpenTelemetry, Prometheus, Grafana, Loki, Jaeger
Container Runtime	Docker

Architecture Pattern

The system follows an API Gateway + Microservices pattern:

                          ┌─────────────┐
                          │   Traefik   │
                          │ API Gateway │
                          │  :80 / :443 │
                          └──────┬──────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
         ┌────▼────┐      ┌─────▼─────┐      ┌─────▼─────┐
         │ Backend │      │  Frontend │      │  Scalar   │
         │  :8000  │      │  :5173    │      │  :8030    │
         └────┬────┘      └───────────┘      └───────────┘
              │
    ┌─────────┼──────────┬──────────┬──────────┐
    │         │          │          │          │
┌───▼──┐ ┌───▼──┐ ┌───▼───┐ ┌───▼──┐ ┌───▼───┐
│Survey│ │ Data │ │ Sync  │ │Analyt│ │Worksp │
│:8001 │ │:8002 │ │:8003  │ │:8004 │ │:8006  │
└──┬───┘ └──┬───┘ └───┬───┘ └──┬──┘ └───┬───┘
   │        │         │        │        │
   └────────┴─────────┴────────┴────────┘
              │
    ┌─────────┼──────────┬──────────┬──────┐
    │         │          │          │      │
┌───▼──┐ ┌───▼──┐ ┌───▼───┐ ┌───▼──┐ ┌───▼───┐
│Webhk │ │ODKBr │ │ Form  │ │Media │ │Notif  │
│:8007 │ │:8009 │ │:8010  │ │:8011 │ │:8012  │
└──────┘ └──────┘ └───────┘ └──────┘ └───────┘
                                       ┌───────┐
                                       │Audit  │
                                       │:8013  │
                                       └───────┘

Communication Patterns

Synchronous (REST): Services communicate via HTTP through Traefik. Service-to-service calls use X-Service-API-Key authentication.
Asynchronous (Redis Pub/Sub): Survey and data services publish events to the webhook:events channel. The webhook-service consumes these events and dispatches outbound webhooks.
Background Tasks (Celery): Each service runs its own Celery worker with dedicated queues for background processing (email delivery, webhook retries, analytics aggregation).

Key Design Principles

Database-per-service: Each microservice owns its PostgreSQL database. No cross-service database access.
Tenant isolation: All queries filter by tenant_id. Tenant middleware is first in the middleware stack.
Best-effort events: Event publishing failures are logged but never break the main request flow.
Pagination standard: All list endpoints return { items, total, skip, limit, has_next, has_previous }.