LinkLens — self-hosted link intelligence and smart redirect engine

The problem

Typical URL shorteners resolve every click against a transactional relational database and call paid third-party APIs for geolocation. Both become the bottleneck — in latency and in cost — as click volume grows.

LinkLens was designed so that the redirect itself never waits on the database or on analytics, and so that geo/device enrichment costs nothing per request.

Architecture and approach

• Hot path: link rules are resolved from Redis by the NestJS redirect engine, without querying PostgreSQL. The design target for this path is a single-digit-millisecond redirect.
• Cold path: each click is published to a BullMQ queue; a worker pool enriches it and stream-inserts it into ClickHouse, a columnar store suited to large analytical aggregations.
• Geo and device data come from local MaxMind .mmdb datasets and ua-parser-js evaluated in memory, so there is no recurring external lookup cost.
• Custom domains get TLS automatically: Caddy issues certificates on demand after validating the domain through a backend webhook, without server restarts.

Key features

• Rule-based routing by country, OS, browser, language or weighted A/B split.
• Analytics dashboards on ClickHouse aggregations, with UTM attribution and a live WebSocket activity feed.
• Workspace isolation with OWNER, ADMIN, MANAGER and ANALYST roles (RBAC).
• REST API documented with OpenAPI 3.0, SHA-256-hashed API keys with rotation, and HMAC-SHA256-signed webhooks.
• A GDPR mode that truncates IP addresses before they are persisted.
• SVG/PNG/PDF QR-code generation with logo overlays and styling.

Engineering decisions

• Split read path and write path: the redirect response never depends on analytics writes succeeding.
• Columnar storage (ClickHouse MergeTree ordered by workspace, link and month, with a 365-day TTL) for click telemetry instead of the relational database.
• Self-hosted enrichment data instead of a paid geo API, trading periodic dataset updates for zero per-request cost.

Technology stack

Backend

• NestJS
• TypeScript
• Passport.js (JWT/OAuth)
• BullMQ

Data

• PostgreSQL 16 (Prisma)
• Redis 7
• ClickHouse 24

Frontend

• Next.js 14 (App Router)
• React 18
• Tailwind CSS
• TanStack Query
• Zustand
• Recharts

Infrastructure

• Docker Compose
• Caddy 2 (on-demand TLS)

Links