Alshorty — The Bible 🚀
Your single source of truth: build, security, no-bug discipline, growth from 1 week to 5 years, marketing and business. Rebuilt from the live site (alshorty.com, crawled fresh) and the actual codebase — worker/ + ui/, 32 Worker files, 53 frontend pages — not just the historical planning docs.
🧭 How to use this tracker
This file is self-contained — no login, no cloud dependency. Everything lives in your browser, with backup/restore to keep it safe across devices.
1
Navigate with the sidebar — grouped by System Map, Product Pillars, Platform Operations, Security/QA, Growth Timeline, and Marketing/Business.
2
Click any task to mark it done (turns green ✓). Click again to unmark.
3
Growth Timeline has horizon tabs — 1 Week, 1 Month, 3/6/12 Months, 2–5 Years — each with its own focus and checklist.
4
Press "💾 Save Progress" (or Ctrl+S) — saves to browser localStorage. Progress persists between sessions.
5
Use "⬇ Backup / Restore" to download a .json file regularly. Re-import on any device to sync progress — treat this like a save file.
Tasks Done
0
of 0 total tracked tasks
Overall Progress
0%
Across every pillar
Current Phase
Phase 0
V2 → V3 Migration
Product Pillars
3 live
URL Shortener · Link-in-Bio · SmartPages, one API key
Loading…0%
🎯 Today's Mission
Loading…
💸 AI Spend (month)$0
❤️ Platform Health—
🚦 Release Ready0 / 3
🔐 Critical Security Closed0 / 0
🕓 Recent Activity
- No activity yet — tick a task to get started.
The honest position, restated: SmartPages is an entire third product with zero mentions in the last known technical doc (dated May 11, 2026) — it was built afterward and is fully live today. Geo-targeting, retargeting pixels, and A/B split testing were all still listed as "future" in the old tracker; all three are confirmed shipped and PRO-gated in the actual redirect code. Meanwhile real Pro pricing (₹399/mo, $8/mo) is fully built but currently shown as $0 — a deliberate choice, not a gap. Read the panels here as ground truth, not the old docs.
✅ Shipped Since the Last Known Doc — Verified From Code
- SmartPages — an entire third product (routes/pages.js, 828 lines). 15 block types, drag-and-drop, free tier live on homepage. Zero mentions in the May 11 technical doc.
- Link-in-Bio Prominence Upgrade — the May doc describes this as "Active." It's now fully shipped: free tier (1 page, 5 links) live on the homepage as a first-class product, not buried behind Pro.
- A/B split testing, geo-targeting redirects, and retargeting pixels (FB/GA/GTM) — all three were listed as "Tier 1 future" in the old tracker. All three are confirmed live and PRO-gated in links.js and redirect.js.
- Currency/pricing bug fully fixed — usePricing() v3.1.0, single backend source of truth, geo-aware INR/USD split, session-cached, zero hardcoded prices anywhere in the frontend.
- 6 alternatives pages (Bitly/Rebrandly/TinyURL/Linktree/Short.io/Carrd), /developers (68KB) with a full interactive API playground, /documentation (95KB).
- RFC 9116 security.txt, honeypot traps, Google Safe Browsing integration, 30+ phishing regex patterns, zero-tolerance CSAM detection.
📐 The Core Question
Before building any new feature: is this genuinely new capability, or does it already exist in links.js/redirect.js and just needs a frontend UI to expose it? geo_rules, device_rules, ab_variants, and pixels all already have backend support — several "future" ideas may just be missing an edit-modal UI, not backend work.
Alshorty
│
├── Core (auth, KV/D1/R2, admin-config — DONE)
├── URL Shortener (links.js — A/B, geo, pixels all live — MOSTLY DONE)
├── Link-in-Bio (free tier live, first-class product — DONE)
├── SmartPages (undocumented 3rd product, SSR pending — MOSTLY DONE)
├── Analytics (D1 clicks, IP-hash privacy — DONE)
├── Free Tools (QR/UTM/LinkChecker/OGChecker — DONE)
├── Admin Console (bootstrap-protected, audit_log — DONE)
├── Marketing Site (6 alternatives, /developers, blog — MOSTLY DONE)
│
└── Monetization (real pricing built, shown as $0 — DECISION PENDING)
└── custom domains, teams, webhooks — genuinely NOT STARTED
North Star & Strategy
The strategic frame every other decision in this tracker hangs off of.
🧭 The Strategic Shift
Alshorty is a 3-in-1 bundle, not a URL shortener with side features.
URL Shortener + Link-in-Bio + SmartPages, one login, one API key, one price (currently $0). The actual competitive wedge isn't out-featuring Bitly or out-designing Linktree individually — it's that a user would otherwise pay for Bitly AND Linktree AND a landing-page tool separately, and Alshorty bundles all three free.
⚠️ The Open Question This Tracker Answers
The last technical doc is dated May 11, 2026 and has zero mentions of SmartPages — an entire product built afterward. The old tracker still listed geo-targeting, retargeting pixels, and A/B testing as "Tier 1 future, build next" when all three are confirmed live and PRO-gated in the real redirect code. This tracker is grounded in the code and the live site, not the historical docs — treat any future planning doc as secondary to what links.js and redirect.js actually say.
📊 Wrong Metric vs Correct Metric
Track outcomes, not activity. A signed-in link or a real click-through on a bio page is the actual unit of value — not a page view or an anonymous link that expires in 60 days.
| Instead of tracking | Track this | Why it matters |
|---|---|---|
| Links created | Links created by signed-in users | Anonymous links expire in 60 days and never become a relationship |
| Bio/SmartPage views | Bio/SmartPage → click-through on an embedded link | A bio page that gets views but no clicks isn't doing its job |
| Total signups | Signups who create a 2nd link/page in the same week | One-and-done signups don't indicate product-market fit |
| — | Free users who hit their monthly cap | The real signal for whether Pro pricing has pull once switched on |
| — | Abuse reports / links removed per week | A rising trend is a real cost and risk signal, not just a checklist line |
🏷️ Revenue Model — Real, Built, Currently Disabled
Full pricing infrastructure exists in constants.js and works end-to-end via Razorpay. Pro is shown as $0 on the live site today — a deliberate growth-phase choice, tracked as an open decision on the Business & Revenue panel.
| Tier | Access | Price |
|---|---|---|
| Anonymous | 2 links max, 60-day expiry, no signup | Free |
| Free (signed in) | 50 links/mo, 1 bio page (5 links), 1 SmartPage (8 blocks) | ₹0 / $0 |
| Pro — currently $0 | 10,000 links/mo, 5 bio pages, 10 SmartPages, A/B testing, geo-targeting, pixels | Built: ₹399/mo · $8/mo · ₹3,999/yr — shown as $0 |
Guiding Principles
Every architectural and pricing decision should comply. Re-read before any sprint that touches more than one product.
Standing rule for every decision: if a system could be reused by more than one product (Shortener, Bio, SmartPages), it belongs in Core. If it's specific to one product's logic, it lives inside that product's own route file and data shape.
1
One login, one API key, one price for all three products
A user experiences Alshorty as one bundle, never as three separate tools requiring separate accounts or separate keys.
2
KV for the hot path, D1 for relational data — a deliberate split, not a compromise
Links live in KV specifically for sub-50ms redirect latency. Don't "fix" this by migrating to D1 — it would make the core product slower to solve a problem that doesn't exist yet.
3
No hardcoded prices anywhere in the frontend
usePricing()/useUsdPricing() read a single backend source of truth. Any new priced feature must follow this pattern — update constants.js and every surface updates automatically.
4
Abuse prevention runs on every link, every time, no exceptions
Phishing regex, Google Safe Browsing, honeypot traps, IP bans — this layered defense is what makes a free, no-signup-required shortener safe to operate. Never let a new creation path (e.g. a future bulk-import) skip it.
5
IP is stored as a hash, never raw — this is marketing copy, not just an engineering choice
"Privacy-first, GDPR-safe by design" is a genuine differentiator vs. GA4-based competitors. Keep it true on every new analytics surface, and say it out loud in marketing.
6
File Version headers and inline change notes on every edit — this discipline pays for itself
It's exactly what made rebuilding this tracker from the codebase alone possible. Keep bumping the version and writing what changed, every time.
7
Runtime config (app_config) must actually be enforced, not just saved
A known, named gap: the admin panel can save a config value the worker doesn't read yet. Don't let this drift — an admin who changes a limit and sees nothing happen loses trust in the whole panel.
8
Check the code before writing "future" — several "future" ideas are already half-built
geo_rules, device_rules, ab_variants, and pixels all exist on the link object schema already. A "new" feature idea might just be a missing UI, not new backend work — check before scoping it as a bigger job than it is.
9
Pro pricing at $0 is a decision, not a default — document the trigger for changing it
Don't let "we'll turn it on eventually" become "we never decided." A number (user count, cost pressure, funding need) beats a vibe.
10
Full Bitly/Linktree feature parity is explicitly not the goal
Compete on the 3-in-1 bundle, the generous free tier, and India-first pricing — not on matching every enterprise line item a much larger competitor has.
All Systems
Every internal system across Alshorty. Status, maturity, and dependencies — auto-tracked from your checklists, the rest editable inline.
Identity, Storage & Core
One login system, 5-namespace KV architecture, D1 for relational data, R2 for images, admin-editable config — the foundation every product depends on.
Confirmed live: magic-link + Google/Microsoft OAuth, 7-day sessions, D1 users table, app_config for runtime settings. Known gap: worker-side enforcement of app_config changes.
🔐 Identity & Authentication
Magic-link auth — 15-min token expiry, 5/15min rate limit per email
Google OAuth + Microsoft OAuth, both confirmed working in production
7-day sessions in AUTH_SESSIONS KV, httpOnly cookies
API key auth — SHA-256 hash + display prefix, never stores raw key
🗄️ Storage Architecture
5-namespace KV split — SHORTY_LINKS, SHORTY_RATE, SHORTY_LIMITS, AUTH_TOKENS, AUTH_SESSIONS
D1 schema — users, clicks, api_keys, audit_log, app_config, thin links table (migration 0004)
R2 bucket for bio images — content-type + size validated, no egress fees
⚙️ Admin-Editable Config
app_config table — pricing.*, limits.* editable at runtime via /__admin/config
Default config values seeded correctly (pricing, limits) on fresh install
Worker actually reads and enforces app_config changes at runtime, not just saves them
Known gap, called out directly: the admin config panel saves to app_config in D1, but runtime enforcement in the worker was flagged as an outstanding issue. Don't treat any app_config value as authoritative in new code until this is confirmed closed.
Critical Build Order
The spine of the platform. Build top to bottom — each layer unlocks the next. Support modules run in parallel alongside it.
🪜 The Spine
🔧 Support Modules (parallel, non-blocking)
Impact & Priority
Score every system on Business Value, Engineering Effort, Reuse, Risk, and Strategic Fit. Click a star to re-rate — it's saved instantly.
🔗 URL Shortener ✓ Live
The original product. links.js — 1,253 lines, v1.0.3. Links live in Cloudflare KV, not D1, for sub-50ms redirect latency.
Uses These Systems
🔗 Core Shortening
Create/list/edit/delete links, custom aliases (5/mo free, 100/mo Pro)
4 domain prefixes — /link (free default), /s /go /run (Pro-only)
Password protection, expiry by date or max-click count
QR code generation on every link, free on all plans
UTM parameter builder integrated into link creation
Bulk shortener UI (Bulk.tsx) — one at a time confirmed, CSV import still pending
🎯 V3 Advanced Targeting — Confirmed Live, PRO-Gated
A/B split testing — ab_variants[] with weighted random selection, per-variant click tracking in redirect.js
Geo-targeting — geo_rules[] routes by country, up to 10 rules per link
Device targeting — device_rules{} routes mobile/desktop/tablet separately
Retargeting pixels — fb_pixel_id, ga_id, gtm_id fired on redirect
🛡️ Security on Link Creation
30+ phishing regex patterns + Google Safe Browsing API check on every link
Blocked shortener domains, TLDs, malware/paste-dump domains, honeypot traps
🚧 Remaining for This Pillar
Bulk CSV import/export — currently 1-at-a-time only in the Bulk UI
Link expiry notification emails — 3 days before expiry, cron job not yet built
🧬 Link-in-Bio ✓ Live — Free Tier First-Class
alshorty.com/bio/you. Lives inside links.js, not a separate route file. The "Prominence Upgrade" the May 11 doc described as active is now fully shipped.
Uses These Systems
🧬 Core Bio Builder ✓ Live
Free tier live — 1 bio page, 5 links, no Pro guard, homepage hero section
Profile + avatar, 8 themes, gradient/image/accent-color backgrounds
Block types — link, youtube, spotify, soundcloud, text, contact form, section headers
Click & view analytics — countries, devices, per-link stats
QR code included, print-ready instant download
Built-in contact form / email capture
Pro tier — up to 5 bio pages, 20 links/page, custom slug, image upload, verified badge
🚧 Remaining for This Pillar
Bio OG meta tags (og:title, og:image, og:description) on bio-page.js template
Auto-detect social platform icons in bio links (expand detectIcon())
"Store" mode — sell products/services directly via Razorpay Payment Link, 0% commission
🧱 SmartPages Mostly Live — SEO Gap
alshorty.com/p/your-page. routes/pages.js — 828 lines, v1.0.0. The undocumented third product: zero mentions in the May 11 technical doc, fully built afterward.
Uses These Systems
🧱 Page Builder ✓ Live
Drag-and-drop block builder — free tier 1 page / 8 blocks, Pro 10 pages / unlimited blocks
15 block types — hero, headline, text, image, video, buttons, countdown, social_proof, features, testimonials, faq, form, embed, logo, divider, spacer
Slug availability check, publish instantly at /p/slug
Page analytics + CTA click tracking per block ID
Password protection on free tier
Pro — custom CSS, tracking pixels (FB/GA4/GTM/TikTok), remove branding, form blocks
Image upload to R2 for page assets, content-type validated
🚧 Remaining for This Pillar
Worker SSR at /p/* for SEO — currently client-rendered, invisible to crawlers that don't execute JS
Templates gallery — 10 pre-built templates to reduce blank-page friction
Form block → Resend lead capture wiring, confirmed end-to-end
The single highest-leverage open item across all three products: SmartPages SSR. A landing-page builder that search engines can't see defeats its own purpose — this was already flagged as pending in the last known roadmap snapshot and should be the first thing closed.
📊 Analytics ✓ Live
D1 clicks table shared across all three products. routes/analytics.js — 296 lines, v1.0.2. IP-hash only, GDPR-safe by design.
📈 Coverage
Country, city, device, browser, OS, referrer, UTM breakdown per click
IP stored as SHA-256 hash only — never raw, GDPR-safe by design
Shared page_views pattern reused across bio pages and SmartPages
7-day analytics on Free, full history + CSV export on Pro
Public stats endpoint (/api/public/stats) — links_today, links_total, 300s KV cache
🚧 Remaining
Click heatmap by hour/day, Looker Studio connector — both still on the future list
🧪 Free Tools ✓ Live
No login required, at /tools/*. SEO landing pages doubling as top-of-funnel acquisition.
🛠️ Coverage
QR Code Generator — free QR for any URL, PNG/SVG download
Link Checker — URL safety / redirect health check
OG Checker — Open Graph tag preview for any URL
UTM Builder — campaign tracking URL generator
🚧 Remaining
Each tool's /tools/ and /features/ variant confirmed as genuinely distinct copy, not near-duplicate content
🔌 Developer API ✓ Live
One API key across all 3 products. Full REST docs + interactive playground at /developers.
🔑 Coverage
Single API key covers URL Shortener, Link-in-Bio, and SmartPages endpoints
120 req/min general, 20 req/min auth endpoints, documented rate limits
Interactive playground pre-fills code snippets with the user's real API key
🚧 Remaining
API playground kept in sync as new endpoints ship
Rate-limit headers surfaced in API responses so integrators can self-throttle
💳 Billing & Payments
routes/payments.js v1.0.2 — Razorpay order-based flow. Real pricing fully built; Pro currently shown as $0.
💳 Core Billing ✓ Live
Razorpay Create-Order flow, INR at the gateway (India-only constraint)
Geo-aware USD/INR pricing hook, v3.1.0 — single backend source, no hardcoded prices
payment.captured webhook wired to renderProWelcomeEmail via ctx.waitUntil
payment.refunded webhook handled
🚧 Remaining / Decisions
Pro pricing actually switched on from $0 to real pricing (₹399/mo, $8/mo)
Annual billing (₹3,999/yr / $80/yr) live alongside monthly
🛠️ Admin Console ✓ Live
admin-backend.js v1.0.3 (526 lines) + admin-pages.js (194 lines) — Full Admin API V3.
🎛️ Coverage
Bootstrap-protected first-admin creation — requires ADMIN_SECRET, blocks if any admin exists
User management — view/search/suspend, is_disabled flag
Pricing/config manager — app_config editable without redeploy
audit_log — every admin action recorded with actor, action, target, timestamp
/__admin/stats — includes SmartPages stats (folded in per v1.0.3 change note)
Disabled-user → links cascade — flagged as an open item ("410 cascade fix") in the last known roadmap
🚧 Remaining
audit_log actually reviewed periodically, not just written and forgotten
🌐 Marketing Site
53 frontend pages total. 6 alternatives pages, 4 audience-targeted "for" pages, 3 Arabic pages, blog.
🏠 Core Pages ✓ Live
Homepage, pricing, about, blog architecture
6 alternatives pages — Bitly, Rebrandly, TinyURL, Linktree, Short.io, Carrd
4 "for" pages — India, Agencies, Creators, Marketers
/developers (68KB) with interactive API playground + /documentation (95KB)
Public status page (/status) — monitors Shortener, Bio, Analytics, QR, API, Cloudflare Edge
3 Arabic-localized pages — /ar/url-shortener, /ar/link-in-bio, /ar/landing-pages
Legal — Privacy, Terms, Cookie Policy, DMCA, Security, Report Abuse, all public
Cookie consent banner, GDPR-compliant
🚧 Remaining
Blog cover images — real image files, flagged as a still-open blocker on AdSense submission
AdSense submission + GA4 setup — sequenced right after ms9
🔐 Security Checklist
Categorized, severity-tagged, grounded in the actual codebase — including a genuinely serious layered anti-abuse system most URL shorteners don't bother building.
The platform's #1 named gap: runtime enforcement of app_config changes in the worker. The admin panel can save a value the worker doesn't actually read yet — close this before treating any config value as authoritative.
✅ No-Bug / QA Policy
The discipline that keeps production clean. Adopt these as standing practice, not a one-time checklist.
The bar: a feature is not "done" until verified on the live Worker via wrangler tail or a real curl check — local success and production success are different bars, confirmed by the exact class of bug (broken QR/routing from stale index.js) that already happened once during the V2→V3 migration.
⏳ Growth Timeline — 1 Week → 5 Years
Every horizon has its own focus and checklist. Switch tabs to zoom in or out on the plan.
Phase Roadmap (0–6)
Reconciled against the actual codebase and both historical docs, not treated as strictly sequential. Click a phase to expand.
🛰️ Future Modules
Genuinely not built yet — confirmed by searching the actual codebase, not just carried over from the old tracker's "future" list.
📋 Tracked Tasks
Custom domain for PRO — links.yourbrand.com via Cloudflare Custom Hostnames API
Team/Workspace plan — shared links, Admin/Member/Viewer roles
Chrome Extension — right-click "Shorten with Alshorty", Manifest v3
Referral / affiliate program — recurring revenue share per Pro referral
Click-event webhooks (Zapier/Make/n8n) — distinct from the existing Razorpay payment webhook
AI Smart Slug — memorable slugs from destination content via Workers AI
QR code customization — logo overlay, custom colors, SVG/PDF export
Deep Link routing — iOS App Store / Android Play Store specific URLs
📣 Marketing Channels
How to play reachability — owned content, product-led growth, community, partnerships, and paid (not yet — Pro is $0).
✅ Marketing Action Checklist
🔍 SEO Playbook
Technical foundation, keyword strategy, link building, and measurement.
The one item that undercuts everything else here: SmartPages is not server-rendered at /p/*. A landing-page product invisible to crawlers is the single highest-leverage SEO fix on this entire list — see the SmartPages panel.
✅ SEO Action Checklist
💼 Business & Revenue
Pricing, unit economics, retention — grounded in the real, currently-disabled pricing.ts model.
💳 Plan Tiers
✅ Business Action Checklist
Ownership Matrix
The most important document. Before building any feature — check this first.
The core question: could more than one product (Shortener, Bio, SmartPages) reuse this in the next 12 months? YES → Build in Core. NO → Build inside that product's own logic.
Feature Ownership
| Feature | Owner | Location | Notes |
|---|---|---|---|
| Authentication (magic-link, OAuth, sessions) | Core | worker/src/routes/auth.js | v1.0.2 — every product imports this |
| Pricing / config | Core | worker/src/config/constants.js | Single source of truth, app_config overrides at runtime (enforcement gap noted) |
| KV storage architecture | Core | 5 namespaces | SHORTY_LINKS holds link, bio, AND page objects — shared namespace, distinct key prefixes |
| R2 image storage | Core | alshorty-bio-images bucket | Used by Bio today; SmartPages image blocks likely reuse the same bucket |
| Abuse prevention (phishing scan, Safe Browsing, honeypots) | Core | worker/src/utils/security.js | v1.0.3 — runs on every link/bio/page creation, not product-specific |
| Link shortening + redirect logic | Shortener | routes/links.js, routes/redirect.js | 1,253 + 376 lines — the largest, oldest module |
| Bio page builder + rendering | Bio | routes/links.js (shared file), templates/bio-page.js | Not a separate route file — lives inside links.js |
| SmartPages block builder + rendering | SmartPages | routes/pages.js | v1.0.0 — the newest, least documented product |
| Analytics (clicks table) | Core (Analytics) | routes/analytics.js | Shared D1 table + query pattern across all 3 products |
| Payments | Core | routes/payments.js | One Razorpay flow covers Pro across all 3 products, not per-product billing |
Cross-Pillar Matrix
Which products consume which internal systems — and how built-out each pairing already is.
🚫 Kill List
Do NOT build any of these before real demand signal. Re-read this before every sprint.
If you find yourself about to build one of these: stop, re-read the Guiding Principles, and ask if there's a simpler path.
Tech Stack
Confirmed choices from the actual codebase.
⚠️ Risk Register
Named risks with their mitigation — revisit quarterly.
AI Cost Dashboard
Alshorty has no AI cascade today. This panel is forward-looking for AI Smart Slug (fu6) once it ships on Workers AI — set up now so it's ready when needed.
Platform Health
A weighted self-assessment across the dimensions that actually predict production pain. Adjust sliders as things change.
Release Readiness
A product is marked "Ready" only when its overall score is ≥85%, testing ≥70%, and docs ≥50%. No exceptions.
Technical Debt
Real, named gaps — plus any new shortcuts you take on purpose. Log them here so they get paid down deliberately.
Title
Severity
Est. hours
Decisions Log
Lightweight Architecture Decision Records. Capture the why, not just the what.
Decision
Reason
Alternatives considered
My Notes
Free-form workspace. What you're building today, blockers, ideas.
Current Focus
Blockers
Next 3 Actions
Decisions Made (free-form)
Open Questions
Abandoned / Deprioritized
Ideas Backlog