# opengovsg/plumber architecture

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

- Interactive diagram: https://gitdiagram.com/opengovsg/plumber
- Repository: https://github.com/opengovsg/plumber

## Overview

##### Main components
- Frontend – Found under packages/frontend, built using React with components for editors, dashboards, login forms, and pages for flows, executions, tiles, etc. It integrates with GraphQL (as seen in packages/frontend/src/graphql) and uses Apollo (or similar) for data handling.
- Backend – Present in packages/backend. It is organized in a modular “apps” folder with distinct submodules (e.g., calculator, custom-api, delay, formatter, formsg, lettersg, m365-excel, paysg, postman-sms, slack, telegram-bot, tiles, toolbox, twilio, vault-workspace, webhook, etc.) that encapsulate individual automation tasks.
- Database & Data Stores – The backend includes migrations (using Knex) and seeds in packages/backend/src/db as well as configurations for both relational (likely PostgreSQL) and DynamoDB (see packages/backend/src/config/database.ts and dynamodb.ts). Also, Redis configurations (in packages/backend/src/config/redis.ts) for caching or queues are present.
- API & GraphQL layer – The backend’s GraphQL directory and resolvers (packages/backend/src/graphql) indicate that external clients (including the frontend) interact with the backend primarily through GraphQL endpoints.
- Workers & Queues – There are workers (packages/backend/src/workers) and queues (packages/backend/src/queues) to handle asynchronous processing such as executing automation flows, scheduling, and triggers.
- External Service Integrations – Numerous “apps” (e.g., m365-excel, slack, telegram-bot, twilio, etc.) show how external services and APIs are integrated. Mark these as external systems that interact with the backend.
- Containerization & Deployment – The root-level Dockerfile, .devcontainer configuration, ECS definitions (in the ecs folder), and GitHub workflow files demonstrate that deployment is container-based, with distinct environments (e.g., production, staging, UAT).

##### Relationships and data flows
- Frontend communicates with the backend over GraphQL (indicated by Apollo and the GraphQL client setup) to fetch and send data.
- The backend processes business logic in a modular manner where each “app” (for instance, the calculator or formsg module) encapsulates its own actions and tests. These modules connect to controllers, services, models, and follow a layered architecture.
- The GraphQL API aggregates different business logic components and interacts with the database, message queues, and external services.
- Workers and queues run background tasks (for automation flows, executing jobs, and handling triggers) and interface with the database and external API endpoints.
- External systems (government services and commercial apps) interface with specific app modules like m365-excel, slack, and others—often through REST or custom integrations.

##### Architectural patterns and design principles
- Modular Monorepo – The project is organized into separate packages (backend, frontend, types), enabling a clean separation of concerns.
- Layered Architecture – The backend is divided into configuration, controllers, models, services, and workers. There’s also dedicated handling for error management, testing, and GraphQL API layers.
- Microservice-like Modular Apps – Although it is not split into completely independent services, each “app” under packages/backend/src/apps behaves similarly to a microservice by encapsulating its logic, tests, and assets.
- Containerization and CI/CD – With Docker, ECS configurations, and multiple GitHub workflow files, the project makes extensive use of containerization and automated deployments.

- Use clear labels for each component (e.g., “React Frontend”, “GraphQL API”, “Business Logic Modules”, “Relational Database”, “DynamoDB”, “External Service: Slack”, “Queue Worker”, etc.).
– From the frontend to the API layer.
– From API to the business logic modules.
– From the business logic modules to databases and external services.
– From queues to background workers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Section
    subgraph "Frontend"
        FE["React Frontend"]:::frontend
    end

    %% Backend Section
    subgraph "Backend"
        BE["Backend Engine"]:::backend
        API["GraphQL API"]:::api
        MA["Modular Apps"]:::module
        DB["SQL Database (PostgreSQL)"]:::database
        NOSQL["NoSQL & Cache (DynamoDB & Redis)"]:::database
        Q["Queues"]:::queue
        W["Workers"]:::worker
        subgraph "External Integrations"
            SL["Slack Integration"]:::external
            TB["Telegram Bot"]:::external
            TW["Twilio Integration"]:::external
        end
    end

    %% Deployment Infrastructure Section
    subgraph "Deployment Infrastructure"
        CC["Container Config"]:::container
        CICD["CI/CD Pipelines"]:::container
    end

    %% Data Flow Connections
    FE -->|"queries"| API
    BE --> API
    API -->|"calls"| MA
    API -->|"reads/writes"| DB
    API -->|"reads/writes"| NOSQL
    MA -->|"triggers"| Q
    Q -->|"processes"| W
    MA -->|"integrates"| SL
    MA -->|"integrates"| TB
    MA -->|"integrates"| TW
    CC --> FE
    CC --> BE
    CICD --> FE
    CICD --> BE

    %% Click Events
    click FE "https://github.com/opengovsg/plumber/tree/develop-v2/packages/frontend"
    click BE "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend"
    click API "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/graphql"
    click MA "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/apps"
    click DB "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/db"
    click NOSQL "https://github.com/opengovsg/plumber/blob/develop-v2/packages/backend/src/config/dynamodb.ts"
    click Q "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/queues"
    click W "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/workers"
    click SL "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/apps/slack"
    click TB "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/apps/telegram-bot"
    click TW "https://github.com/opengovsg/plumber/tree/develop-v2/packages/backend/src/apps/twilio"
    click CC "https://github.com/opengovsg/plumber/tree/develop-v2/Dockerfile"
    click CICD "https://github.com/opengovsg/plumber/tree/develop-v2/.github/workflows"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef backend fill:#F7E1AE,stroke:#333,stroke-width:2px;
    classDef api fill:#F7A1AE,stroke:#333,stroke-width:2px;
    classDef module fill:#D1F7AE,stroke:#333,stroke-width:2px;
    classDef database fill:#C7CEEA,stroke:#333,stroke-width:2px;
    classDef queue fill:#E2CFCF,stroke:#333,stroke-width:2px;
    classDef worker fill:#E2CFF7,stroke:#333,stroke-width:2px;
    classDef external fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef container fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
