How opengovsg/plumber works
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.