Backend Architecture Document

Backend Architecture Document

Project: Drop Version: 0.1.0 Date: 2026-02-23 Author: Platform Architect (AI) Status: In Review Reviewers: Alem Bašić (CEO)

Document History

1. Architecture Pattern

Pattern: Modular Monolith — Next.js App Router with co-located API routes

Rationale: Drop is a two-person MVP (Alem + AI). The Next.js App Router pattern co-locates API routes (app/api/) with the frontend, enabling full-stack development in a single TypeScript codebase with zero additional runtime complexity. The src/lib/ directory provides module isolation (db, middleware, services, features) without microservice overhead. App Runner handles scaling concerns at the infrastructure level.

Pass-Through Model (Critical Architecture Constraint): Drop NEVER holds customer money. All payments are pass-through via PSD2:

• AISP (Account Information): reads bank balance from user's real bank account
• PISP (Payment Initiation): initiates transfers directly from user's bank account
• bank_accounts.balance = last AISP-read value from external bank (cached for UI display, NOT a Drop-held balance)

2. Technology Stack

3. Application Structure

src/drop-app/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── api/                # API route handlers (REST endpoints)
│   │   │   ├── auth/           # BankID OIDC + session management
│   │   │   │   ├── bankid/     # initiate + callback endpoints
│   │   │   │   ├── me/         # current user + bank accounts
│   │   │   │   ├── logout/     # session revocation
│   │   │   │   └── refresh/    # token refresh
│   │   │   ├── transactions/   # remittance, qr-payment, history, disclosure, receipt
│   │   │   ├── recipients/     # recipient CRUD
│   │   │   ├── rates/          # exchange rates (public)
│   │   │   ├── merchants/      # merchant registration + dashboard
│   │   │   ├── notifications/  # push notification management
│   │   │   ├── settings/       # user preferences
│   │   │   ├── consents/       # GDPR consent management
│   │   │   ├── complaints/     # Finansavtaleloven §3-53 complaints
│   │   │   ├── cards/          # [FUTURE] feature-flagged card management
│   │   │   ├── user/           # GDPR data export + account deletion
│   │   │   └── health/         # health check endpoint
│   │   └── (frontend pages)    # Next.js pages
│   └── lib/                    # Shared application library
│       ├── db.ts               # Database abstraction (PostgreSQL + SQLite)
│       ├── middleware.ts        # Auth, rate limiting, CSRF, session revocation
│       ├── middleware/          # Modular middleware library
│       │   ├── auth-middleware.ts  # Bearer token auth (mobile)
│       │   ├── error-handler.ts   # AppError class + error response formatting
│       │   └── validation.ts      # Input validation functions
│       ├── alerts.ts           # Slack alerting + error spike detection
│       ├── secrets.ts          # Pluggable secrets provider (env / Doppler / AWS SM)
│       ├── feature-flags.ts    # Environment-variable-based feature flags
│       ├── features.ts         # Feature tracking system (dev tool)
│       └── services/           # External service integrations
│           ├── index.ts        # Service initialization
│           ├── mock-sumsub.ts  # Sumsub KYC (production-ready)
│           ├── mock-swan.ts    # Swan Open Banking (DEPRECATED)
│           └── mock-stripe.ts  # Stripe Issuing (mock only, FUTURE)
├── tests/                      # Test suite
│   ├── setup.ts                # Vitest setup (NODE_ENV=test, in-memory DB)
│   ├── *.test.ts               # Unit + integration tests
│   └── e2e/                    # Playwright E2E tests
│       ├── user-flows.spec.ts
│       ├── full-flows.spec.ts
│       └── input-chaos.spec.ts
└── scripts/
    ├── backup.sh               # SQLite backup script
    └── qa-report.js            # QA metrics generator

4. Database Layer

4.1 Dual-Database Architecture

Drop auto-detects the database driver at startup:

• DATABASE_URL set → PostgreSQL (pg driver)
• DATABASE_URL not set → SQLite (better-sqlite3)

Source: src/lib/db.ts

4.2 Key Database Tables

4.3 Data Auto-Detection (db.ts)

// Auto-detects driver based on DATABASE_URL env var
const driver = process.env.DATABASE_URL ? 'pg' : 'sqlite';

5. Authentication Architecture

5.1 BankID OIDC Flow (Primary Auth)

Auth method: Norwegian BankID — mandatory for all users. Email/password auth deprecated (returns 410 Gone).

Token: JWT (HS256), stored in drop_token httpOnly cookie (web) or Authorization Bearer header (mobile).

Token lifetime: 24h (web), 7d (mobile)

BankID Web Flow:

1. GET /api/auth/bankid → generate state + nonce, set bankid_state cookie, return redirect URL
2. User authenticates with BankID at provider
3. GET /api/auth/bankid/callback?code=&state= → verify state, exchange code for tokens, verify JWKS signature, parse pid, hash pid → SHA-256, find/create user, issue JWT cookie

User creation on first BankID login:

• Parse pid (Norwegian national ID, 11 digits) from ID token
• Hash pid with SHA-256 → national_id_hash column
• KYC status automatically approved (BankID = verified identity)
• Password set to sentinel 'EIDONLY' — no password login possible

Age verification: pid encodes date of birth — must be >= 18 years old.

5.2 Session Management

Login  → Create session record (SHA-256 of JWT) in sessions table
Request → requireAuth() checks: cookie present + JWT valid + session not revoked
Logout → revokeAllSessions(userId) — sets revoked=1 on all user sessions

5.3 CSRF Protection

• Web: State parameter in BankID OIDC flow (httpOnly cookie)
• API: Origin header validation in requireAuth() against allowed origins
• Mobile: N/A (Bearer token, no cookies)

6. Middleware Stack

7. API Design Principles

1. Consistent response envelope:

   • Success: { "data": { ... } } or { "data": [...], "pagination": { ... } }
   • Error: { "error": "code", "message": "...", "details": [...] }

2. No wallet model: Drop never holds funds. bank_accounts.balance is AISP-read cache only.

3. KYC gate: Remittance requires kyc_status === 'approved' — enforced in route handler.

4. Atomic transactions: Balance deduction and transaction creation in a single DB transaction.

5. Data masking: Bank account numbers masked in responses (*****5678), card numbers PCI-masked.

6. GDPR by design: Data export, account deletion (soft delete), consent records all implemented.

7. Compliance-first: STR reports, AML alerts, audit log, complaint system (Finansavtaleloven §3-53), PITR retention (5 years per hvitvaskingsloven).

8. Security Architecture

9. External Service Integrations

10. Related Documents

• API Reference
• Middleware Design
• Service Design
• External Services Integration
• Deployment Architecture
• Authentication Source

Approval