Skip to main content

Architecture Overview

Drop Architecture Documentation

Project: Drop -- Fintech Payment App (Remittance + QR Payments) Model: PSD2 Pass-through (AISP + PISP) -- Drop never holds customer funds Last updated: 2026-02-21

Reading Guides by Audience

Executive Summary

Start here for a high-level understanding of Drop's architecture and regulatory position.

  1. System Context (C4 Level 1) -- Drop and all external actors (banks, BankID, regulators)
  2. Security Architecture -- Security controls and threat model
  3. ADR-003: PSD2 Pass-through Model -- Why Drop never holds money

Architect Track

For a complete understanding of system design and key decisions.

  1. High-Level Design (C4)
  2. Cross-Cutting Concerns
  3. Architecture Decision Records
  4. Integration Specifications

Developer Track

For implementing features and understanding code flows.

  1. Low-Level Designs (User Flows)
  2. Database
  3. Key ADRs for Developers

Compliance Track

For regulatory compliance review and audit preparation.

  1. Security Architecture -- Authentication, authorization, data protection
  2. KYC/AML Flow -- Customer due diligence, transaction monitoring, STR filing
  3. Data Lifecycle -- GDPR retention policies, right to erasure
  4. Audit Architecture -- Audit trail for regulatory reporting
  5. Registration & Onboarding -- Consent collection, age verification
  6. ADR-003: PSD2 Pass-through -- Regulatory model decision
  7. ADR-007: BankID OIDC Auth -- SCA compliance

Document Index

High-Level Design (HLD)

Document Description Key Diagrams
System Context (C4 L1) Drop and all external actors, trust boundaries, compliance zones C4 context diagram, trust boundary diagram
Container Diagram (C4 L2) Internal containers: Next.js BFF, Hono API, databases, edge C4 container diagram, data flow diagram
Component Overview (C4 L3) Module-level breakdown: auth, transactions, merchants, compliance Component diagrams per module
Security Architecture Auth, encryption, input validation, rate limiting, headers Security layer diagram, threat model
Data Architecture Data flow, storage tiers, processing pipeline Data flow diagram, storage topology
Deployment Architecture AWS App Runner, Cloudflare, CI/CD pipeline, environments Deployment topology, CI/CD pipeline

Architecture Decision Records (ADR)

Two-Backend Convergence: Drop currently runs two backend surfaces — drop-api (Express/Hono, port 3001) and drop-app Next.js API routes (port 3000). See ADR-002: Two-Backend Convergence Plan for role audit, current topology, and the recommended convergence path.

ADR Title Category Status
ADR-001 Consolidate to Single Backend Architecture Accepted
ADR-002 Separate FontelePay from Drop Architecture Accepted
ADR-003 PSD2 Pass-through Model (No Wallet) Architecture Accepted
ADR-004 JWT in httpOnly Cookies Security Accepted
ADR-005 Monolith-First Architecture Architecture Accepted
ADR-006 SQLite Dev, PostgreSQL Prod Database Superseded by ADR-014
ADR-007 BankID as Sole Auth Provider Security Accepted
ADR-008 Hono v4 for Mobile API Backend Accepted
ADR-009 Custom Feature Flag System Backend Accepted
ADR-010 Dual Database Driver Abstraction Database Superseded by ADR-014
ADR-011 Expo SDK 54 for Mobile Mobile Accepted
ADR-012 AWS App Runner Deployment Infrastructure Accepted
ADR-013Settlement Model — Split Payment (Pass-through)ArchitectureAccepted
ADR-014 PostgreSQL-Only Architecture (Drizzle ORM) Database Accepted
ADR-015BullMQ + Redis for Background Job ProcessingInfrastructureAccepted
ADR-016Graceful Shutdown for App RunnerInfrastructureAccepted
ADR-017PSD2 SCA Payment Session SeparationSecurityProposed

Integration Specifications

Document Description External System
Open Banking AISP/PISP PSD2 account access and payment initiation Nordic banks (DNB, SpareBank1, Nordea)
BankID OIDC Integration Norwegian eID authentication and SCA BankID Norge
Sumsub KYC Integration Document verification and screening Sumsub
Payment Processing Remittance and QR payment orchestration Banks, SEPA, SWIFT
Sentry Observability Error tracking and performance monitoring Sentry

Low-Level Design (LLD) -- User Flows

Document Description Key Endpoints
Login Authentication BankID OIDC login (frontend) /api/auth/bankid, /api/auth/bankid/callback
Login Auth Backend Auth backend: JWT, sessions, revocation lib/auth.ts, middleware/auth.ts, middleware/rate-limit.ts
Registration & Onboarding New user registration, consent, bank linking /api/auth/bankid, /api/consents
Bank Account Linking AISP consent and account sync Open Banking AISP APIs
Remittance International money transfer POST /api/transactions/remittance
QR Payment Merchant QR scan and pay POST /api/transactions/qr-payment
Transaction History Transaction listing with filters GET /api/transactions
KYC/AML KYC verification and AML monitoring Sumsub webhooks, aml_alerts, str_reports
Merchant Onboarding Business registration and QR setup POST /api/merchants/register
Profile & Settings User preferences and account management GET/PATCH /api/settings
Notifications Push notification delivery GET/PATCH /api/notifications

Database Architecture

Document Description
Database Design Schema rationale, entity relationships, 19-table overview
Migration Strategy Historical SQLite to PostgreSQL migration record (completed; see ADR-014)
Data Lifecycle GDPR retention, AML record keeping, deletion policies
Audit Architecture audit_log table design and compliance trail
Indexing Strategy Performance indexes for queries, compliance, and reporting
Document Location Description
Main Architecture Document project/architecture/ Original architecture overview (v1.1)
API Reference docs/backend/ All 24+ API endpoints
Database Schema docs/backend/ Full table definitions
Authentication System docs/backend/ BankID OIDC implementation
Middleware docs/backend/ Auth, rate limiting, validation
Feature Flags docs/backend/ Runtime feature toggles
Security Architecture docs/security/ Security controls reference
Compliance Status docs/security/ Regulatory compliance tracking
Roadmap Root Product roadmap and phases

Architecture Principles

  1. Pass-through model: Drop never holds customer funds. All payments initiated via PISP from user's bank.
  2. Security-first: httpOnly cookies, parameterized SQL, BankID SCA, rate limiting on all public endpoints.
  3. Compliance by design: Audit logging, consent tracking, AML monitoring built into the data model.
  4. Monolith-first: Simple deployment, extract services only when scaling demands it.
  5. PostgreSQL-only: PostgreSQL 16 in all environments (dev, CI, staging, production) via Drizzle ORM. See ADR-014.
  6. Feature-flagged: Unreleased features (cards) safely gated; critical features can be killed instantly.
Back to top