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) - TODO

• Upload asset endpoint (POST /workspaces/{id}/assets)
• List assets (GET /workspaces/{id}/assets)
• Delete asset (DELETE /workspaces/{id}/assets/{id})
• Asset storage (local/S3)

---

Phase 5: Domain Management

Custom Domains

• Add domain (POST /workspaces/{id}/domains)
• List domains (GET /workspaces/{id}/domains)
• Delete domain (DELETE /workspaces/{id}/domains/{id})
• Domain verification flow
  • Generate verification token
  • Check DNS TXT record
  • Mark as verified
• Domain status management (Pending → Verified → Active)

---

Phase 6: Frontend Dashboard

Authentication UI

• Login page
• Registration page
• Forgot password page
• Password reset page
• Auth state management

Dashboard

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

Link Management UI

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

QR Designer UI

• QR designer page
• Color pickers
• Shape selectors
• Logo upload
• Live preview
• Export buttons

Analytics UI

• Charts (time series)
• Stat cards
• Breakdown tables (referrer, geo, device)

---

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 workspace
  • 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

• 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)

Total: 81 tests passing

Next up: Phase 5 - Domain Management or Frontend Dashboard

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 ✓

---

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