# wfp-vam/dmp architecture

> Architecture diagram of the GitHub repository wfp-vam/dmp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wfp-vam/dmp
- Repository: https://github.com/wfp-vam/dmp

## Overview

##### Project type and purpose
- This is a full-stack, monorepo-style form management tool (“DMP”) built for the World Food Programme Cambodia.
- It consists of three primary “apps”:
- apps/frontend – a Next.js/React UI for users to log in, fill and review disaster-related forms
- apps/backend – a NestJS REST API for authentication, user & campaign management, form persistence, and webhook handling
- apps/backend-infrastructure – an AWS CDK stack provisioning VPC, ECS services, RDS, certificates, Route53 records, etc.
- Shared TypeScript definitions live under packages/interfaces; linting, CI/CD configs and scripts at the root.

##### File structure
- Top-level directories:
- apps/ – frontend, backend code and infra
- packages/ – shared configs and interfaces
- .github/workflows – CI pipelines for lint, test, staging & production merges
- turbo.json, pnpm-workspace.yaml – orchestrate monorepo builds
- apps/backend:
- NestJS modules: auth, user, kob o integrations, webhook, logger
- datasource & TypeORM migrations targeting an RDS database
- Dockerfile + docker-compose for local development
- apps/frontend:
- Next.js pages & components implementing forms, reports, filters
- React Query or SWR hooks under services/api
- Environment management for production, staging, test
- docs under apps/frontend/docs describing architecture, deploy, error handling
- apps/backend-infrastructure:
- CDK constructs for network (VPC), container clusters (ECS service), database (RDS), certificates, DNS

##### README.md
- High-level description: “form management tool” for disaster relief
- Instructions defer into backend README for more details

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web Browser/Mobile Browser"]:::ui
    end

    %% Frontend Layer
    subgraph "Frontend App" 
        NextJS["Next.js Frontend App"]:::ui
        Pages["Frontend Pages (SSR/SSG)"]:::ui
        Components["React Components"]:::ui
        APIHooks["API Hooks (React Query/SWR)"]:::ui
        EnvConfigs["Environment Configs"]:::ui
        Docs["Frontend Documentation"]:::ui
    end

    %% Shared Interfaces
    Shared["Shared TypeScript Interfaces"]:::shared

    %% Backend API Layer
    subgraph "Backend API"
        NestApp["NestJS Backend API"]:::api
        AuthMod["Auth Module"]:::api
        UserMod["User Management Module"]:::api
        KoboMod["KoboToolbox Integration Module"]:::api
        WebhookMod["Webhook (Telegram) Module"]:::api
        LoggerMod["Custom Logger Module"]:::api
        Datasource["TypeORM Datasource & Migrations"]:::api
        DockerCfg["Docker Config"]:::api
    end

    %% Data Layer
    Database["PostgreSQL RDS"]:::data

    %% External Services
    subgraph "External Services"
        KoboAPI["KoboToolbox API"]:::external
        TelegramAPI["Telegram Bot API"]:::external
    end

    %% Infrastructure Layer
    subgraph "AWS Infrastructure"
        CDKStack["AWS CDK Infra Stack"]:::infra
        VPC["VPC Construct"]:::infra
        ECS["ECS Service Construct"]:::infra
        RDSConstruct["RDS Construct"]:::infra
        Cert["ACM Certificate Construct"]:::infra
        DNS["Route53 Record Construct"]:::infra
        NestStack["NestJS ECS Stack"]:::infra
    end

    %% CI/CD Layer
    subgraph "CI/CD Pipelines"
        CI["GitHub Actions CI/CD"]:::ci
        Orch["PNPM/Turbo Orchestration"]:::ci
    end

    %% Connections
    Browser -->|"loads"| NextJS
    NextJS -->|"calls REST API"| NestApp
    NextJS --> Shared
    NestApp --> AuthMod
    NestApp --> UserMod
    NestApp --> KoboMod
    NestApp --> WebhookMod
    NestApp --> LoggerMod
    NestApp --> Datasource
    NestApp --> DockerCfg
    AuthMod -->|"issues/verifies JWT"| NestApp
    NestApp --> Database
    KoboMod --> KoboAPI
    WebhookMod --> TelegramAPI
    NestApp --> Shared
    CDKStack --> VPC
    CDKStack --> ECS
    CDKStack --> RDSConstruct
    CDKStack --> Cert
    CDKStack --> DNS
    CDKStack --> NestStack
    CI -->|"deploy infra"| CDKStack
    CI -->|"deploy frontend"| NextJS
    CI -->|"deploy backend"| ECS
    Orch --> NextJS
    Orch --> NestApp
    Orch --> Shared

    %% Click Events
    click NextJS "https://github.com/wfp-vam/dmp/tree/main/apps/frontend"
    click Pages "https://github.com/wfp-vam/dmp/tree/main/apps/frontend/pages"
    click Components "https://github.com/wfp-vam/dmp/tree/main/apps/frontend/components"
    click APIHooks "https://github.com/wfp-vam/dmp/tree/main/apps/frontend/services/api"
    click EnvConfigs "https://github.com/wfp-vam/dmp/blob/main/apps/frontend/.env.sample"
    click EnvConfigs "https://github.com/wfp-vam/dmp/blob/main/apps/frontend/.env.staging"
    click EnvConfigs "https://github.com/wfp-vam/dmp/blob/main/apps/frontend/.env.production"
    click EnvConfigs "https://github.com/wfp-vam/dmp/blob/main/apps/frontend/.env.test"
    click Docs "https://github.com/wfp-vam/dmp/tree/main/apps/frontend/docs"
    click NestApp "https://github.com/wfp-vam/dmp/tree/main/apps/backend"
    click AuthMod "https://github.com/wfp-vam/dmp/tree/main/apps/backend/src/modules/auth"
    click UserMod "https://github.com/wfp-vam/dmp/tree/main/apps/backend/src/modules/user"
    click KoboMod "https://github.com/wfp-vam/dmp/tree/main/apps/backend/src/modules/kobo"
    click WebhookMod "https://github.com/wfp-vam/dmp/tree/main/apps/backend/src/modules/webhook"
    click LoggerMod "https://github.com/wfp-vam/dmp/tree/main/apps/backend/src/modules/logger"
    click Datasource "https://github.com/wfp-vam/dmp/blob/main/apps/backend/src/datasource.options.js"
    click Datasource "https://github.com/wfp-vam/dmp/blob/main/apps/backend/datasource.js"
    click Datasource "https://github.com/wfp-vam/dmp/tree/main/apps/backend/migration"
    click DockerCfg "https://github.com/wfp-vam/dmp/tree/main/apps/backend/Dockerfile"
    click DockerCfg "https://github.com/wfp-vam/dmp/blob/main/apps/backend/docker-compose.yml"
    click CDKStack "https://github.com/wfp-vam/dmp/tree/main/apps/backend-infrastructure"
    click VPC "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/vpc.ts"
    click ECS "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/ecs-service.ts"
    click RDSConstruct "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/database.ts"
    click Cert "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/certificate.ts"
    click DNS "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/route53-record.ts"
    click NestStack "https://github.com/wfp-vam/dmp/blob/main/apps/backend-infrastructure/lib/nestStack.ts"
    click Shared "https://github.com/wfp-vam/dmp/tree/main/packages/interfaces/src"
    click Orch "https://github.com/wfp-vam/dmp/blob/main/pnpm-workspace.yaml"
    click Orch "https://github.com/wfp-vam/dmp/blob/main/turbo.json"
    click CI "https://github.com/wfp-vam/dmp/blob/main/.github/workflows/ci.yml"
    click CI "https://github.com/wfp-vam/dmp/blob/main/.github/workflows/merge-staging.yml"
    click CI "https://github.com/wfp-vam/dmp/blob/main/.github/workflows/merge-production.yml"

    %% Styles
    classDef ui fill:#e0f7e9,stroke:#2e7d32,color:#2e7d32
    classDef api fill:#e3f2fd,stroke:#1565c0,color:#1565c0
    classDef data fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef infra fill:#eceff1,stroke:#546e7a,color:#37474f
    classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
    classDef shared fill:#fce4ec,stroke:#ad1457,color:#880e4f
    classDef ci fill:#f3e5f5,stroke:#8e24aa,color:#6a1b9a
```
