# Microservices Overview {#microservices-overview}


MQUAD runs 15 microservices plus supporting infrastructure. Each service is independently deployable, owns its own database, and communicates through the Traefik API Gateway.


## Service Table {#service-table}


| # | Service | Port | Base Path | Database | Category | Status |
|---|---------|------|-----------|----------|----------|--------|
| 1 | **backend** | 8000 | `/api/v1` | appdb | Core | Active |
| 2 | **survey-service** | 8001 | `/api/v1` | survey_db | Domain | Active |
| 3 | **data-service** | 8002 | `/api/v1` | data_db | Domain | Active |
| 4 | **sync-service** | 8003 | `/api/v1` | sync_db | Domain | Active |
| 5 | **analytics-service** | 8004 | `/api/v1` | analytics_db | Analytics | Active |
| 6 | **workspace-service** | 8006 | `/api/v1` | workspace_db | Domain | Active |
| 7 | **webhook-service** | 8007 | `/api/v1` | webhook_db | Integration | Active |
| 8 | **odk-bridge** | 8009 | `/api/v1` | odk_db | Integration | Active |
| 9 | **form-service** | 8010 | `/api/v1` | mquad_forms_db | Forms | Active |
| 10 | **media-service** | 8011 | `/api/v1` | media_db | Infrastructure | Active |
| 11 | **notification-service** | 8012 | `/api/v1` | notification_db | Integration | Active |
| 12 | **audit-service** | 8013 | `/api/v1` | audit_db | Security | Active |
| 13 | **feature-flags-service** | 8014 | `/api/v1` | feature_flags_db | Infrastructure | Active |
| 14 | **quota-service** | 6380 | `/` | — | Core | Active |
| 15 | **scalar-service** | 8030 | `/` | — | Documentation | Active |


## Common Architecture {#common-architecture}


Every microservice follows the same internal structure:

```
service-name/
├── api/
│   ├── __init__.py              # App factory + sys.path hack
│   ├── core/config.py           # Pydantic Settings
│   ├── common/dtos/             # Shared DTOs
│   ├── domain/entities/         # SQLAlchemy models
│   ├── domain/enums/            # Enumerations
│   ├── infrastructure/database.py  # SQLAlchemy async setup
│   ├── interfaces/api_controllers/  # FastAPI endpoints
│   ├── interfaces/middlewares/  # FastAPI middlewares
│   ├── interfaces/security/     # Role checkers
│   └── usecases/                # Business logic
├── alembic/                     # Migrations (unless using create_all)
├── Dockerfile
├── requirements.txt
└── .env
```


## Critical Gotcha {#critical-gotcha}


Each service's `api/__init__.py` must include `sys.path.insert(0, "/opt/common")` **before** importing from `common.*`. This is because the `common/` module is mounted as a Docker volume at `/opt/common`:

```python
import sys
sys.path.insert(0, "/opt/common")

from common.rbac_helpers import is_super_admin
```


## Database Note {#database-note}


The analytics-service uses `Base.metadata.create_all()` instead of Alembic for schema management. Adding columns to an existing table in that service requires manual SQL migration.