Tinybird Analytics Infrastructure
Purpose and Scope
Dub uses Tinybird as the analytics backend for the product area that reports clicks, conversions, top links, referrers, devices, locations, and time-based trends. The repository-level Tinybird README identifies the analytics assets that belong to this subsystem, while the web application exposes a TypeScript boundary for recording and retrieving analytics events. Together, these files show a split between warehouse-style Tinybird definitions and application-level functions that publish or read event data. This page helps contributors understand where analytics infrastructure is declared, how the app touches it, and which named endpoints map to dashboard and API reporting concepts.
Sources: packages/tinybird/README.md, apps/web/lib/tinybird/index.ts
The first-party product docs describe Dub Analytics as a high-volume reporting surface for clicks and conversion events, with breakdowns by location, device, links, UTM parameters, and referrer data. The source evidence aligns with that public framing: the Tinybird package lists endpoint pipes for browser, city, clicks, country, device, operating system, referer, timeseries, top links, and top URLs. Those names are important because they mirror the analytics families a reader sees in the dashboard and API. The repository does not present Tinybird as a generic optional add-on here; it is the named analytics technology behind those reporting slices.
Relevant Source Files
- packages/tinybird/README.md — Lists the Tinybird project layout, including datasources, materialized/latest datasources, endpoint pipes, and ingestion or transform pipes used by Dub analytics.
- apps/web/lib/tinybird/index.ts — Re-exports the application-facing Tinybird library modules for client access, event retrieval, and recording click, lead, link, and sale data.
System-to-Code Mapping
The Tinybird README is the infrastructure map. It groups assets into datasources, endpoints, and pipes, which is a useful mental model for reading the analytics system. Datasources are the persisted tables or views that hold click events and link metadata. Pipes transform or materialize those records, including a click event pipe and a link metadata pipe. Endpoints are the query surfaces that turn stored event data into product reports. Because the README names both raw and derived assets, contributors can distinguish ingestion storage from user-facing query results before inspecting individual Tinybird files in a hydrated workspace.
Sources: packages/tinybird/README.md
The web library index is the application map. It exports modules named for analytics actions rather than Tinybird internals: client access, click event retrieval, lead event retrieval, click recording, lead recording, link recording, and sale recording. That boundary suggests that most application code should depend on task-oriented helpers instead of constructing Tinybird requests directly. In practice, a dashboard, API route, redirect handler, or conversion-tracking path can import a recording or retrieval helper from the web library while the Tinybird package remains responsible for the underlying datasource and endpoint definitions.
Sources: apps/web/lib/tinybird/index.ts
Datasources, Pipes, and Endpoints
The visible datasource names show two event families. Click analytics are represented by a click events datasource and a click events materialized view datasource. Link metadata is represented by a metadata datasource and a latest metadata datasource. This separation matters because analytics queries often need both behavioral facts and link context. A click tells Dub what happened, while link metadata tells it which workspace, short link, destination, or reporting grouping the event belongs to. Keeping latest link metadata separately named also hints at the need for current link attributes when aggregating historical activity.
The endpoint list is a compact reference for the analytics slices exposed by Tinybird. Device reporting is split into browser, device, and operating system endpoints. Location reporting is split into country and city endpoints. Traffic-source reporting appears through the referer endpoint, while aggregate traffic and trend reporting appear through clicks and timeseries. Link-centric leaderboards are represented by top links and top URLs. These endpoint names are not merely implementation details; they are the bridge between the analytics infrastructure and the user questions Dub answers in product surfaces such as performance dashboards, exports, and API-driven reports.
Event Recording and Retrieval Flow
A typical click flow starts in the web application, where a redirect or tracking path can call an application helper that records the click. The public export surface includes modules for recording clicks and retrieving click events, which keeps ingestion and lookup concerns inside the Tinybird library boundary. After events are recorded, Tinybird datasources and pipes provide the data model needed for endpoint queries. Downstream consumers then ask for dimensions such as country, device, referer, or top links rather than manually scanning raw event rows. This keeps analytics reads aligned with named endpoint pipes.
Conversion tracking follows the same source-level pattern but uses separate event concepts. The web library exports recording helpers for leads and sales, along with a retrieval helper for lead events. Those names match Dub's broader product model, where analytics is not limited to short-link clicks and also includes conversion events. The page evidence does not expose the full schemas for lead and sale records, but the exported module names establish that conversion analytics belongs to the same Tinybird-facing library area as click analytics. Contributors should treat these helpers as the stable app-side entry points.
Sources: apps/web/lib/tinybird/index.ts
Compact Reference
Tinybird asset groups visible in the repository:
| Group | Visible names | Reader-facing role |
|---|---|---|
| Datasources | dub_click_events.datasource, dub_click_events_mv.datasource, dub_links_metadata.datasource, dub_links_metadata_latest.datasource | Store event facts and link metadata used by analytics queries |
| Endpoint pipes | browser.pipe, city.pipe, clicks.pipe, country.pipe, device.pipe, os.pipe, referer.pipe, timeseries.pipe, top_links.pipe, top_urls.pipe | Serve dimension-specific and aggregate analytics results |
| Internal pipes | dub_click_events_pipe.pipe, dub_links_metadata_pipe.pipe | Transform or ingest click events and link metadata into queryable shapes |
Application exports visible in the web Tinybird library:
| Exported module | Purpose indicated by name |
|---|---|
| client | Shared Tinybird client boundary |
| get-click-event | Retrieve a click event |
| get-lead-event | Retrieve a lead event |
| record-click | Record click analytics data |
| record-lead | Record lead conversion data |
| record-link | Record link metadata for analytics context |
| record-sale | Record sale conversion data |
Implementation Guidance and Next Steps
When extending analytics, start by deciding whether the change is an ingestion change, a metadata change, or a query-surface change. New event fields usually affect recording helpers and Tinybird datasource or pipe definitions. New dashboard breakdowns usually correspond to endpoint-style pipes, following the existing family names for device, location, referrer, trend, and top-link reporting. Metadata changes should consider how link context is recorded and how latest metadata is made available to historical event queries. This keeps the application API and Tinybird assets evolving together instead of drifting into separate models.
For related reading, use the analytics concept pages to understand how dimensions such as devices, locations, referrers, and UTM data appear to users, then use the Analytics API page to see how those concepts are requested programmatically. Contributors working on event ingestion should also read the Track API and conversion tracking pages because the web library explicitly includes lead and sale recording alongside click recording. If the task is operational rather than product-facing, inspect the Tinybird package assets first, then follow imports through the web Tinybird library boundary before changing dashboard or API consumers.