User Link Directory & Search
Relevant source files
The following files were used as context for generating this wiki page:
User Link Directory & Search is a core system within GoGovSG that enables public officers and citizens to discover and manage official short links. The system provides two primary interfaces: a public-facing Directory for searching links across the platform and a private User Page for officers to search and filter their own created links.
The system handles high-volume queries using a combination of PostgreSQL full-text search and indexed metadata. It supports advanced filtering by link status, content type (URL vs. File), tags, and ownership email addresses.
Sources: src/client/directory/index.tsx, test/end-to-end/DirectoryFilter.spec.ts, test/end-to-end/UserPage.spec.ts
Directory Architecture & Data Flow
The Directory interface uses a React-based frontend that communicates with the backend via Redux actions. It manages search state through URL query parameters, allowing users to share specific search results or filtered views.
Search Execution Flow
When a user interacts with the Directory search bar or filter panel, the application follows this execution path:
- Input Capture: The
DirectoryHeadercomponent captures text input or filter changes. - Debouncing: For text queries, a 500ms debounce prevents excessive API calls during typing.
- State Synchronization: New parameters are pushed to the browser's history, updating the URL.
- Data Fetching: An effect hook detects URL changes and dispatches the
getDirectoryResultsaction. - Repository Query: The backend
UrlRepositoryexecutes a raw Sequelize query against the database usingDirectoryQueryConditions.
The diagram above shows the lifecycle of a search request from user input to database retrieval.
Sources: src/client/directory/index.tsx:112-212, test/server/repositories/UrlRepository.test.ts:466-508
Search Components & Parameters
The system supports various parameters to refine search results. These parameters are shared between the directory search and the internal user link management table.
| Parameter | Type | Description |
|---|---|---|
query | string | The keyword or email address to search for. |
sortOrder | string | Determines result order: RELEVANCY, RECENCY, or POPULARITY. |
state | string | Filters by link status: ACTIVE or INACTIVE. |
isFile | boolean | Filters specifically for file-based short links. |
isEmail | boolean | If true, treats the query as an email address/domain search. |
tags | string[] | Filters links containing specific user-defined tags. |
Sources: src/client/directory/index.tsx:24-32, src/server/modules/user/tests/UserController.test.ts:316-368
User Page Search Logic
Unlike the global directory, the User Page focuses on link management. It allows officers to search their own links by short URL slug, original long URL, or tags.
Tag-Based Filtering
The User Page implements an OR-condition search for tags. When multiple tags are selected, the system returns links that contain at least one of the specified tags. Tags are stored as a semicolon-separated string (tagStrings) in the database to optimize search performance.
This sequence shows how clicking a tag chip triggers a filtered refresh of the user's link table.
Sources: test/end-to-end/UserPage.spec.ts:107-160, src/server/modules/user/tests/UserController.test.ts:251-300
Implementation Details
Database Repository Methods
The UrlRepository provides specialized methods for search and directory listing:
- rawDirectorySearch: Executes complex SQL to search by keyword or email domain. It supports filtering by
isFileandstate. - getUrlsWithConditions: Used by the User Page to retrieve a specific user's links with support for pagination, sorting by
clicksorcreatedAt, and tag filtering.
Sources: test/server/repositories/UrlRepository.test.ts:466-508, src/server/modules/user/tests/UserController.test.ts:303-455
Input Validation
The UserController validates search and filter inputs before passing them to the service layer:
- Tag Length: Tags must not exceed 25 characters.
- Tag Count: Searches are limited to a maximum of 5 tags simultaneously.
- Search Text: General search queries must meet minimum character requirements to prevent performance degradation.
Sources: src/server/modules/user/tests/UserController.test.ts:400-435
Conclusion
The User Link Directory & Search system provides a robust mechanism for both discovery and management of official links. By utilizing debounced client-side state management and optimized repository queries, the system maintains high performance while supporting complex filtering requirements like tag-based OR searches and email domain lookups.
Sources: src/client/directory/index.tsx, test/end-to-end/DirectoryFilter.spec.ts