GoGovSG Overview
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG is the official Singapore government link shortener. It provides a secure platform for authorized public officers, education officers, and healthcare professionals to create recognizable and authenticated short links. By using official domains, the system protects citizens against phishing and ensures that shortened URLs are trustworthy and official.
The codebase supports three distinct environment variants—Go.gov.sg, for.edu.sg, and for.sg—using a single repository with multi-tenant asset configurations. It provides features for link management, file sharing, bulk QR code generation, and click analytics.
Sources: README.md:15-26, src/server/config.ts:223-228
System Architecture
GoGovSG follows a client-server architecture. The frontend is built with React and Redux, while the backend uses Node.js and Express. The system relies on a PostgreSQL database for persistent storage and multiple Redis instances for caching, session management, and statistics.
Component Diagram
The diagram below illustrates the high-level relationship between the client, application server, and data storage layers.
Sources: README.md:73-81, src/server/config.ts:16-30
Environment Variants
The application uses the ASSET_VARIANT environment variable to determine branding, meta tags, and authorized email domains.
| Variant | Domain | Target Users |
|---|---|---|
gov | go.gov.sg | Public officers |
edu | for.edu.sg | Education officers |
health | for.sg | Healthcare professionals |
Sources: webpack.config.ts:18-47, src/server/config.ts:223-228
Infrastructure and Configuration
The system requires several infrastructure components for production operation. Configuration is managed via environment variables that define database connections, security salts, and feature flags.
Key Infrastructure Requirements
- PostgreSQL: Stores short-to-long URL mappings. A replica can be configured for redirects using the
FF_USE_REPLICA_FOR_REDIRECTSflag. - Redis: Used in a segmented manner for OTP hashes, sessions, redirect caching, statistics, and safe browsing results.
- AWS S3: Stores user-uploaded files for file-based short links.
- AWS SQS: Manages triggers for asynchronous tasks like bulk QR code generation.
Sources: README.md:73-85, src/server/config.ts:16-30, src/server/config.ts:182-184
Environment Configuration
The following table summarizes critical server environment variables:
| Variable | Required | Description |
|---|---|---|
DB_URI | Yes | Primary PostgreSQL connection string |
REPLICA_URI | Yes | Replica PostgreSQL connection string |
REDIS_REDIRECT_URI | Yes | Redis instance for short link caching |
VALID_EMAIL_GLOB_EXPRESSION | Yes | Glob pattern for authorized email domains |
FF_EXTERNAL_API | No | Flag to enable external and admin APIs |
Sources: README.md:95-163, src/server/config.ts:23-35
Core Features and Data Flow
Link Creation and Redirection
The system validates long URLs to prevent circular redirects (pointing to itself) and checks against blacklists or safe browsing APIs.
Bulk QR Code Generation
The system supports generating QR codes in bulk. This process is handled by a serverless function that combines a generated QR code with the official variant logo and short link text.
- URL Processing: Splits the target URL into manageable lines for text rendering.
- QR Generation: Uses
qrcodeto generate a base SVG. - Logo Overlay: Injects the variant-specific logo (e.g.,
qrlogo-gov.svg) into the center of the QR code. - Text Rendering: Appends the human-readable shortlink at the bottom of the image using IBM Plex Sans.
Sources: src/server/serverless/bulk-qrcode-generation/qrCode.js:50-138
Development and Deployment
Build Pipeline
The project uses pnpm for package management and webpack for bundling client assets.
- Linting: Uses
oxlintfor high-performance JavaScript/TypeScript linting. - Transpilation: Uses
babelandswc-loaderfor supporting modern JS features and IE11 compatibility. - Styling: Utilizes Material-UI (
@material-ui/core) for the user interface.
Sources: package.json:9-25, webpack.config.ts:104-125
Local Development
To run the environment locally:
- Clone the repository and run
pnpm install. - Start the development environment using
pnpm run dev. This spins up PostgreSQL and Redis via Docker Compose. - The webpack dev server listens on port 3000, while the backend API listens on port 8080.
Sources: README.md:46-64, package.json:16-19
GoGovSG serves as a critical piece of Singapore's digital infrastructure, providing a centralized and secure method for government entities to share information. Its multi-tenant architecture and strict validation rules ensure link integrity across the government, education, and health sectors.