Lorentz Click
AWS Lambda • API Gateway • DynamoDB • S3 • CloudFront • Route 53 • SQS • Cognito • CloudWatch • SNS • SES • Terraform • GitHub Actions • Serverless • IaC • Event-driven architecture
Project Description
LorentzClick is a link shortening service. It is built entirely on the AWS platform, leveraging a serverless architecture.
Project Context
The main challenge LorentzClick solves is the poor usability of lengthy and unwieldy URLs, which are unsuitable for sharing across various platforms. On the technical side, the project addresses the need for an scalable and cost-efficient solution to manage high-volume redirects. It also tackles the crucial issues of resource governance and data relevance by implementing a strategy for automated link deduplication and expiry, ensuring the platform remains lean and relevant over time.
Main Goal
The primary objective of this project was to build a robust, fully serverless architecture for a common web service on the AWS platform. The goal was to showcase key modern cloud principles: high performance through an event-driven, non-blocking process; operational cost efficiency via serverless compute; and intrinsic scalability. The project specifically intended to demonstrate a highly responsive redirect mechanism where statistical updates are handled asynchronously, guaranteeing the fastest possible user experience.
Architecture & Technical Solution
The following diagram illustrates the key components and their interaction within the LorentzClick service.
Architecture Overview
The LorentzClick architecture is built on a fully serverless stack in the AWS Cloud. The frontend static website is hosted on an Amazon S3 bucket and served globally via Amazon CloudFront as a Content Delivery Network (CDN). All API requests for creating and resolving links are handled by Amazon API Gateway.
The backend logic is powered entirely by AWS Lambda functions. Amazon DynamoDB serves as the primary data store, mapping short links to their original URLs and storing metadata, including the Time-To-Live (TTL) attribute for automatic expiration. A crucial part of the design is the asynchronous processing for link redirects: when a user clicks a short link, the Resolve short URL Lambda function immediately executes the redirect and places a message in an Amazon SQS queue to asynchronously update the click count and TTL. This decoupling ensures minimal user-facing latency for redirects. To ensure reliability, the SQS queue for metadata updates is configured with a Dead Letter Queue (DLQ), which catches and stores messages that fail processing for subsequent inspection and handling.
Link Shortening Flow
The link shortening workflow starts when the client sends a POST request to Amazon API Gateway. The gateway forwards this request to the corresponding AWS Lambda function, which handles all core logic. Upon invocation, the function validates the submitted long URL and checks Amazon DynamoDB to see whether a short link already exists for it.
To prevent duplication, two deduplication strategies are applied:
- Global Deduplication - used for anonymous users, ensuring that only one short link exists across the entire system for a specific long URL.
- Personal Deduplication - used for authenticated users, allowing them to create their own short link even if a global one already exists, keeping their data isolated and easier to manage.
Redirect Flow
This mechanism ensures an ultra-low-latency redirect experience for end users. When a user clicks a short link, the request is received by Amazon API Gateway and handled by URL Lambda function.
- Immediate Redirect: The Lambda function validates the short URL, retrieves the original destination from DynamoDB, and immediately returns an HTTP 308 redirect response. This completes the user’s request with minimal latency.
- Asynchronous Update: At the same time, the Lambda function sends a message to an Amazon SQS queue containing metadata needed to update the click counter and TTL expiration time.
- Background Processing: A separate AWS Lambda function acts as the SQS consumer. It processes messages asynchronously, retrieving the corresponding record from DynamoDB, atomically incrementing the visit counter, and refreshing the Time-to-Live (TTL) attribute.
- Error Handling: The SQS queue is configured with a Dead-Letter Queue (DLQ). Messages that fail to process successfully (for instance, due to transient database errors or function timeouts) are automatically moved to the DLQ for manual inspection and reprocessing, ensuring that no click data is lost.
Data Management and Optimization
Data retention and resource optimization are ensured through two key mechanisms: deduplication and automatic removal of old records in DynamoDB using Time-To-Live (TTL).
DynamoDB TTL serves as the primary component for automated data expiry and cost management. The TTL attribute is refreshed on each link creation or visit, ensuring that links remain active as long as they are being used. Links created by anonymous users expire after 2 months of inactivity, while links created by authorized users remain active for 6 months since their last visit.
The combined use of global and personal deduplication further optimizes the system by eliminating redundant records, preserving data relevance, and reducing DynamoDB throughput and storage consumption. Additionally, authorized users gain access to aggregated visit statistics for their personalized links.
Deployment & Observability
The entire LorentzClick infrastructure is defined and managed using Infrastructure as Code (IaC) principles with Terraform. This approach ensures consistent, idempotent, and easily reproducible environments across all stages. Deployment is fully automated through GitHub Actions workflows, which orchestrate both infrastructure provisioning and updates via Terraform, as well as the build and deployment of AWS Lambda function code. This setup enables continuous, reliable delivery with minimal manual intervention.
To maintain system reliability and performance, comprehensive observability is implemented across all AWS components. Core services such as API Gateway, Lambda, and SQS emit detailed logs and metrics to Amazon CloudWatch. A dedicated CloudWatch Dashboard aggregates key performance indicators (KPIs) - including Lambda invocation counts, SQS queue depth, and DynamoDB latency - providing a centralized operational view.
Additionally, CloudWatch Alarms are configured to trigger notifications via Amazon SNS and Amazon SES when critical metrics exceed defined thresholds, ensuring administrators are promptly alerted to potential issues and can respond proactively.