trakqr/docs/tasks.md

TrakQR Implementation Tasks

This file tracks implementation progress. Update status as work completes.

Status Legend

• Not started
• [~] In progress / Partial
• Complete

---

Phase 1: Foundation (Complete)

Database & Models

• PostgreSQL setup
• EF Core configuration
• User entity
• Workspace entity
• Project entity
• ShortLink entity (model only)
• QRCodeDesign entity (model only)
• Domain entity (model only)
• Event entity (model only)
• Asset entity (model only)

Authentication

• User registration endpoint (POST /auth/register)
• User login endpoint (POST /auth/login)
• JWT token generation
• [~] Forgot password endpoint (endpoint exists, email TODO)
• [~] Reset password endpoint (endpoint exists, needs completion)
• Email verification flow

Workspaces & Projects

• Create workspace (POST /workspaces)
• List workspaces (GET /workspaces)
• Get workspace (GET /workspaces/{id})
• Update workspace (PUT /workspaces/{id})
• Delete workspace (DELETE /workspaces/{id})
• Create project (POST /workspaces/{id}/projects)
• List projects (GET /workspaces/{id}/projects)
• Get project (GET /workspaces/{id}/projects/{id})
• Update project (PUT /workspaces/{id}/projects/{id})
• Delete project (DELETE /workspaces/{id}/projects/{id})
• Auto-create default workspace on signup
• Ownership verification / access control

Testing Infrastructure

• ApiWebApplicationFactory for integration tests
• Project endpoint tests
• Workspace endpoint tests
• Link endpoint tests

---

Phase 2: Core Link Features (Next Priority)

Short Link CRUD

• Create short link endpoint (POST /workspaces/{id}/links)
  • Custom slug or auto-generate
  • URL validation
  • Title (optional)
  • Project assignment (optional)
  • Domain selection (default domain initially)
• List short links (GET /workspaces/{id}/links)
  • Filter by project
  • Filter by status
  • Pagination (not yet)
• Get short link (GET /workspaces/{id}/links/{id})
• Update short link (PUT /workspaces/{id}/links/{id})
  • Update destination URL
  • Update title
  • Enable/disable (status)
  • Set expiration date
  • Set password protection
• Delete short link (DELETE /workspaces/{id}/links/{id})
• Short link tests (15 tests)

Public Redirect Endpoint

• GET /{slug} redirect endpoint
  • Resolve domain + slug to destination
  • Check link exists
  • Check link is active
  • Check not expired
  • Check password (if protected, return 401 with X-Password-Required header)
  • Log event (async, non-blocking) - TODO Phase 3
  • Return 302 redirect
• Default domain configuration (using null domain for now)
• Password-protected link handling (POST /{slug} with password)
• Redirect endpoint tests (10 tests)

---

Phase 3: Event Tracking & Analytics

Event Logging

• Event logging service (IEventTrackingService)
  • IP hashing (privacy) ✓
  • User agent parsing (device type) ✓
  • GeoIP lookup (country) - TODO: integrate GeoIP database
  • Referrer capture ✓
  • Dedupe key generation (30-min window) ✓
• Click event recording (from redirect)
• [~] Scan event recording (from QR) - ready, needs QR endpoints
• Async/background event processing (fire-and-forget)
• Event tracking tests (5 tests)

Analytics Endpoints

• Workspace analytics (GET /workspaces/{id}/analytics)
  • Total clicks/scans ✓
  • Unique visitors ✓
  • Time series data ✓
  • Top links breakdown ✓
  • Device breakdown ✓
  • Referrer breakdown ✓
• Link analytics (GET /workspaces/{id}/links/{id}/analytics)
  • Per-link stats ✓
  • Referrer breakdown ✓
  • Device breakdown ✓
  • Geo breakdown - TODO: integrate GeoIP database
• Time filters (24h, 7d, 30d, all-time)
• Analytics endpoint tests (9 tests)

---

Phase 4: QR Code Designer

QR Code Generation

• QR code generation service (IQRCodeGeneratorService)
  • Uses QRCoder library ✓
  • Support different error correction levels (L/M/Q/H) ✓
  • Quiet zone configuration ✓
  • PNG and SVG output ✓
• QR code design model integration
  • Foreground/background colors ✓
  • Module shapes (square) - more shapes TODO
  • Eye shapes - TODO
  • Logo embedding - TODO (needs asset upload)

QR Code Endpoints

• Create QR design (POST /workspaces/{id}/qrcodes)
• List QR designs (GET /workspaces/{id}/qrcodes)
• Get QR design (GET /workspaces/{id}/qrcodes/{id})
• Update QR design (PUT /workspaces/{id}/qrcodes/{id})
• Delete QR design (DELETE /workspaces/{id}/qrcodes/{id})
• Preview QR (GET /workspaces/{id}/qrcodes/{id}/preview) - returns data URL
• Export QR as PNG (GET /workspaces/{id}/qrcodes/{id}/export?format=png&size=512)
• Export QR as SVG (GET /workspaces/{id}/qrcodes/{id}/export?format=svg)
• QR code endpoint tests (12 tests)

Asset Management (for logos)

• Upload asset endpoint (POST /workspaces/{id}/assets)
• List assets (GET /workspaces/{id}/assets)
• Get asset public endpoint (GET /assets/{storageKey})
• Delete asset (DELETE /workspaces/{id}/assets/{id})
• Asset storage service (local storage, S3 interface ready)
• Asset endpoint tests (10 tests)

---

Phase 5: Domain Management (Complete)

Custom Domains

• Add domain (POST /workspaces/{id}/domains)
• List domains (GET /workspaces/{id}/domains)
• Get domain (GET /workspaces/{id}/domains/{id})
• Delete domain (DELETE /workspaces/{id}/domains/{id})
• Verify domain (POST /workspaces/{id}/domains/{id}/verify)
• Domain verification flow
  • Generate verification token ✓
  • Check DNS TXT record (stub - uses "verified-" prefix for testing)
  • Mark as verified ✓
• Domain status management (Pending → Verified)
• Domain endpoint tests (10 tests)

---

Phase 6: Frontend Dashboard (Complete)

Authentication UI

• Login page
• Registration page
• Forgot password page
• Password reset page
• Auth state management (Pinia store)

Dashboard

• Workspace switcher
• Dashboard home (overview stats)
• Navigation/sidebar (AppLayout component)

Link Management UI

• Links list view
• Create link modal
• Edit link modal
• Link details with analytics

QR Designer UI

• QR designer page
• Color pickers
• Shape selectors (Square, Rounded, Dots for modules; Square, Rounded, Circle for eyes)
• Logo upload integration (upload new or select from existing assets)
• Live preview (for saved QR codes)
• Export buttons (PNG/SVG)
• Style presets (6 presets with shape variations)

Analytics UI

• Charts (time series with clicks/scans)
• Stat cards (clicks, scans, visitors, total)
• Breakdown tables (referrer, device)
• Geo breakdown (country flags and names, requires MaxMind GeoIP2 database)

---

Phase 7: Production Readiness

Security & Performance

• Rate limiting
• Input sanitization
• CORS configuration
• Request logging
• Error handling middleware

Email System

• Email service integration (SendGrid/SES/etc.)
• Email verification emails
• Password reset emails
• Email templates

Plan & Quotas

• Usage tracking
• Plan limits enforcement
  • Free: 50 links, 1 workspacf - Pro: 5,000 links, 5 workspaces
  • Business: Unlimited
• Upgrade prompts

---

Phase 8: Post-MVP Features

Payments (Stripe)

• Stripe integration
• Checkout flow
• Subscription management
• Webhook handling

Advanced Features

• UTM builder
• Link groups/campaigns
• Bulk link creation
• API keys for external access
• Webhooks for events

---

Current Focus

Completed: Phase 2 + Phase 3 + Phase 4 + Phase 5 + Phase 6 (partial)

Backend (101 tests passing):

• Short Link CRUD (5 endpoints, 15 tests)
• Public Redirect Endpoint (2 endpoints, 10 tests)
• Event Tracking Service (click logging, dedupe, device detection)
• Analytics Endpoints (2 endpoints, 9 tests)
• QR Code Designer (7 endpoints, 12 tests)
• Domain Management (5 endpoints, 10 tests)
• Asset Upload (4 endpoints, 10 tests)

Frontend (Vue 3 + Vite + Pinia):

• Landing page with hero, features, analytics sections
• Login/Register pages with auth state management
• Dashboard with stats grid, activity chart, top links, device/referrer breakdowns
• Links page with CRUD modals, copy-to-clipboard, analytics link
• Link detail page with per-link analytics
• QR Codes list with preview thumbnails, export buttons
• QR Designer with color pickers, error correction, quiet zone, 6 presets
• Analytics page with time series chart, period selector, breakdowns

Next up:

• Complete forgot/reset password pages
• Add geo breakdown to analytics
• Logo upload integration in QR designer
• Phase 7 - Production Readiness (CORS, rate limiting, email)

Completed:

1. Create short link endpoint with auto-slug generation ✓
2. List/Get/Update/Delete short link endpoints ✓
3. Public redirect endpoint (GET /{slug}) ✓
4. Password redirect endpoint (POST /{slug}) ✓
5. Event logging (basic click tracking) ✓
6. Analytics endpoints ✓
7. QR code generation and designer ✓
8. Domain management (add, list, get, delete, verify) ✓
9. Asset upload for QR logos ✓
10. Frontend dashboard with auth, links, QR, analytics ✓

---

Gap Analysis (Spec vs Implementation)

This section identifies gaps between the MVP spec (docs/spec.md) and the current implementation.

Authentication & Account

Spec Requirement	Status	Notes
Email verification	❌ Missing	Endpoint structure exists, but no email sending or verification flow
Basic account settings page	❌ Missing	No settings UI or endpoints for profile updates
SSO (optional, post-MVP)	⏳ Deferred	As expected

Short Link Features

Spec Requirement	Status	Notes
UTM builder (preset templates)	❌ Missing	Spec mentions UTM builder for Pro plan
Destination URL allowlist/denylist	❌ Missing	Abuse prevention not implemented
Soft delete for links	❌ Missing	Currently using hard delete

QR Code Designer

Spec Requirement	Status	Notes
Shape presets (module shapes)	✅ Complete	Square, Rounded, Dots module shapes supported
Eye shape customization	✅ Complete	Square, Rounded, Circle eye shapes supported
Logo upload integration	✅ Complete	Upload new or select from existing assets
Logo size + margin controls	⚠️ Partial	Fixed 20% size, no user controls
Print-ready options ("high contrast" toggle)	❌ Missing	No print optimization features

Analytics & Tracking

Spec Requirement	Status	Notes
Geo (country) breakdown	✅ Complete	MaxMind GeoIP2 integrated, UI with country flags
Per-QR analytics endpoint	❌ Missing	Spec: GET /analytics/qrcode/{id} - only link analytics exist
Scan vs Click distinction via ?qr= param	⚠️ Partial	Event type exists but QR export doesn't append ?qr=<id> to URLs
Custom date range filter	❌ Missing	Only 24h/7d/30d implemented, spec mentions custom range
Monthly IP salt rotation	❌ Missing	Spec requires rotating salt for privacy compliance
Event retention configuration per plan	❌ Missing	No retention policy or cleanup jobs

Admin & Quotas

Spec Requirement	Status	Notes
Subscription status display	❌ Missing	Plan field exists on Workspace but no UI
Usage quotas enforcement	❌ Missing	No limits enforced for links/QRs/events/domains
Upgrade prompts	❌ Missing	No paywall or upgrade flows

Security & Non-Functional

Spec Requirement	Status	Notes
Rate limiting on public endpoints	❌ Missing	Critical for redirect endpoint
CORS configuration	❌ Missing	Needs proper configuration
Strict CSP headers	❌ Missing	App pages have no CSP
Request logging	❌ Missing	No structured logging
Error handling middleware	❌ Missing	No global error handler

Frontend UI Pages

Spec Requirement	Status	Notes
Forgot password page	✅ Complete	Full UI with success state
Password reset page	✅ Complete	Full UI with token validation and success state
Projects list UI	❌ Missing	Backend CRUD complete, no frontend
Domains page (add/verify)	❌ Missing	Backend complete, no frontend
Workspace switcher (full UI)	⚠️ Partial	Basic switcher exists, no create/manage UI
Per-QR analytics view	❌ Missing	Only per-link analytics in UI

Email System

Spec Requirement	Status	Notes
Email service integration	❌ Missing	No email provider configured
Email verification emails	❌ Missing	No templates or sending logic
Password reset emails	❌ Missing	Token generated but not emailed
Email templates	❌ Missing	No templating system

Background Jobs

Spec Requirement	Status	Notes
Domain verification checks	❌ Missing	Only manual verification, no periodic checks
Event enrichment (geo/device)	✅ Complete	Device parsing and GeoIP country lookup done
Cleanup & retention tasks	❌ Missing	No scheduled cleanup for old events

API Surface Gaps

Endpoint (from spec)	Status
GET /analytics/qrcode/{id}	❌ Missing
Account settings endpoints	❌ Missing
Usage/quota endpoints	❌ Missing

---

Priority Gap Resolution

High Priority (MVP Blockers)

1. Email system - Verification and password reset cannot work without email
2. Rate limiting - Security risk without it on public redirect
3. QR scan tracking - QR exports need ?qr=<id> param for scan attribution
4. Geo breakdown - GeoIP integration for country-level analytics ✅ Complete
5. Projects UI - Backend exists, needs frontend

Medium Priority (MVP Polish)

6. Account settings page - Users need to update profile
7. Domains UI - Backend exists, needs frontend
8. Usage quotas - Enforce plan limits
9. QR shape presets - More customization options ✅ Complete (Square, Rounded, Dots)
10. Custom date range - Analytics flexibility

Lower Priority (Post-MVP)

11. UTM builder
12. Soft delete for links
13. Print-ready QR options
14. SSO integration
15. Stripe payments

---

Notes

• Backend uses FastEndpoints (not traditional MVC controllers)
• Vertical slice architecture: features in src/api/Features/{Feature}/
• All endpoints require JWT auth except public redirect
• Default domain: use app's domain until custom domains implemented