System Architecture 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 officers to create recognisable and authenticated short links for citizens. The system serves three distinct environments—Go.gov.sg, for.edu.sg, and for.sg—using a single codebase with environment-specific assets.
Sources: README.md:12-25
Core Infrastructure
The application runs on a Node.js Express backend and a React frontend. It requires specific infrastructure components to manage data persistence and transient state.
Data Storage Components
- PostgreSQL Database: Stores primary short-long URL mappings and user information.
- Redis Server: Manages transient data across multiple instances, including browser sessions, one-time passwords (OTP), click statistics, and frequently accessed shortlinks.
- AWS S3: Serves as the storage backend for files uploaded by users for file-based shortlinks.
Sources: README.md:68-80, src/server/index.ts:167-175
High-Level Architecture Diagram
The following diagram illustrates the relationship between the client, application server, and backing services.
Sources: README.md:82-156, src/server/index.ts:184-210
Backend Architecture
The backend is built with Express and utilizes InversifyJS for dependency injection. The server entry point is src/server/index.ts, which initializes the database and configures middleware.
Middleware and Security
The server implements several layers of security and request processing:
- Helmet: Configures Content Security Policy (CSP) headers to prevent XSS and other injections.
- Morgan: Logs HTTP requests with custom tokens for client IP, redirect URLs, and user IDs.
- Session Management: Uses
express-sessionwith a Redis store for authenticated sessions. - Body Parser: Handles JSON payloads for API requests.
Sources: src/server/index.ts:32-60, src/server/index.ts:117-158
Routing Structure
The backend separates routes into three primary categories:
| Route Pattern | Description | Controller/Middleware |
|---|---|---|
/api/* | Backend API for user management and link creation. | api module |
/:shortUrl | The core redirect endpoint that resolves short links. | RedirectController.redirect |
/assets/* | Static assets including QR code resources. | express.static |
Sources: src/server/index.ts:215-230
Frontend Architecture
The frontend is a React Single Page Application (SPA) that uses Redux for state management. Webpack bundles the application into a single bundle.js.
Multi-Environment Asset Handling
The system uses "Asset Variants" to serve different branding for government, education, and health sectors. Webpack aliases @assets to a specific directory based on the ASSET_VARIANT environment variable during the build process.
Sources: webpack.config.ts:65-71, README.md:215-220
Client-Side Technology Stack
- React 17: Core UI library.
- Redux & Redux-Thunk: Manages global state and asynchronous actions.
- Material-UI: Provides the component library and styling system.
- i18next: Handles internationalization and localized text.
Sources: package.json:56-90, src/client/user/index.tsx:1-20
Specialized Modules
Bulk QR Code Generation
This module exists as a serverless function to generate QR codes in batches. It uses the qrcode library to generate the base code and cheerio to manipulate the SVG by adding government-specific logos and short URL text.
Link Creation Flow
Users can create links through the web console. The process involves validation against blacklisted domains and circular redirect checks.
Sources: test/end-to-end/UrlCreation.spec.ts:50-75
Deployment and Infrastructure
GoGovSG is deployed using AWS Elastic Beanstalk for the web server and AWS Lambda for background tasks.
| Component | AWS Service |
|---|---|
| Web Application | Elastic Beanstalk |
| Migration Scripts | AWS Lambda |
| QR Code Generation | AWS Lambda |
| File Storage | S3 |
| Task Queue | SQS |
Sources: README.md:167-205
Conclusion
The GoGovSG architecture follows a standard tiered approach, leveraging Node.js for performance and Redis for scalable session management. Its unique multi-tenant asset system allows a single codebase to support multiple government domains while maintaining strict isolation of branding and authorized user groups.
Sources: README.md:215-220, src/server/index.ts:250-265