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
• QRCodeDesign entity
• Domain entity
• Event entity
• Asset entity
• ApiKey entity
• EmailVerificationToken entity
• PasswordResetToken entity

Authentication

• User registration endpoint (POST /auth/register)
• User login endpoint (POST /auth/login)
• JWT token generation
• Forgot password endpoint (POST /auth/forgot)
• Reset password endpoint (POST /auth/reset)
• Email verification endpoint (POST /auth/verify-email)
• Resend verification endpoint (POST /auth/resend-verification)
• Get profile endpoint (GET /auth/profile)
• Update profile endpoint (PUT /auth/profile)
• Change password endpoint (POST /auth/change-password)
• Delete account endpoint (DELETE /auth/account)

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
• Auth endpoint tests
• Domain endpoint tests

---

Phase 2: Core Link Features (Complete)

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
• List short links (GET /workspaces/{id}/links)
  • Filter by project
  • Filter by status
  • Include deleted (soft delete support)
• Get short link (GET /workspaces/{id}/links/{id})
• Update short link (PUT /workspaces/{id}/links/{id})
• Delete short link (DELETE /workspaces/{id}/links/{id}) - soft delete
• Restore short link (POST /workspaces/{id}/links/{id}/restore)
• Bulk create links (POST /workspaces/{id}/links/bulk)

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)
  • Log event (async, non-blocking)
  • Return 302 redirect
• Password-protected link handling (POST /{slug})
• Rate limiting on redirect endpoint

---

Phase 3: Event Tracking & Analytics (Complete)

Event Logging

• Event logging service (IEventTrackingService)
  • IP hashing (privacy)
  • User agent parsing (device type)
  • GeoIP lookup (country) - MaxMind GeoIP2 integrated
  • Referrer capture
  • Dedupe key generation (30-min window)
• Click event recording (from redirect)
• Scan event recording (from QR with ?qr= param)
• Async/background event processing

Analytics Endpoints

• Workspace analytics (GET /workspaces/{id}/analytics)
  • Total clicks/scans
  • Unique visitors
  • Time series data
  • Top links breakdown
  • Device breakdown
  • Referrer breakdown
  • Country breakdown (geo)
• Link analytics (GET /workspaces/{id}/links/{id}/analytics)
• QR code analytics (GET /workspaces/{id}/qrcodes/{id}/analytics)
• Time filters (24h, 7d, 30d)
• [~] Custom date range filter (backend supports startDate/endDate, frontend needs UI)

---

Phase 4: QR Code Designer (Complete)

QR Code Generation

• QR code generation service (IQRCodeGeneratorService)
  • QRCoder library
  • 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, Rounded, Dots)
  • Eye shapes (Square, Rounded, Circle)
  • Logo embedding with size control

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)
• Export QR (GET /workspaces/{id}/qrcodes/{id}/export?format=png|svg&size=N)
• QR exports include ?qr={id} for scan attribution

Asset Management

• Upload asset endpoint (POST /workspaces/{id}/assets)
• List assets (GET /workspaces/{id}/assets)
• Get asset (GET /assets/{storageKey})
• Delete asset (DELETE /workspaces/{id}/assets/{id})

---

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)
  • Generate verification token
  • DNS TXT record verification
  • Mark as verified

---

Phase 6: Frontend Dashboard (Complete)

Authentication UI

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

Dashboard

• Workspace switcher with create/manage modals
• Dashboard home (overview stats, charts, breakdowns)
• Navigation/sidebar (AppLayout component)

Link Management UI

• Links list view with trash/restore
• Create link modal with UTM builder
• Edit link modal
• Link details with analytics
• Bulk import modal

QR Designer UI

• QR codes list with preview thumbnails
• QR designer page with color pickers
• Shape selectors (modules and eyes)
• Logo upload integration
• Live preview
• Export buttons (PNG/SVG)
• Style presets (6 presets)
• QR code detail/analytics page

Other UI Pages

• Analytics page with time series, breakdowns, geo
• Projects page with CRUD
• Domains page with verification flow
• Settings page (profile, password, API keys, delete account)
• Billing page with plan display and upgrade flow

State Management

• Pinia stores (auth, workspace)
• localStorage persistence for workspace selection
• Automatic data refresh on workspace change
• Proper initialization flow in App.vue

---

Phase 7: Production Readiness (Complete)

Security & Performance

• Rate limiting (auth and redirect endpoints)
• CORS configuration
• Global exception handling middleware
• Request error logging

Email System

• Email service interface (IEmailService)
• Console email service (development)
• SMTP email service (production)
• Email templates (verification, password reset)
• Email verification flow
• Password reset emails

Plan & Quotas

• Usage tracking service (IPlanLimitsService)
• Plan limits configuration (Free, Pro, Business)
• Usage endpoint (GET /usage)
• [~] Plan limits enforcement in create endpoints (service exists, needs integration)

API Keys

• Create API key (POST /workspaces/{id}/api-keys)
• List API keys (GET /workspaces/{id}/api-keys)
• Delete API key (DELETE /workspaces/{id}/api-keys/{id})
• API key authentication middleware

---

Phase 8: Payments & Billing (Complete)

Stripe Integration

• Stripe service (IStripeService)
• Stripe settings configuration
• Checkout session endpoint (POST /billing/checkout)
• Customer portal endpoint (POST /billing/portal)
• Subscription endpoint (GET /workspaces/{id}/subscription)
• Webhook handling (POST /billing/webhook)
• Billing UI with plan comparison

---

Remaining Tasks

High Priority

1. API Key Authentication

   • Middleware to authenticate requests using API keys
   • Scope validation (read, write, admin)

2. Plan Limits Enforcement

   • Integrate IPlanLimitsService.CanCreate* checks in create endpoints
   • Return 403 with upgrade message when limit reached

3. Custom Date Range UI

   • Add date picker to analytics pages
   • Backend already supports startDate/endDate params

Medium Priority

4. Background Jobs

   • Periodic domain verification checks
   • Event retention cleanup (delete old events per plan)
   • Monthly IP salt rotation for privacy

5. Input Validation

   • URL allowlist/denylist for abuse prevention
   • Stricter input sanitization

6. Testing

   • Add tests for new auth endpoints
   • Add tests for billing endpoints
   • Add tests for API key endpoints

Lower Priority

7. Print-Ready QR Options

   • High contrast mode toggle
   • CMYK color support

8. Advanced Analytics

   • Export analytics data (CSV/JSON)
   • Scheduled reports

9. Webhooks

   • User-configurable webhooks for click events

---

Architecture Notes

• Backend: ASP.NET Core with FastEndpoints (vertical slice architecture)
• Frontend: Vue 3 + Vite + Pinia + Vue Router
• Database: PostgreSQL with EF Core
• Features: Located in src/api/Features/{Feature}/
• Authentication: JWT tokens, rate-limited auth endpoints
• Email: Pluggable service (Console for dev, SMTP for prod)
• Payments: Stripe integration with webhooks

---

API Endpoints Summary

Auth

Method	Path	Description
POST	/auth/register	Register new user
POST	/auth/login	Login
POST	/auth/forgot	Request password reset
POST	/auth/reset	Reset password with token
POST	/auth/verify-email	Verify email with token
POST	/auth/resend-verification	Resend verification email
GET	/auth/profile	Get current user profile
PUT	/auth/profile	Update profile
POST	/auth/change-password	Change password
DELETE	/auth/account	Delete account

Workspaces

Method	Path	Description
GET	/workspaces	List user's workspaces
POST	/workspaces	Create workspace
GET	/workspaces/{id}	Get workspace
PUT	/workspaces/{id}	Update workspace
DELETE	/workspaces/{id}	Delete workspace

Projects

Method	Path	Description
GET	/workspaces/{id}/projects	List projects
POST	/workspaces/{id}/projects	Create project
GET	/workspaces/{id}/projects/{pid}	Get project
PUT	/workspaces/{id}/projects/{pid}	Update project
DELETE	/workspaces/{id}/projects/{pid}	Delete project

Links

Method	Path	Description
GET	/workspaces/{id}/links	List links
POST	/workspaces/{id}/links	Create link
POST	/workspaces/{id}/links/bulk	Bulk create links
GET	/workspaces/{id}/links/{lid}	Get link
PUT	/workspaces/{id}/links/{lid}	Update link
DELETE	/workspaces/{id}/links/{lid}	Soft delete link
POST	/workspaces/{id}/links/{lid}/restore	Restore deleted link
GET	/workspaces/{id}/links/{lid}/analytics	Get link analytics

QR Codes

Method	Path	Description
GET	/workspaces/{id}/qrcodes	List QR codes
POST	/workspaces/{id}/qrcodes	Create QR code
GET	/workspaces/{id}/qrcodes/{qid}	Get QR code
PUT	/workspaces/{id}/qrcodes/{qid}	Update QR code
DELETE	/workspaces/{id}/qrcodes/{qid}	Delete QR code
GET	/workspaces/{id}/qrcodes/{qid}/preview	Get QR preview (data URL)
GET	/workspaces/{id}/qrcodes/{qid}/export	Export QR (PNG/SVG)
GET	/workspaces/{id}/qrcodes/{qid}/analytics	Get QR analytics

Domains

Method	Path	Description
GET	/workspaces/{id}/domains	List domains
POST	/workspaces/{id}/domains	Add domain
GET	/workspaces/{id}/domains/{did}	Get domain
DELETE	/workspaces/{id}/domains/{did}	Delete domain
POST	/workspaces/{id}/domains/{did}/verify	Verify domain

Assets

Method	Path	Description
GET	/workspaces/{id}/assets	List assets
POST	/workspaces/{id}/assets	Upload asset
DELETE	/workspaces/{id}/assets/{aid}	Delete asset
GET	/assets/{storageKey}	Get asset file (public)

Analytics

Method	Path	Description
GET	/workspaces/{id}/analytics	Workspace analytics

API Keys

Method	Path	Description
GET	/workspaces/{id}/api-keys	List API keys
POST	/workspaces/{id}/api-keys	Create API key
DELETE	/workspaces/{id}/api-keys/{kid}	Delete API key

Billing

Method	Path	Description
POST	/billing/checkout	Create Stripe checkout session
POST	/billing/portal	Create Stripe portal session
GET	/workspaces/{id}/subscription	Get subscription details
POST	/billing/webhook	Stripe webhook handler

Usage

Method	Path	Description
GET	/usage	Get usage stats and limits

Public

Method	Path	Description
GET	/{slug}	Redirect to destination
POST	/{slug}	Redirect with password