Features

UTM Gen feature specification

1. Product Overview

UTMGen is a UTM link generation and governance platform for individuals, marketing teams, and enterprises. It solves two problems existing tools handle poorly: fast bulk generation of correctly-tagged links, and organization-level governance so UTM taxonomy stays clean and consistent across a whole company.

Unlike link shorteners that treat UTM tagging as an afterthought, UTMGen treats governance and taxonomy as the core product. Short-link redirection is a first-party feature, not a bolt-on.

2. Glossary

3. MVP Feature Set (Launch)

3.1 Link & UTM Generation

• Single link generation with standard 5 UTM parameters + org-defined custom parameters.
• Multi-link generation, two modes:
  • One URL, many parameter combinations (e.g. one destination, varying medium/source per row).
  • Many URLs, one shared parameter set (e.g. same campaign tagging applied across multiple destination URLs).
• Bulk CSV import: paste/upload rows of URL + parameter combinations, validate, generate in batch.
• Bulk export: CSV/XLSX export of any link set (generated links, or full account/org history).
• Duplicate detection: warn (not necessarily block) when an identical URL + full parameter combination already exists.
• Delimiter & format enforcement: consistent separator character (e.g. - not _), enforced casing (see Governance), max length checks, stripping of disallowed characters.
• Test link mode: a link-level flag (not a URL parameter) that excludes the link's click events from all analytics/reporting. Internal QA links never pollute campaign data.

3.2 Templates

• Users can save a named template: a full or partial parameter set, reusable across future link generations.
• Org-level template management: designated admin(s) (permissioned role, not necessarily the sole org owner) can create, edit, and publish templates for the whole org to use.
• Templates can be locked (values fixed, non-editable by end user) or suggestive (pre-filled but editable, subject to taxonomy rules).

3.3 Short Links & Domains

• First-party redirect service on a shared UTMGen domain (free/default tier).
• Custom domain support (paid tiers): org can point their own subdomain (e.g. go.acme.com) via CNAME; UTMGen handles domain verification and automatic TLS provisioning.
• All redirects — shared domain or custom domain — route through UTMGen's own infrastructure, so all click events are first-party from day one (see Section 5.1 for the architectural reasoning).
• 404 / broken-link detection: flag short links whose destination returns an error, or which receive no valid redirect target.

3.4 Governance & Taxonomy

• Org admins define, per parameter (standard or custom), one of:
  • Free text — no restriction.
  • Governed enum — only admin-approved values selectable.
• Forced normalization: e.g. force-lowercase on output regardless of user input casing; this is an org-level toggle, applied at generation time so it can't be bypassed by client input.
• Custom parameters: orgs can define additional parameters beyond the standard 5, which behave identically to standard parameters for governance, templating, and taxonomy purposes.
• Parameter request workflow: for governed parameters, a non-admin user can submit a request to add a new value (e.g. "please add medium=podcast"); an admin approves or rejects. This is scoped to requesting a taxonomy value, not full link approval (see Day-2 for full link-approval workflows).
• Campaign name builder (org-optional): instead of (or alongside) free-text campaign naming, an org can define a structured builder — e.g. concatenating controlled sub-fields (team + quarter + initiative) into a consistent campaign name — rather than a strict enum. Decide per-org whether campaign name is free text, structured builder, or governed enum.
• Audit log: every create/edit/delete of a link, template, taxonomy value, or permission change is logged with actor, timestamp, and before/after state. Exportable, and required for enterprise.

3.5 Team & Org Management

• Individual (single-user) accounts, fully supported, no org required.
• Org accounts with multiple users, role-based permissions at minimum: Owner, Admin (taxonomy/template management), Member (generate links within governance rules).
• Auth and org-level SSO via Clerk (see Tech Stack doc). Clerk's own org model should map closely to UTMGen's org/role model — avoid building a parallel permissions system where Clerk's primitives already cover it.

3.6 Analytics (MVP scope)

• Per-link click count, referrer, geography, device, and timestamp (first-party, from your own redirect service).
• Org-level rich dashboard: all links, filterable by taxonomy dimensions, template, creator, date range.
• Comparison views: campaign-vs-campaign, channel-vs-channel, period-over-period.
• Test-tagged links excluded from all standard reporting views by default (visible only under an explicit "include test links" toggle for internal QA).
• 404/broken-link monitoring surfaced in dashboard.

3.7 Billing & Tiering (initial proposal — open to revision)

Sales-assisted for Enterprise; self-serve for Free/Premium.

4. Day-2 Feature Set (Post-launch roadmap)

• Conversion attribution: tie clicks to downstream conversions/revenue (e.g. Stripe webhook integration), not just click counting.
• Full link-approval workflows: beyond parameter-value requests, a submit-for-approval flow for entire links before they go live, for orgs that want stricter control.
• GA4 / Google Search Console import and export: import existing param taxonomy from GA4; export UTMGen's canonical taxonomy back to GA4 so reporting stays aligned.
• Slack / Teams notifications: on link creation, taxonomy requests, approvals.
• Browser extension / quick-capture tool: fastest path from "I need a UTM link right now" to a generated, governed link, without opening the full app.
• Dub.co connector: for orgs with an existing Dub.co account, ingest their click data via Dub's API/webhooks and merge into UTMGen's governance/reporting layer. This is additive, not a replacement for UTMGen's own first-party redirect service.

5. Architecture Decisions & Ramifications

5.1 Short-link hosting models

Three distinct models were considered, with real analytics implications:

1. Shared UTMGen domain (self-hosted redirect) — clicks hit UTMGen's own edge/redirect service first. Full first-party ownership of every click event (IP, geo, device, referrer, timestamp) plus attached taxonomy metadata. This is the default and the foundation for all other analytics features (test-link exclusion, 404 monitoring, future conversion attribution).
2. BYO custom domain (CNAME to UTMGen) — architecturally identical to #1; only the domain/TLS layer differs. Requires domain verification and automated cert provisioning (e.g. via a platform like Vercel's Domains API or Cloudflare for SaaS) plus multi-tenant routing at the edge. No analytics ramification beyond an extra "which domain" dimension.
3. Dub.co as redirect backend — considered and not recommended as the primary redirect path. If Dub hosts the actual redirect, click events originate on their infrastructure, not ours; we'd depend on their webhook/API for data, inherit their latency and uptime as a dependency, and pay for infrastructure the customer is already paying us to provide. Self-hosting Dub's open-source engine as our own infra was also considered — feasible in principle since 99% of their codebase is AGPLv3 — but AGPLv3 has real obligations around modifications run as a network service, which needs legal review before treating it as core infrastructure. Decision: build our own lightweight redirect service (a KV lookup + redirect + async click-event write is not a large engineering lift), and offer a Dub.co connector as a Day-2 integration only, for customers migrating data in.

5.2 Test-link mode

Implemented as a link-level boolean flag, not a URL parameter. The marker never appears in the outbound URL, so a test link can't accidentally leak a visible tag if shared externally. Filtering happens at the analytics-ingestion layer: click events from test-flagged links are tagged as such and excluded from all default reporting views.

5.3 Governance data model (parameters, taxonomy, requests)

• Each org maintains a taxonomy table per parameter: parameter_name, mode (free_text | governed_enum), allowed_values[], normalization_rules (e.g. force_lowercase, delimiter).
• Custom parameters are stored using the same schema as standard parameters, distinguished only by an is_custom flag — this avoids special-casing custom parameters anywhere in generation, templating, or governance logic.
• Parameter-value requests are a lightweight workflow table: requested_by, parameter_name, requested_value, status (pending/approved/rejected), reviewed_by. Kept intentionally separate from any future full link-approval workflow (Day 2), since they solve different problems (enum growth vs. per-link sign-off).

6. Open Questions / Decisions Needed

• Should duplicate detection block generation or only warn? (Recommendation: warn, with an override — hard blocking will frustrate legitimate re-tagging.)
• Campaign name: free text, structured builder, or governed enum — should this be an org-level choice, or a single default UTMGen enforces?
• Premium seat pricing model: flat per-seat add-on, or tiered seat packs?
• Does Free tier get short links on the shared domain at all, or only "raw" UTM-tagged long URLs (no redirect)? This affects whether Free-tier users get any click analytics at all.
• Exact SLA/data-retention differences between tiers for analytics history (e.g. 30 days on Free, unlimited on Premium/Enterprise) — not yet specified.

Next: tech stack proposal, covering framework, database, analytics pipeline, auth (Clerk), and deployment — to follow as a companion document.