Plan: mcd-tracker

Plan: mcd-tracker

Vision

Projects & Repos Touched

Context

• [x] Project created in pal-e-docs (project-mcd-tracker)
• [x] Project page created with user stories, architecture stubs, repo table
• [x] Plan created (this note)
• [ ] Board created
• [ ] Architecture diagram notes created

Previous Plan

Depends On

• plan-pal-e-platform — platform must be stable (it is: 16/19 phases completed)
• plan-pal-e-agency — SOPs and conventions must exist (they do: all 13 phases resolved)

Phases

Phase 1: Service Onboarding (COMPLETED)

• Add mcd-tracker entry to pal-e-services/terraform/k3s.tfvars var.services map:

  mcd-tracker = {
    forgejo_repo = "forgejo_admin/mcd-tracker-api"
    image_repo   = "mcd-tracker/api"
    port         = 8000
    funnel       = true
    source_repo  = "forgejo_admin/pal-e-deployments"
    source_path  = "overlays/mcd-tracker/prod"
  }

• tofu plan -lock=false → verify 6-7 new resources (namespace, Harbor project, robot accounts, pull secret, ArgoCD app, funnel ingress)
• tofu apply -lock=false
• Create kustomize overlay: pal-e-deployments/overlays/mcd-tracker/prod/

Phase 2: Backend Scaffold + First Deploy (COMPLETED)

• Create mcd-tracker-api repo on Forgejo
• Scaffold FastAPI app (following basketball-api pattern):
• Activate Woodpecker → add Harbor secrets (harbor_username, harbor_password)
• Push → green pipeline → Harbor image → ArgoCD deploys
• Verify: curl https://mcd-tracker.tail5b443a.ts.net/healthz

Phase 3: Data Model + Postgres (COMPLETED)

• Add Postgres sidecar to kustomize overlay (postgres.yaml — Postgres 16-alpine, 1Gi PVC, ClusterIP service)
• Add src/mcd_tracker_api/database.py — engine, SessionLocal, get_db()
• Add src/mcd_tracker_api/models.py — SQLAlchemy models:
• Init Alembic, create first migration
• Update health endpoint to verify DB connection
• Deploy — verify migration runs on startup

• No separate User table — user identity comes from Keycloak JWT (sub claim). Store keycloak_sub as FK-like reference on Location and CouponUsage.
• Rolling window query: SELECT COUNT(*) FROM coupon_usage WHERE location_id = ? AND user_id = ? AND used_at > NOW() - INTERVAL '30 days'
• Slot reopens: MIN(used_at) + 30 days from the 5 active usages at a location

Phase 4: Keycloak Realm + Auth (COMPLETED)

• Create mcd-tracker realm in Keycloak admin console
• Create realm roles: user, admin
• Create OIDC client: mcd-tracker-app (for SvelteKit) and mcd-tracker-ios (for Swift, public client + PKCE)
• Add src/mcd_tracker_api/auth.py — JWKS fetch, JWT decode, User dataclass, require_role dependency factory (copy basketball-api pattern)
• Add config: MCD_TRACKER_KEYCLOAK_REALM_URL
• Update deployment-patch.yaml with Keycloak env var
• Create test user + admin user in realm

Phase 5: Core API Endpoints + Integration Tests (COMPLETED)

• Routes:
• Rolling window logic:
• Integration tests (pytest, real Postgres):
• Deploy and verify via curl

Phase 6: Frontend Playground (IN PROGRESS — CSS consolidated, @-comment specs added, pending phone approval)

• Decide: folder experiment in html-playground or repo experiment (mcd-tracker-playground)
• Create screens (vanilla HTML/CSS, hardcoded data):
• Mobile-first design — this is a phone app at heart
• Lucas verifies on phone via Tailscale funnel
• Iterate until design locks

Phase 7: SvelteKit + Capacitor Frontend (IN PROGRESS — scaffold deployed, Docker Compose merged, pending local validation)

• Create mcd-tracker-app repo on Forgejo
• SvelteKit scaffold with Auth.js + Keycloak OIDC (copy westside-app pattern)
• Direct port from playground: copy CSS → scoped styles, copy HTML → Svelte templates, replace hardcoded data with {data.foo} bindings
• Pages: / (dashboard), /add (log code), /locations (manage), /history, /admin (stats)
• Service onboarding for frontend: add mcd-tracker-app to k3s.tfvars + kustomize overlay
• Deploy, verify on phone

Phase 8: Mac Woodpecker Agent (NOT STARTED)

• Install Xcode on MacBook Air M1 (App Store)
• Install Woodpecker agent binary (brew install woodpecker-ci/tap/woodpecker-agent or direct download)
• Configure agent with local backend:

  WOODPECKER_SERVER=https://woodpecker.tail5b443a.ts.net
  WOODPECKER_AGENT_SECRET=<from k3s.tfvars>
  WOODPECKER_BACKEND=local
  WOODPECKER_FILTER_LABELS=platform=darwin

• Create launchd plist for auto-start on boot
• Install Fastlane: brew install fastlane
• Verify: agent appears in Woodpecker UI, test pipeline with labels: [platform: darwin] runs on Mac

Phase 9: Capacitor iOS Build + Native Plugins (NOT STARTED — replaces Swift app)

• Create mcd-tracker-ios repo on Forgejo
• SwiftUI app scaffold:
• Keycloak OIDC auth via ASWebAuthenticationSession (public client + PKCE — mcd-tracker-ios client created in Phase 4)
• API client layer — same endpoints as SvelteKit, JWT Bearer auth
• .woodpecker.yaml with labels: [platform: darwin] — targets Mac agent
• Pipeline: xcodebuild test → xcodebuild archive → export .ipa

Phase 10: App Store Submission (NOT STARTED)

• Enroll in Apple Developer Program ($99/yr)
• Fastlane setup:
• CI pipeline addition: after xcodebuild archive, run fastlane pilot upload
• TestFlight beta distribution — Lucas + testers validate
• App Store submission — metadata, screenshots, privacy policy, review
• Post-approval: pipeline does git push → test → build → TestFlight → (manual promote to App Store)

Phase 11: Analytics + Dual-Channel Tracking (NOT STARTED)

Phase 12: Monetization (NOT STARTED — when ~100 active users)

Phase 13: Gamification + XP System (NOT STARTED)

Phase 14: Receipt Intelligence (NOT STARTED)

Key Files

Verification

• [ ] Phase 1: kubectl get ns mcd-tracker exists, ArgoCD app visible
• [ ] Phase 2: curl https://mcd-tracker.tail5b443a.ts.net/healthz returns 200
• [ ] Phase 3: Health endpoint shows DB connected, Alembic migration applied
• [ ] Phase 4: Unauthenticated request returns 401, authenticated returns 200
• [ ] Phase 5: Log 6 codes at one location → 6th rejected (limit 5). Wait 30 days (or mock time) → slot reopens. All integration tests green.
• [ ] Phase 6: Lucas approves all screens on phone
• [ ] Phase 7: Web app live, login works, can log and redeem codes
• [ ] Phase 8: Mac agent visible in Woodpecker UI, test pipeline completes
• [ ] Phase 9: iOS app builds on Mac CI, runs on physical iPhone
• [ ] Phase 10: App live on App Store, pipeline: push → TestFlight in <10 min

Related

• project-mcd-tracker — project page
• service-onboarding-sop — Phase 1 procedure
• convention-kustomize-overlay — Phase 1 overlay pattern
• sop-frontend-experiment — Phase 6 playground workflow
• plan-pal-e-platform — platform this project runs on
• plan-pal-e-agency — SOPs and conventions this project follows