initial commit

docs/spec.md

@@ -0,0 +1,283 @@
+# QR-First URL Shortener SaaS (Designer + Short Links + Tracking)
+
+Note: These specs are a draft and need review.
+
+## 0) Product Definition
+
+One-liner: Create branded short links and highly customizable QR codes, then track scans/clicks with actionable analytics.
+
+Primary users:
+- Solo creators / small businesses
+- Marketing teams in SMB/PME
+- Agencies managing multiple clients
+
+Core value: Beautiful QR designs + brandable short domains + trustworthy tracking in one place.
+
+## 1) MVP Scope (what ships first)
+
+### 1.1 User Capabilities (MVP)
+
+Auth & Account
+- Sign up / sign in (email + password; optional SSO later)
+- Email verification
+- Password reset
+- Basic account settings
+
+Projects / Workspaces
+- Default workspace per user
+- Create “Projects” to organize links/QRs (e.g., “Restaurant menus”, “Flyers Q1”)
+
+Short Link Creation
+- Create short link: https://d.om/abc123 or custom slug …/menu
+- Destination URL validation
+- Optional UTM builder (preset templates)
+- Enable/disable link
+- Expiration date (optional)
+- Password protection (optional) — may be “Pro” if you want
+
+QR Code Designer
+- Generate QR from a short link (default) or direct URL
+- Styling:
+  - Colors (foreground/background)
+  - Error correction level (L/M/Q/H)
+  - Quiet zone padding
+  - Shape presets (modules/eyes) (start with a few presets)
+  - Center logo upload (PNG/SVG) with size + margin controls
+- Export:
+  - PNG and SVG
+  - Size presets (e.g., 256/512/1024/2048)
+  - Print-ready options (e.g., “high contrast” toggle)
+
+Tracking & Analytics (MVP)
+- Track events: click (short link) and scan (QR)
+- Dashboard:
+  - Total events, uniques, last 24h / 7d / 30d
+  - Time series
+  - Top referrers (for clicks)
+  - Geo (country) and device (desktop/mobile) high-level
+  - Per-link analytics and per-QR analytics
+
+Basic Admin
+- Subscription status
+- Usage quotas (links/QRs/events)
+
+## 2) Non-Goals for MVP (explicitly out)
+
+- Team roles/permissions (RBAC) beyond “owner”
+- A/B routing, smart rules, rotation, geo routing
+- Deep campaign automation
+- Enterprise SSO, SCIM
+- Offline QR scan tracking (impossible without network in most cases)
+
+## 3) Plans & Monetization (recommended)
+
+Free
+- 1 workspace
+- 25 short links
+- 25 QR designs
+- 10k events/month
+- 1 custom QR logo upload (or allow unlimited but watermark exports)
+
+Pro (individual/SMB)
+- Custom domains (1–3)
+- Higher limits
+- No watermark
+- UTM templates
+- Expiring links / password links (if Pro)
+
+Business
+- Multiple workspaces
+- Team seats (later)
+- Higher retention and export presets
+
+## 4) Core Entities (Data Model)
+
+### 4.1 Entities
+
+User
+- id, email, password_hash, verified_at, created_at
+
+Workspace
+- id, owner_user_id, name, plan, created_at
+
+Project
+- id, workspace_id, name, created_at
+
+Domain
+- id, workspace_id, hostname, status (pending/verified/active), verification_token, created_at
+
+ShortLink
+- id
+- workspace_id, project_id (nullable)
+- domain_id (nullable; else default platform domain)
+- slug
+- destination_url
+- title (nullable)
+- status (active/disabled)
+- expires_at (nullable)
+- password_hash (nullable)
+- created_at, updated_at
+
+QRCodeDesign
+- id
+- workspace_id, project_id (nullable)
+- shortlink_id (nullable; recommended default)
+- style_json (colors, shapes, ecc level, etc.)
+- logo_asset_id (nullable)
+- created_at, updated_at
+
+Event
+- id (or bigint)
+- workspace_id
+- shortlink_id
+- qrcode_id (nullable but strongly recommended to tag scans)
+- type: click | scan
+- ts
+- ip_hash (privacy-safe)
+- user_agent
+- referrer
+- country_code (nullable)
+- device_type (nullable)
+- dedupe_key (nullable)
+- raw_json (optional for debug, or drop)
+
+Asset
+- id, workspace_id, type (logo), storage_key, mime, size, created_at
+
+### 4.2 Key Design Choice
+
+How do we distinguish “scan” vs “click”?
+
+When exporting a QR, embed a URL like:
+https://d.om/s/abc123?qr=<qrcode_id>
+
+The redirect endpoint records scan when it detects qr=<id>, then redirects to destination, which will also produce a click unless you decide “scan implies click” and record only one.
+
+Recommendation: record one event per redirect request:
+- If qr present → type=scan
+- Else → type=click
+
+## 5) System Behavior (Routes & Flows)
+
+### 5.1 Public Redirect
+
+GET /{slug}
+
+Resolve domain + slug → short link
+
+Validate:
+- exists
+- active
+- not expired
+- if password-protected → show password page
+
+Log event (scan/click)
+
+Redirect 301/302 (configurable later; MVP use 302)
+
+### 5.2 QR Export
+
+QR code is generated from:
+
+Redirect URL including qrcode id: https://{domain}/{slug}?qr={qrcode_id}
+
+## 6) Functional Requirements (MVP checklist)
+
+Link Management
+- Create, edit, disable, delete (soft delete preferred)
+- Slug uniqueness per domain
+- Auto-slug generator (base62)
+- Destination URL allowlist/denylist (prevent abuse)
+
+QR Designer
+- Live preview
+- Save design
+- Export SVG/PNG
+- Logo upload with validation (size/mime)
+
+Analytics
+- Views for:
+  - Workspace overview
+  - Project overview
+  - Per short link
+  - Per QR design
+- Time filters: 24h / 7d / 30d / custom range
+- Unique definition:
+  - Unique per day per link based on ip_hash + UA hash (privacy-safe and approximate)
+
+## 7) Non-Functional Requirements
+
+Performance
+- Redirect endpoint P95 < 100ms (excluding DNS/TLS)
+- Event write must not block redirect (use async queue if possible)
+
+Availability
+- Redirect is the critical path; should stay up even if dashboard is down
+- Graceful degradation: if analytics store is down, still redirect
+
+Security
+- Rate limit public endpoints
+- Abuse prevention: phishing/malware reporting flow (later), basic filters now
+- Domain verification to prevent takeover
+- Strict CSP on app pages
+
+Privacy & Compliance (Canada / Quebec friendly baseline)
+- Avoid storing raw IP; store hashed IP with rotating salt (e.g., monthly)
+- Provide retention configuration per plan (e.g., 30/180/365 days)
+
+## 8) Architecture (pragmatic MVP)
+
+Components
+- Web App: dashboard + designer (Vue/React)
+- API: CRUD for links/qr/projects/domains, analytics queries
+- Redirect Edge: fastest path for /{slug} (can be same API initially)
+
+Storage
+- PostgreSQL for core entities
+- Analytics:
+  - MVP: PostgreSQL events table partitioned by month
+  - Later: ClickHouse/BigQuery for scale
+
+Background Jobs
+- Domain verification checks
+- Event enrichment (geo/device parsing)
+- Cleanup & retention tasks
+
+## 9) API Surface (minimal)
+
+- POST /auth/register|login|forgot|reset
+- GET/POST /workspaces
+- GET/POST /projects
+- GET/POST /links
+- GET/POST /qrcodes
+- POST /domains + verification status
+- GET /analytics/overview
+- GET /analytics/link/{id}
+- GET /analytics/qrcode/{id}
+
+## 10) UI Pages (MVP)
+
+- Login / Register / Reset
+- Workspace switcher
+- Projects list
+- Links list + create/edit
+- QR designer (create/edit) with preview
+- Analytics dashboard (overview + per link + per QR)
+- Domains page (add/verify)
+
+## 11) Pricing/Quotas Enforcement
+
+Enforce at API level:
+- max links, max QR codes, max events/month, max custom domains
+
+Stripe integration later; MVP can be “manual Pro” toggle or Stripe from day 1 if you want.
+
+## 12) Implementation Notes (key decisions)
+
+- Use one redirect URL as canonical; QR adds ?qr= for attribution.
+- Event logging should be non-blocking:
+  - MVP: write to DB async (background queue) or “fire-and-forget” with retry
+- Plan for domain verification:
+  - Require DNS TXT record or CNAME to verify ownership
+- Short link collision:
+  - Slug uniqueness per domain enforced in DB