MMMS Backend Design

Een RESTful API gebouwd met AWS Chalice en PostgreSQL voor email verzending met API key authenticatie, SQS queue processing en structured logging.

De MMMS Backend biedt een complete email microservice met ondersteuning voor:

• Email verzending via AWS SES
• SQS Queue processing voor bulk emails
• API Key authenticatie met origin validatie
• PostgreSQL database voor API keys en origins
• Structured logging en error handling
• Pydantic model validatie

---

Projectstructuur

• Directorybackend/

  • app.py # Hoofdapplicatie entry point
  • Directorychalicelib/ # Applicatiebibliotheek

    • Directoryaws/ # AWS service integraties

      • …
    • Directorycontrollers/ # HTTP request handlers

      • …
    • Directorydatabase/ # Database laag

      • …
    • Directorymodels/ # Pydantic data models

      • …
    • Directoryqueries/ # SQL queries

      • …
    • Directoryrepositories/ # Data access

      • …
    • Directoryservices/ # Business logic

      • …
    • Directoryutils/ # Utility functies

      • …
• Directorytests/ # Test suite

  • …
• requirements.txt # Python dependencies

Email Verzending Flow

Single Email Verzending

1. Client dient email request in via POST /v1/mail
2. API valideert API key en origin via middleware
3. Request wordt gevalideerd met Pydantic models
4. Email wordt verzonden via AWS SES
5. Status wordt gepubliceerd naar result queue
6. Response wordt teruggestuurd naar client

Bulk Email Verzending (SQS)

1. Client dient bulk email request in via POST /v1/mail
2. API valideert en publiceert naar processing queue
3. SQS Consumer Lambda verwerkt berichten (batch_size=10)
4. Voor elke recipient wordt email verzonden via SES
5. Status wordt gepubliceerd naar result queue
6. VEMAP Backend ontvangt status updates

Snelle Start

Vereisten

• Python 3.12+
• AWS CLI geconfigureerd
• PostgreSQL database (AWS RDS)
• AWS SES verified identities
• AWS SQS queues

Installatie

# Clone de repository
git clone <repository-url>
cd MMMS/backend

# Installeer dependencies
pip install -r requirements.txt

# Stel environment variables in
# Bewerk .chalice/config.json met je AWS configuratie

# Start lokaal
chalice local

Environment Variables

{
  "environment_variables": {
    "SECRET_NAME": "postgresql-01-secret",
    "DB_NAME": "mmms",
    "MAIL_QUEUE_URL": "https://sqs.eu-central-1.amazonaws.com/.../processing-queue",
    "MAIL_RESULT_QUEUE_URL": "https://sqs.eu-central-1.amazonaws.com/.../result-queue"
  }
}

API Endpoints

Health Check

Naar health check API referenties →

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/health	Health check	Publiek

Mail

Naar mail API referenties →

Methode	Endpoint	Beschrijving	Toegang
POST	/v1/mail	Verstuur email	API Key

API Key Management

Naar API key API referenties →

Methode	Endpoint	Beschrijving	Toegang
POST	/v1/api-key	Maak nieuwe API key	Publiek
DELETE	/v1/api-key/{api_key}	Verwijder API key	Publiek
POST	/v1/api-key/{api_key}/origins	Voeg origins toe aan API key	Publiek

Architectuur

Design Patterns

• MVC Pattern: Controllers handelen HTTP requests af, Services bevatten business logic
• Repository Pattern: Database toegang geabstraheerd via repositories
• Middleware Pattern: Request/response verwerking en authenticatie
• SQS Pattern: Asynchrone message processing voor bulk operations

Belangrijke Componenten

• Controllers: HTTP request handling en response formatting
• Services: Business logic en externe service integratie
• Repositories: Database toegang en data persistentie
• Middleware: Authenticatie, logging en request verwerking
• Models: Pydantic data validatie en serialization

SQS Queue Processing

Processing Queue Flow

sequenceDiagram
    participant Client
    participant MMMS
    participant SQS Processing
    participant Lambda Consumer
    participant SES
    participant SQS Result

    Client->>MMMS: POST /v1/mail (bulk)
    MMMS->>SQS Processing: Send message
    SQS Processing->>Lambda Consumer: Trigger (batch_size=10)
    Lambda Consumer->>Lambda Consumer: Process each message
    Lambda Consumer->>SES: Send email
    SES-->>Lambda Consumer: Response
    Lambda Consumer->>SQS Result: Publish status
    Lambda Consumer->>SQS Processing: Delete message

Kritieke Punten

• Message Processing: process_email_from_queue() moet ALTIJD succesvol returnen
• Error Handling: Exceptions in Lambda Consumer leiden tot oneindige retry loop
• Batch Processing: Max 10 messages per batch voor optimale performance
• Status Tracking: Alle email status updates worden gepubliceerd naar result queue

Beveiligingskenmerken

• API Key authenticatie met origin validatie
• PostgreSQL database voor secure credential storage
• AWS Secrets Manager voor database credentials
• Request/response logging voor audit trails
• CORS configuratie voor frontend integratie
• Pydantic model validatie voor input sanitization

Ontwikkeling

Tests Uitvoeren

python -m pytest tests/

Code Stijl

Het project volgt PEP 8 richtlijnen en gebruikt:

• Type hints voor betere code documentatie
• Uitgebreide logging voor debugging
• Error handling met juiste HTTP status codes
• Pydantic models voor data validatie
• Geen try/except in controllers (errors bubblen naar middleware)

Deployment

# Deploy naar AWS
chalice deploy

# Deploy naar specifieke stage
chalice deploy --stage production