# Architecture Overview {#architecture-overview}


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 {#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 {#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 {#communication-patterns}


1. **Synchronous (REST)**: Services communicate via HTTP through Traefik. Service-to-service calls use `X-Service-API-Key` authentication.

2. **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.

3. **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 {#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 }`.