trakqr/docs/tasks.md

# TrakQR Implementation Tasks

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

## Status Legend
- [ ] Not started
- [~] In progress / Partial
- [x] Complete

---

## Phase 1: Foundation (Complete)

### Database & Models
- [x] PostgreSQL setup
- [x] EF Core configuration
- [x] User entity
- [x] Workspace entity
- [x] Project entity
- [x] ShortLink entity (model only)
- [x] QRCodeDesign entity (model only)
- [x] Domain entity (model only)
- [x] Event entity (model only)
- [x] Asset entity (model only)

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

### Workspaces & Projects
- [x] Create workspace (`POST /workspaces`)
- [x] List workspaces (`GET /workspaces`)
- [x] Get workspace (`GET /workspaces/{id}`)
- [x] Update workspace (`PUT /workspaces/{id}`)
- [x] Delete workspace (`DELETE /workspaces/{id}`)
- [x] Create project (`POST /workspaces/{id}/projects`)
- [x] List projects (`GET /workspaces/{id}/projects`)
- [x] Get project (`GET /workspaces/{id}/projects/{id}`)
- [x] Update project (`PUT /workspaces/{id}/projects/{id}`)
- [x] Delete project (`DELETE /workspaces/{id}/projects/{id}`)
- [x] Auto-create default workspace on signup
- [x] Ownership verification / access control

### Testing Infrastructure
- [x] ApiWebApplicationFactory for integration tests
- [x] Project endpoint tests
- [x] Workspace endpoint tests
- [x] Link endpoint tests

---

## Phase 2: Core Link Features (Next Priority)

### Short Link CRUD
- [x] 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)
- [x] List short links (`GET /workspaces/{id}/links`)
  - Filter by project
  - Filter by status
  - Pagination (not yet)
- [x] Get short link (`GET /workspaces/{id}/links/{id}`)
- [x] Update short link (`PUT /workspaces/{id}/links/{id}`)
  - Update destination URL
  - Update title
  - Enable/disable (status)
  - Set expiration date
  - Set password protection
- [x] Delete short link (`DELETE /workspaces/{id}/links/{id}`)
- [x] Short link tests (15 tests)

### Public Redirect Endpoint
- [x] `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
- [x] Default domain configuration (using null domain for now)
- [x] Password-protected link handling (`POST /{slug}` with password)
- [x] Redirect endpoint tests (10 tests)

---

## Phase 3: Event Tracking & Analytics

### Event Logging
- [x] 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) ✓
- [x] Click event recording (from redirect)
- [~] Scan event recording (from QR) - ready, needs QR endpoints
- [x] Async/background event processing (fire-and-forget)
- [x] Event tracking tests (5 tests)

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

---

## Phase 4: QR Code Designer

### QR Code Generation
- [x] QR code generation service (`IQRCodeGeneratorService`)
  - Uses QRCoder library ✓
  - Support different error correction levels (L/M/Q/H) ✓
  - Quiet zone configuration ✓
  - PNG and SVG output ✓
- [x] 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
- [x] Create QR design (`POST /workspaces/{id}/qrcodes`)
- [x] List QR designs (`GET /workspaces/{id}/qrcodes`)
- [x] Get QR design (`GET /workspaces/{id}/qrcodes/{id}`)
- [x] Update QR design (`PUT /workspaces/{id}/qrcodes/{id}`)
- [x] Delete QR design (`DELETE /workspaces/{id}/qrcodes/{id}`)
- [x] Preview QR (`GET /workspaces/{id}/qrcodes/{id}/preview`) - returns data URL
- [x] Export QR as PNG (`GET /workspaces/{id}/qrcodes/{id}/export?format=png&size=512`)
- [x] Export QR as SVG (`GET /workspaces/{id}/qrcodes/{id}/export?format=svg`)
- [x] QR code endpoint tests (12 tests)

### Asset Management (for logos)
- [x] Upload asset endpoint (`POST /workspaces/{id}/assets`)
- [x] List assets (`GET /workspaces/{id}/assets`)
- [x] Get asset public endpoint (`GET /assets/{storageKey}`)
- [x] Delete asset (`DELETE /workspaces/{id}/assets/{id}`)
- [x] Asset storage service (local storage, S3 interface ready)
- [x] Asset endpoint tests (10 tests)

---

## Phase 5: Domain Management (Complete)

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

---

## Phase 6: Frontend Dashboard (Complete)

### Authentication UI
- [x] Login page
- [x] Registration page
- [x] Forgot password page
- [x] Password reset page
- [x] Auth state management (Pinia store)

### Dashboard
- [x] Workspace switcher
- [x] Dashboard home (overview stats)
- [x] Navigation/sidebar (AppLayout component)

### Link Management UI
- [x] Links list view
- [x] Create link modal
- [x] Edit link modal
- [x] Link details with analytics

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

### Analytics UI
- [x] Charts (time series with clicks/scans)
- [x] Stat cards (clicks, scans, visitors, total)
- [x] Breakdown tables (referrer, device)
- [x] 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