Infrastructure Setup & Deployments
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG provides a secure link shortening service for the Singapore government. The infrastructure consists of a Node.js/Express backend, a React frontend, and multiple cloud-native components hosted on AWS. It supports three distinct environments: gov, edu, and health.
Sources: README.md:15-20, webpack.config.ts:46-50
Core System Architecture
The application uses a modular architecture where the backend serves both API requests and static frontend assets. It relies on PostgreSQL for persistent data and Redis for high-performance caching and session management.
The diagram above shows the relationship between the Express server, the load balancer, and the various data storage layers.
Sources: README.md:83-100, src/server/index.ts:160-220, src/server/config.ts:190-200
Infrastructure Components
GoGovSG requires specific managed services to function in production:
- PostgreSQL: Stores long-term mappings between short and long URLs. It includes a master database for writes and a replica for read-heavy operations like redirects.
- Redis: Manages transient data across five distinct logical databases for OTPs, sessions, link redirects, click statistics, and safe browsing cache.
- AWS S3: Hosts user-uploaded files when short links point to documents rather than external URLs.
- AWS Lambda: Executes background tasks such as QR code generation and administrative account migrations.
Sources: README.md:86-98, src/server/config.ts:18-35, src/server/config.ts:192-200
Database Configuration
The application validates database connectivity at boot. It uses a read replica to improve redirect performance when the feature flag FF_USE_REPLICA_FOR_REDIRECTS is enabled.
| Variable | Description | Source |
|---|---|---|
DB_URI | Main PostgreSQL connection string | src/server/config.ts:192 |
REPLICA_URI | Read replica connection string | src/server/config.ts:194 |
DB_POOL_SIZE | Max database connections (default: 40) | src/server/config.ts:223 |
Sources: src/server/config.ts:192-223, src/server/index.ts:145-150
Serverless Functions
The system uses the Serverless Framework to deploy AWS Lambda functions. These functions handle asynchronous or administrative tasks that are outside the main request-response cycle.
Sources: serverless.yml:25-78, README.md:143-160
Function Definitions
| Function Name | Memory | Purpose |
|---|---|---|
migrate-url-to-user | 128MB | Transfers a single URL to a new owner email. |
migrate-user-links | 128MB | Bulk transfers all links from one email to another. |
bulk-qrcode-generation | 8192MB | Generates QR codes in SVG/PNG for bulk uploads. |
capture-ses-events | 128MB | Processes SNS notifications for email delivery events. |
Sources: serverless.yml:25-78, README.md:215-235
Deployment Process
The deployment pipeline utilizes GitHub Actions and the Serverless Framework to target AWS Elastic Beanstalk and AWS Lambda.
Environment Variants
The project uses ASSET_VARIANT to differentiate between the three branding environments. This affects the logo, favicons, and localized copy.
gov: Go.gov.sgedu: for.edu.sghealth: for.sg
Sources: webpack.config.ts:10-45, README.md:246-250
Build and Execution
Deployment involves compiling TypeScript for the server and bundling frontend assets with Webpack.
- Transpilation:
pnpm run buildrunstscandwebpackto generate thebuild/anddist/directories. - Asset Injection: Webpack uses aliases to resolve the correct assets based on the
ASSET_VARIANTenvironment variable. - Production Start: The server starts using
node build/server/index.jswithdd-tracefor Datadog monitoring.
Sources: package.json:17-25, webpack.config.ts:65-80, src/server/index.ts:1-10
Security Configuration
The infrastructure enforces security through several layers of middleware and environment-specific settings:
- Content Security Policy (CSP): Managed via
helmetin the main Express app, restricting script sources to trusted domains like Google Analytics and Datadog. - Cookie Security: In production,
secureflags are set to true, and cookies useStrictsame-site policy. - API Authentication: Uses a salt defined by
API_KEY_SALTfor hashing keys. - Rate Limiting: Enforced for OTP generation to prevent brute force attacks.
Sources: src/server/index.ts:105-140, src/server/config.ts:105-120, README.md:183-185
Summary
The GoGovSG infrastructure is a hybrid architecture combining persistent containerized web servers on Elastic Beanstalk with on-demand Lambda functions. It heavily utilizes Redis for high-speed redirects and session handling, while maintaining strict isolation between the three supported service variants through environment-based asset bundling and localized configurations.
Sources: README.md:15-25, src/server/index.ts:200-220, serverless.yml:1-10