My URL Shortener: Technical Choices and Architecture

My URL Shortener: Technical Choices and Architecture

29 août 2025

In a world where speed and reliability are essential, I developed jumpto.io, a modern URL shortener designed to deliver ultra-optimized performance at a global scale.

Beyond simple link shortening, JumpTo offers features designed for modern marketing: automatic deep linking that opens mobile applications directly (YouTube, Instagram, Spotify, etc.) instead of the browser, generation of customizable QR codes for your print campaigns and events, a collections system to organize your links by project or campaign, and custom domains to strengthen your brand. Each link can also be tracked with detailed analytics to understand your audience.

This article details the technical architecture of this multi-tenant SaaS project, from stack selection to distributed deployment strategy.

Project Context and Objectives

The goal of JumpTo is to provide a URL shortening service capable of handling millions of redirections with minimal latency, regardless of the user's geographic location. To achieve this, I opted for a hybrid architecture combining:

  • A complete web application for management (creation, analytics, custom domains)
  • An ultra-fast microservice deployed on the edge for redirections

Global Architecture

JumpTo's architecture is based on three main pillars:

1. The Main Application (Nuxt 4)

The core of the application is developed with Nuxt 4, the latest generation Vue.js framework, combined with TypeScript to ensure type safety. Here are the main technical choices:

Technical Stack:

  • Frontend: Nuxt 4 (Vue.js) + TypeScript + Tailwind CSS 4
  • Backend: Nuxt API routes with PostgreSQL
  • ORM: Drizzle ORM for type-safe queries
  • Authentication: Better Auth
  • UI Components: shadcn-nuxt
  • Payments: Stripe integration for billing

Multi-tenant Architecture:

multi-tenant.png

The application uses an organization system that allows multiple companies to use the service in isolation. Each organization has its own space with its own links, custom domains, and settings. This architecture guarantees strict data separation between clients while sharing the same infrastructure.

The routing system is designed to reflect this organizational structure, with dynamic routes that automatically adapt to the active organization's context. This allows a user who is a member of multiple organizations to easily switch between them.

Data Model:

The database is structured around several key concepts that interact with each other:

  • An organizations system that serves as the main container for all resources
  • User management with different permission levels (owner, administrator, member)
  • Shortened links that constitute the service's core functionality
  • Collections to organize and categorize links
  • Support for custom domains via Cloudflare integration
  • A detailed statistics system that records each click (device, browser, location, referrer)

This structure enables horizontal scalability while maintaining the integrity and isolation of each client's data.

Statistics Collection Flow:

An important aspect of the architecture is the separation between redirection (ultra-fast) and statistics collection. The microservice on Cloudflare Workers doesn't store anything itself - it simply redirects the user instantly, then asynchronously sends analytics data to the Nuxt application. The latter processes and stores it in PostgreSQL to enable detailed analyses later. This approach ensures that data collection never impacts redirection speed.

2. The Redirection Microservice (Cloudflare Workers)

The true innovation of JumpTo lies in its redirection microservice deployed on Cloudflare Workers. This approach offers several crucial advantages to guarantee exceptional performance.

Global Distribution:

Cloudflare Workers runs on more than 300 datacenters distributed worldwide. Each redirection request is automatically processed at the point of presence closest to the user, guaranteeing latency under 50ms in most cases. This geographic distribution eliminates the bottleneck of a single centralized server.

Minimalist Architecture:

The microservice is designed with a single objective in mind: redirect users as quickly as possible. It performs no heavy operations, connects to no traditional database, and maintains a minimal memory footprint. This minimalist approach is the key to its performance.

Distributed Cache System:

Instead of querying a traditional PostgreSQL database on each redirection, the microservice uses Cloudflare KV, a distributed key-value storage system designed for ultra-fast reads. The data structure is optimized to support multi-tenancy:

Each link is identified by a combination of domain and slug (for example: jumpto.io:mylink or go.mydomain.com:custom). This structure allows the same slug to exist on different domains with different destinations, while maintaining constant O(1) lookup times.

Smart Deep Links:

A particularly interesting feature is the automatic detection and conversion of links to mobile applications. The system recognizes URLs from popular platforms (YouTube, Instagram, Spotify, etc.) and automatically converts them into native app links according to the detected operating system.

For Android, the system uses the intent:// scheme which allows specifying the target application while providing a fallback URL if the application is not installed:

intent://instagram.com/user/USERNAME#Intent;
  scheme=https;
  package=com.instagram.android;
  S.browser_fallback_url=https://instagram.com/user/USERNAME;
end

For iOS, the system directly uses the proprietary URL schemes of applications:

youtube://watch?v=VIDEO_ID
instagram://user?username=USERNAME
spotify:track:TRACK_ID

This feature significantly improves the user experience by directly opening the native application rather than the mobile browser.

Infrastructure and Deployment

Main Application: VPS with Docker Swarm

The Nuxt application is deployed on a VPS using Docker Swarm for orchestration. The deployment process is fully automated via GitHub Actions.

Microservice: Cloudflare Workers

The microservice deployment is even simpler thanks to the Cloudflare platform. A simple wrangler deploy is enough to update the code across Cloudflare's entire edge network.

Advantages of this Architecture:

  • Performance: Latency < 50ms thanks to global POPs
  • Scalability: Cloudflare automatically handles scaling
  • Availability: 99.99% uptime guaranteed by Cloudflare
  • Costs: Free plan up to 100K requests/day

Analytics and Statistics

Unlike redirections that must be ultra-fast, analytics collection is performed asynchronously to avoid impacting performance:

Using waitUntil:

ctx.waitUntil(
  fetch(`${JUMPO_APP_URL}/api/stats/click`, {
    method: 'POST',
    body: JSON.stringify(analyticsData)
  })
)

This Cloudflare Workers API allows executing background tasks even after the response has been sent to the client. Thus, the redirection is instantaneous and statistics are collected without impacting the user.

Lessons Learned

Developing JumpTo allowed me to explore in depth distributed architectures and performance optimization strategies. Several key lessons:

Choosing the Right Tool:

  • PostgreSQL for complex data and relationships
  • KV for ultra-fast reads and global distribution
  • Clear separation between management and execution

Edge Computing:

  • Drastic latency reduction thanks to global POPs
  • Automatic scalability without infrastructure management
  • Controlled costs with a pay-per-use model

Developer Experience:

  • TypeScript everywhere for type safety
  • Drizzle ORM for type-safe queries
  • Docker for reproducible deployment
  • CI/CD for frictionless releases

Conclusion

JumpTo demonstrates that it is possible to build a performant and scalable SaaS service by judiciously combining modern technologies. The hybrid architecture - centralized application for management and distributed microservice for execution - offers the best of both worlds: functional richness and maximum performance.

This project also illustrates the importance of choosing the right technology for each problem. PostgreSQL excels for complex relational data, while Cloudflare KV and Workers are unbeatable for simple operations requiring minimal latency at a global scale.