Link Shortening & Management
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG provides an official link shortening service for Singapore government officers, healthcare professionals, and education officers. The system creates recognizable and authenticated short links that redirect users to long URLs or hosted files. Sources: README.md:33-40
The Link Shortening & Management module handles the lifecycle of these links, including creation, ownership transfer, metadata updates, and malicious link deactivation. It supports single link creation, file-based links, and bulk uploads via CSV. Sources: src/server/modules/user/services/UrlManagementService.ts:36-190, src/client/user/components/CreateUrlModal/CreateLinkForm.tsx:45-50
Architecture Overview
The system follows a multi-tier architecture consisting of a React-based frontend, an Express-based backend, and a PostgreSQL database for persistent storage. Redis serves as transient storage for sessions and frequently used shortlinks to optimize redirect performance. Sources: README.md:105-115
Core Components
| Component | Responsibility |
|---|---|
UrlManagementService | Contains business logic for creating, updating, and deactivating links. |
UrlRepository | Interacts with the PostgreSQL database and S3 for link metadata and file storage. |
UserController | Handles HTTP requests, validates input, and invokes service methods. |
CreateLinkForm | Frontend component providing the user interface for link creation. |
S3ServerSide | Manages file uploads to AWS S3 for file-based short links. |
Sources: src/server/modules/user/services/UrlManagementService.ts:28-35, src/server/repositories/UrlRepository.test.ts:58-65, src/server/modules/user/tests/UserController.test.ts:46-55, src/client/user/components/CreateUrlModal/CreateLinkForm.tsx:75-85
Link Creation Workflow
Users can create links through the web console or an external API. The system supports three creation types: standard URL redirects, file-based links, and bulk CSV uploads. Sources: src/client/user/components/CreateUrlModal/CreateLinkForm.tsx:45-50, src/server/modules/user/services/UrlManagementService.ts:56-65
URL and File Creation Logic
When a user submits a link creation request, the system performs the following actions:
- Validates the existence of the user.
- Checks if the requested short URL is available.
- If no short URL is provided (API only), it generates a random string of configured length.
- For file links, it generates an S3 key by adding a file extension to the short URL.
- Calculates the Google Safe Browsing expiry date for the destination URL.
- Persists the link in the database and increments metrics via DogStatsD.
Sources: src/server/modules/user/services/UrlManagementService.ts:66-105
The diagram shows the synchronous flow for creating a new short link through the internal API. Sources: src/server/modules/user/services/UrlManagementService.ts:56-105, test/integration/api/user/Urls.test.ts:68-80
Link Management Operations
Link Updates
Authorized owners can update link metadata, including the destination URL, description, and contact email. However, the system enforces strict rules:
- A long URL cannot be updated for an existing file-based link.
- A file cannot be uploaded to replace a standard URL-based link.
Sources: src/server/modules/user/services/UrlManagementService.ts:121-125
Ownership Transfer
Links can be transferred to new owners. The system validates that the new owner exists and is not the current owner before updating the userId associated with the short URL. Sources: src/server/modules/user/services/UrlManagementService.ts:153-176
Malicious Link Deactivation
The system allows deactivating links identified as malicious. When a link is deactivated, the owner receives an automated email notification. Sources: src/server/modules/user/services/UrlManagementService.ts:200-210
Data Structures and Models
StorableUrl
The primary data structure representing a short link in the repository layer. Sources: src/server/repositories/UrlRepository.test.ts:90-105
| Field | Type | Description |
|---|---|---|
shortUrl | string | The unique slug for the short link. |
longUrl | string | The destination URL or S3 file path. |
state | string | ACTIVE or INACTIVE. |
isFile | boolean | Indicates if the link points to a hosted file. |
clicks | number | Total number of redirects recorded. |
tags | string[] | Array of tags for categorization. |
source | string | CONSOLE, API, or BULK. |
Sources: test/integration/api/user/Urls.test.ts:70-85, src/server/repositories/UrlRepository.test.ts:90-105
File Uploads and Storage
File-based links allow users to host files directly on GoGovSG. Files are uploaded to an AWS S3 bucket. Sources: README.md:120, src/server/repositories/UrlRepository.test.ts:175-185
- Public Access: Files are uploaded with a
PublicACL if the link is active. Sources: src/server/repositories/UrlRepository.test.ts:187-195 - Extension Handling: The system appends the original file extension to the short URL slug to form the S3 object key (e.g.,
short-slug.pdf). Sources: src/server/modules/user/services/UrlManagementService.ts:85-89 - Size Limits: The frontend enforces a maximum file upload size (defaulting to 20MB for files and 1MB for CSVs). Sources: src/client/user/components/CreateUrlModal/CreateLinkForm.tsx:32-35
Bulk Link Creation
The bulk creation feature allows users to upload a CSV file containing multiple long URLs. The system generates random short URLs for each entry and applies a set of common tags to the entire batch. Sources: src/client/user/components/CreateUrlModal/CreateLinkForm.tsx:340-360, src/server/modules/user/services/UrlManagementService.ts:190-198
The flow describes the high-level process of processing bulk link uploads. Sources: src/server/modules/user/services/UrlManagementService.ts:190-198, test/end-to-end/UrlCreation.spec.ts:195-210
Conclusion
Link Shortening & Management in GoGovSG provides a secure and reliable way for government personnel to create and manage official short links. By integrating with AWS S3 for file hosting and providing robust management features like ownership transfer and automated threat deactivation, the system ensures that citizens can trust the links they receive. Sources: README.md:33-45, src/server/modules/user/services/UrlManagementService.ts:200-210