drop-sprint1-implementation-plan

Plan: Drop Sprint 1 Implementation

Date: 2026-02-26 Author: John (AI Director) MC Task: #2110+ Status: PENDING APPROVAL Sprint Duration: 5 weeks (UI prototype with mock integrations)

Research Summary

Existing Codebase (MUCH more than expected)

• 46 API routes with complete business logic (auth, transactions, GDPR, admin, cards, merchants)
• 20 UI pages all with real content (zero stubs)
• 936-line db.ts with dual-driver (SQLite + PostgreSQL) — needs PostgreSQL-only refactor
• 13 database tables via node-pg-migrate (raw SQL, NOT Drizzle) — need 12 more tables
• BankID OIDC fully implemented with PSD2 dynamic linking (298-line callback)
• 12 Figma Make export screens (Vite+React) as UI source of truth
• docker-compose.production.yml already has PostgreSQL 16
• 2 test files — needs major expansion
• NO Drizzle ORM — currently raw SQL via better-sqlite3 + pg
• NO BullMQ/Redis — not yet implemented
• SHA-256 national_id_hash — must change to AES-256-GCM
• Email/password + PIN paths still in code — must remove for BankID-only

Key Insight

This is NOT a greenfield build. It's a refactor to align with architecture decisions + add missing infrastructure + extend with new FRs. The existing code is functional but pre-dates the architecture review.

Objective

Refactor existing Drop codebase to align with all 16 ADRs, add missing database tables and infrastructure (Redis, BullMQ, Drizzle), implement BankID-only auth, and bring UI in line with Figma Make export designs. All external integrations (BankID, ZTL, FX, compliance) remain mocked.

Team Orchestration

Team Members

Step-by-Step Tasks

Phase 1: Foundation (Week 1) — Database + Infrastructure

Task 1: PostgreSQL-only db.ts refactor

• Owner: B1
• BlockedBy: none
• Description: Replace 936-line dual-driver src/lib/db.ts with PostgreSQL-only via Drizzle ORM. Remove better-sqlite3 dependency. Remove all SQLite code paths. Install drizzle-orm + drizzle-kit + @neondatabase/serverless (for edge compat) or postgres driver. Create Drizzle schema matching existing 13 tables.
• Files: src/lib/db.ts, package.json, drizzle.config.ts
• Acceptance:
  • better-sqlite3 removed from package.json
  • drizzle-orm and drizzle-kit in dependencies
  • src/lib/db.ts uses Drizzle with pg driver only
  • All existing getOne(), getAll(), run() calls still work (adapter layer or full migration)
  • docker-compose.yml updated with PostgreSQL service for dev
  • drop.db SQLite file removed from project

Task 2: Drizzle schema for all 25 tables

• Owner: B1
• BlockedBy: 1
• Description: Create src/lib/schema.ts with Drizzle table definitions for all 25 tables per database-design.md. Remove node-pg-migrate, use Drizzle Kit for migrations. Include the 12 new tables: aml_alerts, str_reports, screening_results, consents, data_access_requests, complaints, reconciliation_reports, reconciliation_discrepancies, circuit_breaker_state, webhook_events, webhook_dlq, disputes.
• Files: src/lib/schema.ts, drizzle.config.ts, migrations/ (Drizzle format)
• Acceptance:
  • 25 Drizzle table definitions matching database-design.md
  • All FKs, indexes, constraints defined
  • national_id_hash column renamed to national_id_encrypted + national_id_hmac
  • password_hash column still exists but default='BANKID_ONLY' (backwards compat)
  • npx drizzle-kit generate produces valid migration
  • npx drizzle-kit push applies to local PostgreSQL without errors

Task 3: Validate database migration

• Owner: V1
• BlockedBy: 2
• Acceptance:
  • All 25 tables created in PostgreSQL
  • Schema matches database-design.md exactly
  • Indexes from indexing-strategy.md present
  • No SQLite references remain in codebase (grep -r "better-sqlite3\|sqlite" src/)
  • Docker PostgreSQL starts and accepts connections

Task 4: Redis + BullMQ infrastructure

• Owner: B3
• BlockedBy: none (parallel with Task 1)
• Description: Add Redis and BullMQ per ADR-015. Create src/lib/redis.ts (connection), src/lib/queues.ts (5 queue definitions), src/lib/workers/ (worker stubs for each queue). Add Redis to docker-compose.yml. Add SIGTERM handler per ADR-016.
• Files: src/lib/redis.ts, src/lib/queues.ts, src/lib/workers/, docker-compose.yml, src/lib/shutdown-handlers.node.ts
• Acceptance:
  • bullmq and ioredis in package.json
  • Redis service in docker-compose.yml (port 6379)
  • 5 queues defined: payment-critical, settlement, compliance, reporting, notifications
  • SIGTERM handler with 25s drain, shutdown_interrupted state
  • docker compose up starts both PostgreSQL and Redis
  • Health endpoint includes Redis connectivity check

Task 5: Validate infrastructure

• Owner: V3
• BlockedBy: 4
• Acceptance:
  • docker compose up starts app + PostgreSQL + Redis
  • Health endpoint reports all services healthy
  • BullMQ can enqueue and process a test job
  • SIGTERM handler tested (send SIGTERM, verify graceful shutdown)

Phase 2: Auth + Security (Week 2)

Task 6: BankID-only authentication

• Owner: B2
• BlockedBy: 2 (needs Drizzle schema)
• Description: Remove all email/password and phone/PIN auth paths. Keep BankID OIDC as sole auth. Remove src/app/api/auth/login/, src/app/api/auth/register/, src/app/api/auth/verify-otp/. Update src/app/api/auth/bankid/callback/route.ts to use AES-256-GCM for fødselsnummer (not SHA-256). Update session policy: 30min sliding idle, 8h absolute, 5min payment SCA. Remove bcryptjs dependency (no passwords).
• Files: src/app/api/auth/, src/lib/auth.ts, src/lib/services/auth-provider.ts, src/app/login/page.tsx, src/app/register/page.tsx
• Acceptance:
  • /api/auth/login — REMOVED
  • /api/auth/register — REMOVED
  • /api/auth/verify-otp — REMOVED
  • /api/auth/bankid — sole auth entry point
  • BankID callback stores national_id_encrypted (AES-256-GCM) + national_id_hmac (HMAC-SHA256)
  • JWT has 30min expiry, refresh token server-side
  • Login page shows only "Logg inn med BankID" button
  • Registration page redirects to BankID flow
  • bcryptjs removed from package.json
  • Zero references to password, pin, email+password in auth flows

Task 7: Validate auth + security

• Owner: V2
• BlockedBy: 6
• Acceptance:
  • No email/password/PIN auth paths reachable
  • BankID mock flow works end-to-end
  • national_id stored as AES-256-GCM encrypted (verify with DB inspection)
  • Session expiry at 30min verified
  • grep -r "SHA-256\|sha256\|national_id_hash" src/ returns zero results in auth code
  • grep -r "bcrypt\|password_hash" src/ — only legacy column definition, no active auth use

Phase 3: API Routes (Week 2-3)

Task 8: Webhook handling API (FR-076)

• Owner: B4
• BlockedBy: 2, 4 (needs Drizzle + BullMQ)
• Description: Create POST /api/webhooks/banking-partner per FR-076. HMAC-SHA256 validation, IP whitelist, idempotent processing, state machine (pending→processing→completed/failed), DLQ after 3 attempts.
• Files: src/app/api/webhooks/banking-partner/route.ts, src/lib/services/webhook-processor.ts
• Acceptance:
  • HMAC-SHA256 signature validation with 5-min timestamp check
  • webhook_events table populated on each webhook
  • Duplicate webhook_id returns existing result (idempotent)
  • Failed webhooks retry 3 times then move to webhook_dlq
  • Returns 200 within 5 seconds

Task 9: Reconciliation API (FR-073)

• Owner: B4
• BlockedBy: 2, 4
• Description: Create reconciliation job and API. BullMQ cron job at 06:00 Oslo time. Compares Drop transactions with mock banking partner data. Creates reconciliation_reports and reconciliation_discrepancies records. Admin endpoint GET /api/admin/reconciliation to view reports.
• Files: src/lib/workers/reconciliation-worker.ts, src/app/api/admin/reconciliation/route.ts
• Acceptance:
  • BullMQ cron job scheduled at 06:00 Europe/Oslo
  • Reconciliation report created with matched/discrepancy counts
  • Discrepancies categorized by type
  • Admin API returns reports with pagination

Task 10: Circuit breaker service (FR-075)

• Owner: B4
• BlockedBy: 2, 4
• Description: Create circuit breaker service per FR-075. Shared state in PostgreSQL circuit_breaker_state table. 5 instances (BankID, ZTL, FX, compliance, push). Fallback behaviors per dependency.
• Files: src/lib/services/circuit-breaker.ts, src/lib/workers/circuit-breaker-monitor.ts
• Acceptance:
  • 5 circuit breaker instances initialized on startup
  • State transitions: closed→open after 5 failures, open→half-open after 30s
  • Each external service call wrapped in circuit breaker
  • Fallback behavior per dependency (read-only mode, cached rates, etc.)

Task 11: Dispute/refund API (FR-077)

• Owner: B4
• BlockedBy: 2
• Description: Create dispute endpoints per FR-077. POST /api/transactions/:id/dispute for user submission. GET /api/admin/disputes for admin queue. State machine (submitted→acknowledged→investigating→decided→closed).
• Files: src/app/api/transactions/[id]/dispute/route.ts, src/app/api/admin/disputes/route.ts, src/lib/services/dispute.ts
• Acceptance:
  • User can submit dispute from transaction detail
  • Auto-acknowledgement (logged, notification created)
  • Admin can view/manage dispute queue
  • State machine enforces valid transitions only
  • 5-year retention with do_not_delete flag

Task 12: Validate API routes

• Owner: V4
• BlockedBy: 8, 9, 10, 11
• Acceptance:
  • All new endpoints respond correctly (mock data)
  • Webhook idempotency verified (send same webhook twice)
  • Circuit breaker state transitions verified
  • Dispute lifecycle flows correctly
  • All endpoints require auth (except webhook which uses HMAC)

Phase 4: UI Alignment (Week 3-4)

Task 13: Align existing screens with Figma Make export

• Owner: B5
• BlockedBy: 6 (needs BankID-only auth)
• Description: Compare each of the 10 existing screens against Figma Make export (mockups/figma-make-export/src/app/screens/). Update layouts, colors, typography, spacing to match. Screens: Login, Onboarding, Dashboard, SendMoney, BankAccounts, TransactionHistory, ScanQR, Profile, Notifications, MerchantDashboard. Plus 2 merchant QR screens.
• Files: All page.tsx files in src/app/
• Acceptance:
  • Each screen visually matches Figma Make export
  • Login page: BankID-only (no email/password form)
  • Dashboard: balance card, recent transactions, quick actions
  • SendMoney: multi-step flow matching Make export
  • Brand colors match Drop brand guidelines (green gradient #0B6E35→#064E25)
  • Mobile-first responsive design

Task 14: Admin portal UI (EP-09)

• Owner: B5
• BlockedBy: 8, 9, 10, 11 (needs admin APIs)
• Description: Create admin portal pages per EP-09. MFA login (mock), AML alert dashboard, STR filing, KYC review, transaction search, settlement management, report generation, audit log viewer. Route: /app/admin/.
• Files: src/app/admin/ (new directory), 8 page files
• Acceptance:
  • Admin login page with MFA (mocked)
  • AML alert queue with filter/sort/action buttons
  • STR filing form pre-filled from alert data
  • User KYC search and detail view
  • Transaction search with filters and CSV export
  • Settlement dashboard with batch status
  • Compliance report list with PDF/CSV download stubs
  • Audit log viewer with search

Task 15: Validate UI

• Owner: V5
• BlockedBy: 13, 14
• Acceptance:
  • All 10 consumer screens match Figma Make export (visual comparison)
  • Admin portal: all 8 pages render without errors
  • No broken routes (404s)
  • Mobile responsive (viewport 375px)
  • Brand colors consistent
  • No email/password UI anywhere

Phase 5: Integration + Testing (Week 4-5)

Task 16: Mock services for all external integrations

• Owner: B4
• BlockedBy: 6, 10 (needs auth + circuit breaker)
• Description: Create/update mock services for: BankID (already exists), ZTL banking partner (PISP/AISP mock), FX rate provider (mock with realistic NOK→RSD/BAM/PLN/EUR/PKR/TRY rates), compliance provider (mock PEP/sanctions screening), push notifications (mock). All mocks should be realistic and toggleable via feature flags.
• Files: src/lib/services/mock-*.ts (update existing + create new)
• Acceptance:
  • BankID mock returns valid OIDC flow
  • PISP mock returns realistic payment confirmation after delay
  • AISP mock returns balance data for linked accounts
  • FX mock returns rates for all 6 corridors
  • Compliance mock returns PEP clear/match based on test data
  • All mocks activated via MOCK_MODE=true env var

Task 17: End-to-end test suite

• Owner: B4
• BlockedBy: 16
• Description: Expand test suite (currently 2 files). Add Playwright E2E tests for critical user flows: BankID login → dashboard → send money → transaction history. Add API integration tests for webhook, reconciliation, dispute. Add unit tests for circuit breaker, idempotency logic.
• Files: tests/e2e/, tests/integration/, tests/unit/
• Acceptance:
  • E2E: Login flow → Dashboard renders
  • E2E: Send money flow (mock) completes
  • E2E: Admin portal accessible
  • Integration: Webhook processing with HMAC
  • Integration: Reconciliation job produces report
  • Unit: Circuit breaker state transitions
  • Unit: Idempotency key generation deterministic
  • All tests pass in CI (docker-compose up + test)

Task 18: Final validation

• Owner: V1 + V2 + V3 + V4 + V5 (joint)
• BlockedBy: 17
• Description: Full system validation. Start docker-compose, run all tests, verify all acceptance criteria from all tasks, check for security issues.
• Acceptance:
  • docker compose up → app healthy within 30s
  • All 25 tables present in PostgreSQL
  • BankID-only auth (no other paths)
  • All new API routes functional
  • All UI screens render correctly
  • Zero SQLite references in codebase
  • Zero SHA-256 national_id references
  • QA-19 check passes (≥17/19 for H priority)

Validation Commands

# Database
docker compose up -d
npx drizzle-kit push
psql -h localhost -U drop -d drop -c "\dt" | wc -l  # Should show 25 tables

# Auth
grep -r "better-sqlite3\|bcrypt\|password.*login\|pin.*login" src/ # Should be zero
grep -r "national_id_hash" src/ # Should be zero
curl http://localhost:3000/api/auth/login # Should 404

# Infrastructure
docker compose ps # PostgreSQL + Redis + app all healthy
curl http://localhost:3000/api/health # Should include redis: ok, db: ok

# Tests
npm test
npx playwright test

# QA Gate
node ~/system/tools/qa-19.js check <task-id>

Risk Mitigation

Summary

Approve plan? Then run /build-plan to execute.