Backend design

Een RESTful API gebouwd met AWS Chalice en AWS Cognito voor gebruikersauthenticatie en autorisatie.

---

Overzicht

De VEMAP Backend biedt een complete applicatie met ondersteuning voor:

• Gebruikerslogin met AWS Cognito
• Challenge-gebaseerde authenticatie (bijv. wachtwoordwijzigingen)
• Token vernieuwingsfunctionaliteit
• Rol-gebaseerde toegangscontrole
• Tenant en gebruikersbeheer
• Project en afsluiting beheer
• Bestandsbeheer en uploads
• Email notificaties via AWS SES
• Gestructureerde logging voor monitoring en auditing

---

Projectstructuur

• Directorybackend/

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

    • Directoryaws/ # AWS service integraties (S3, SES, SQS)

      • …
    • Directoryconfig/ # Configuratiebeheer

      • …
    • Directorycontrollers/ # HTTP request handlers

      • …
    • Directoryfactory/ # Dependency injection

      • …
    • Directorymiddleware/ # Request/response middleware

      • …
    • Directorymodels/ # Pydantic request/response models

      • …
    • Directoryqueries/ # SQL query definities

      • …
    • Directoryrepositories/ # Database toegang laag

      • …
    • Directoryservices/ # Business logic

      • …
    • Directoryutils/ # Utility functies

      • …
• Directorytests/ # Test suite

  • …
• requirements.txt # Productie dependencies
• requirements-dev.txt # Development dependencies (tests)

Authenticatie Flow

Standaard Login

1. Gebruiker dient credentials in via POST /v1/authentication/login
2. API valideert met AWS Cognito
3. Bij succes: Retourneert tokens + gebruikersomgevingen
4. Bij challenge vereist: Retourneert challenge data (302 status)

Challenge Authenticatie

1. Gebruiker ontvangt challenge response van login
2. Gebruiker dient challenge response in via POST /v1/authentication/challenge
3. API voltooit challenge met AWS Cognito
4. Retourneert tokens + gebruikersomgevingen (zelfde als succesvolle login)

Token Vernieuwing

1. Gebruiker dient refresh token in via POST /v1/authentication/refresh
2. API vernieuwt tokens met AWS Cognito
3. Retourneert nieuwe access, refresh en ID tokens

Snelle Start

Vereisten

• Python 3.8+
• AWS CLI geconfigureerd
• AWS Cognito User Pool en App Client

Installatie

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

# Installeer dependencies
pip install -r requirements.txt

# Voor development: installeer ook test dependencies
pip install -r requirements-dev.txt


# Start lokaal
chalice local

Environment Variables

CLIENT_ID=your-cognito-app-client-id
POOL_ID=your-cognito-user-pool-id

API Endpoints

Authenticatie

Naar authenticatie endpointdocumentatie

Methode	Endpoint	Beschrijving	Toegang
GET	/health	Health check	Publiek
POST	/v1/authentication/login	Gebruikerslogin	Publiek
POST	/v1/authentication/challenge	Voltooi authenticatie challenge	Publiek
POST	/v1/authentication/refresh	Vernieuw access tokens	Publiek
POST	/v1/authentication/logout	Gebruikerslogout	Publiek
POST	/v1/authentication/forgot-password	Initieer wachtwoord reset	Publiek
POST	/v1/authentication/reset-password	Reset wachtwoord met code	Publiek

Gebruikers

Naar gebruiker endpointdocumentatie

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/users	Haal gebruikers op	Admin, Organisatie, Manager
POST	/v1/{tenant_id}/users	Maak nieuwe gebruiker	Admin, Organisatie, Manager
PATCH	/v1/{tenant_id}/users/{user_id}	Update gebruiker	Admin, Organisatie, Manager
DELETE	/v1/{tenant_id}/users/{user_id}	Verwijder gebruiker	Admin, Organisatie, Manager

Tenants

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/tenants	Haal tenants op	Admin
POST	/v1/{tenant_id}/tenants	Maak nieuwe tenant	Admin
DELETE	/v1/{tenant_id}/tenants/{target_tenant_id}	Verwijder tenant	Admin

Projecten

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/projects	Haal projecten op	Organisatie, Manager
POST	/v1/{tenant_id}/projects	Maak nieuw project	Organisatie, Manager
PATCH	/v1/{tenant_id}/projects/{project_id}	Update project	Organisatie, Manager
GET	/v1/{tenant_id}/projects/{project_id}/closure-references	Haal closure referenties op	Manager
GET	/v1/{tenant_id}/projects/{project_id}/closures	Haal closures van project op	Manager, Stakeholder
GET	/v1/{tenant_id}/projects/{project_id}/recipients	Haal project ontvangers op	Organisatie, Manager
POST	/v1/{tenant_id}/projects/{project_id}/recipients	Voeg ontvangers toe aan project	Organisatie, Manager
DELETE	/v1/{tenant_id}/projects/{project_id}/recipients/{recipient_id}	Verwijder ontvanger van project	Manager

Afsluitingen

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/projects/{project_id}/closures	Haal closures van project op	Manager, Stakeholder
GET	/v1/{tenant_id}/closures/{closure_id}	Haal specifieke closure op	Manager, Stakeholder
POST	/v1/{tenant_id}/closures	Maak nieuwe closure	Manager
GET	/v1/{tenant_id}/closures/{closure_id}/files	Haal bestanden van closure op	Manager, Stakeholder
POST	/v1/{tenant_id}/closures/{closure_id}/stakeholders	Voeg stakeholders toe aan closure	Manager
DELETE	/v1/{tenant_id}/closures/{closure_id}/stakeholders/{stakeholder_id}	Verwijder stakeholder van closure	Manager
GET	/v1/{tenant_id}/closures/{closure_id}/comments	Haal comments van closure op	Manager, Stakeholder
POST	/v1/{tenant_id}/closures/{closure_id}/comments	Maak nieuwe comment	Stakeholder
GET	/v1/{tenant_id}/closures/{closure_id}/events	Haal events van closure op	Manager, Stakeholder

Bestanden

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/files/{file_id}	Haal specifiek bestand op	Manager, Stakeholder
POST	/v1/{tenant_id}/files	Upload bestand metadata	Manager
PATCH	/v1/{tenant_id}/files/{file_id}	Update bestand metadata	Admin, Organisatie, Manager
DELETE	/v1/{tenant_id}/files/{file_id}	Verwijder bestand	Admin, Organisatie, Manager

Stakeholders

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/stakeholders/{user_id}/closures	Haal closures van stakeholder op	Stakeholder

Monitoring

Methode	Endpoint	Beschrijving	Toegang
GET	/v1/{tenant_id}/metrics	Haal metrics op	Admin, Organisatie, Manager, Stakeholder

Email

Methode	Endpoint	Beschrijving	Toegang
POST	/v1/{tenant_id}/mail/{closure_id}	Verstuur mail voor closure	Admin, Organisatie, Manager
POST	/v1/{tenant_id}/mail/recipients/{project_id}	Maak ontvangers voor project/closure	Admin, Organisatie, Manager
DELETE	/v1/{tenant_id}/mail/recipients/{project_id}/{closure_id}/{recipient_id}	Verwijder ontvanger	Admin, Organisatie, Manager
GET	/v1/{tenant_id}/mail/templates	Haal email templates op	Admin, Organisatie, Manager
POST	/v1/{tenant_id}/mail/templates	Maak nieuwe email template	Admin, Organisatie, Manager

Architectuur

Design Patterns

• MVC Pattern: Controllers handelen HTTP requests af, Services bevatten business logic
• Repository Pattern: Database toegang geabstraheerd via repositories
• Factory Pattern: Dependency injection voor service creatie
• Middleware Pattern: Request/response verwerking en authenticatie

Belangrijke Componenten

• Controllers: HTTP request handling en response formatting
• Services: Business logic en externe service integratie
• Repositories: Database toegang en data persistentie
• Queries: SQL query definities en database operaties
• Middleware: Authenticatie, error handling en request verwerking
• Models: Pydantic models voor request/response validatie
• Utils: Utility functies voor logging, authenticatie, error handling

Beveiligingskenmerken

• AWS Cognito integratie voor veilige authenticatie
• JWT token-gebaseerde autorisatie
• Rol-gebaseerde toegangscontrole (RBAC)
• Gestructureerde logging voor audit trails en monitoring
• CORS configuratie voor frontend integratie
• Input validatie via Pydantic models
• Gecentraliseerde error handling

---

Logging

De VEMAP Backend gebruikt een gestructureerd logging systeem voor monitoring en audit trails. Alle logs worden als JSON uitgevoerd voor eenvoudige integratie met CloudWatch Logs.

Event Types

Het logging systeem gebruikt vier gestandaardiseerde event types:

• SUCCESS - Voor succesvolle business operaties
• FAILED - Voor gefaalde operaties (niet-kritieke fouten)
• ERROR - Voor kritieke errors
• WARNING - Voor waarschuwingen

Business Event Structuur

Business events worden gelogd met een vereenvoudigde structuur waarbij de event_type alleen de status bevat en alle contextuele informatie in event_data staat:

self.logger.log_business_event(
    "SUCCESS",
    {
        "action": "create_project",
        "tenant_id": tenant_id,
        "user_id": user_id,
        "project_id": project_id
    }
)

Belangrijke velden:

• event_type: Status woord (SUCCESS, FAILED, ERROR, WARNING)
• event_data.action: Beschrijvende actie naam (bijv. “create_project”, “login”)
• event_data: Alle relevante contextuele informatie
• request_id: Automatisch toegevoegd voor request tracking

Wanneer te Loggen

Loggen:

• CREATE/DELETE operaties voor belangrijke entiteiten
• Authentication events (login, logout, password reset)
• File uploads (initiatie)
• Email operations (batch level)
• Errors (gecentraliseerd door middleware)

NIET loggen:

• Routine GET requests
• Routine updates van niet-kritieke data
• Middleware info logs
• Debug logs in productie

Error Logging

Error logging is gecentraliseerd: services gooien exceptions zonder te loggen, middleware en error handlers loggen alle errors met "ERROR" als message en een action field voor context.

Ontwikkeling

Tests Uitvoeren

# Zorg dat development dependencies geïnstalleerd zijn
pip install -r requirements-dev.txt

# Voer tests uit
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
• Geen comments, wel docstrings

Deployment

# Deploy naar AWS
# Deploy naar development omgeving
chalice deploy --stage dev

# Deploy naar production omgeving
chalice deploy --stage prod