Short URL

Introduction

I built this project while documenting the architectural decisions behind it, evolving the system incrementally from a simple proof of concept to the final architecture.

Architecture v1

Description

ShortURL is in its initial stage. The idea is to build an application that takes a long-form URL and turns it into a short one.

Example: Take a long-form URL such as:

https://yasserjaffer.com/writing/technical-debt-how-legacy-systems-are-created

And turn it into something similar to

https://BaseURL/FyZS1j

Design

The initial design will only include a backend service to validate the implementation as a POC.
The implementation will only include a POST request to generate the short URL.

Problem

One problem to keep in mind that could become an issue later as the application starts to scale is the generation method:

• Can the generation method always generate unique codes?

• Could different URLs generate the same code?

The initial POC will test and validate this possibility

Architecture Diagrams

Flowchart

Sequence Diagram

Testing

The first implementation testing resulted in the following

Request

{
    "url": "https://yasserjaffer.com/writing/technical-debt-how-legacy-systems-are-created"
}

Response

{
    "shortUrl": "G5pY2F"
}

Problem

The problem referenced above was identified using auto-generated URLs:

URL 1: https://example.com/52941347-9497-47E6-9772-51EFDE744394
URL 2: https://example.com/74641B47-962F-4708-B6C6-614BDF6461B7

Both URLs resulted in the same short code:

0Ny05N

This confirmed that trimming the generated Base64 value to six characters does not guarantee uniqueness.

Architecture v2

Description

The new architecture will include a PostgreSQL database to store the generated short URLs.
This version will also aim to resolve the collision issue identified in the previous architecture.

Design

The new design will include a PostgreSQL database to persist the generated short URLs.
Instead of generating the code from the original URL, the backend will generate a random 6-character Base62 code.
Before storing the URL, the backend will check whether the generated code already exists. If it does, it will generate another code. The database will also enforce uniqueness on the generated code.

Architecture Diagrams

Flowchart

Sequence

Architecture v2.5

Description

This sub-version of the second architecture will focus on implementing redirects for the generated short URLs.

Design

The new design will include a GET endpoint:

GET /{code}

The endpoint will use a 302 redirect to navigate the user to the original URL associated with the generated code.
The architecture details in this version focus only on the redirection flow.
There is currently no web-based interface. The full flow uses a direct API call to generate the short URL, after which the generated URL can be opened directly in the browser to trigger the redirect.

Architecture Diagrams

Flowchart

No change in the flowchart.

Sequence

Architecture v3

Description

The third version of the architecture will focus on caching to improve the redirection flow.
If someone generates a short URL and shares it, many users may access the same URL.
Adding Redis to the GET flow will reduce repeated database lookups for frequently accessed URLs.

Design

The new design will introduce Redis as a cache in front of the database.
When the backend receives a redirect request, it will first check Redis.
If the URL already exists in the cache, it will be used immediately.
If it doesn't exist in the cache, the backend retrieves it from PostgreSQL and stores it in Redis so subsequent requests can use the cached value.

Architecture Diagrams

Flowchart

Sequence

Architecture v4

Description

The fourth version of the architecture will focus on implementing a web application that lets users interact with the service easily. This version does not affect the backend implementation.

Design

The new design will only introduce a web-based application.

Architecture Diagrams

Flowchart

Sequence

Architecture v5

Description

The final version of the architecture focuses on improving the maintainability and lifecycle management of generated short URLs.

• Generated URLs should expire after a configurable period.

• If a user requests an expired URL through the GET endpoint, the system will remove it from the database and return a 404 Not Found.

• A scheduler will run at a configured interval to remove expired URLs that are no longer accessed.

Design

The new design introduces changes to both the POST and GET flows.

• When a URL is created, it will be stored in the database with an expiration timestamp.

• The generated short URL will also be added to Redis immediately to improve redirection performance.

• When a short URL is requested, check its expiration.

• If the URL has expired, remove it from the database and Redis, then return 404 Not Found.

• A scheduled cleanup process will periodically remove any remaining expired URLs.

Architecture Diagrams

Flowchart

Sequence - Resolve Short URL

Sequence - Create Short URL

Sequence - Scheduler

Conclusion

ShortURL started as a simple proof of concept for generating short URLs and gradually evolved.
The project was intentionally developed in stages, with each architecture version addressing a limitation or introducing a new requirement.

The final result is a small but complete system that demonstrates how architecture can evolve over time as requirements and problems become clearer.