# 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)](hld/system-context.md) -- Drop and all external actors (banks, BankID, regulators)
2. [Security Architecture](hld/security-architecture.md) -- Security controls and threat model
3. [ADR-003: PSD2 Pass-through Model](adr/ADR-003-psd2-pass-through.md) -- Why Drop never holds money

### Architect Track

For a complete understanding of system design and key decisions.

1. **High-Level Design (C4)**
   - [System Context (C4 Level 1)](hld/system-context.md) -- External actors and trust boundaries
   - [Container Diagram (C4 Level 2)](hld/container-diagram.md) -- Internal containers and data flow
   - [Component Overview (C4 Level 3)](hld/component-overview.md) -- Module-level breakdown
2. **Cross-Cutting Concerns**
   - [Security Architecture](hld/security-architecture.md) -- Auth, encryption, input validation
   - [Data Architecture](hld/data-architecture.md) -- Data flow, storage, and processing
   - [Deployment Architecture](hld/deployment-architecture.md) -- AWS App Runner, Cloudflare, CI/CD
3. **Architecture Decision Records**
   - [ADR Index](adr/README.md) -- All 12 ADRs with template
4. **Integration Specifications**
   - [Open Banking AISP/PISP](integration/open-banking-aisp-pisp.md) -- PSD2 banking integration
   - [BankID OIDC Integration](integration/bankid-oidc-integration.md) -- Norwegian eID authentication
   - [Sumsub KYC Integration](integration/sumsub-kyc-integration.md) -- Identity verification
   - [Payment Processing](integration/payment-processing.md) -- Remittance and QR payment flows
   - [Sentry Observability](integration/sentry-observability.md) -- Error tracking and monitoring

### Developer Track

For implementing features and understanding code flows.

1. **Low-Level Designs (User Flows)**
   - [Login Authentication](lld/flow-login-authentication.md) -- BankID login flow (frontend)
   - [Login Authentication Backend](lld/flow-login-authentication-backend.md) -- Auth backend implementation
   - [Registration & Onboarding](lld/flow-registration-onboarding.md) -- New user registration
   - [Bank Account Linking](lld/flow-bank-account-linking.md) -- AISP consent and account linking
   - [Remittance](lld/flow-remittance.md) -- International money transfer flow
   - [QR Payment](lld/flow-qr-payment.md) -- Merchant QR payment flow
   - [Transaction History](lld/flow-transaction-history.md) -- Transaction listing and filtering
   - [Merchant Onboarding](lld/flow-merchant-onboarding.md) -- Business registration flow
   - [Profile & Settings](lld/flow-profile-settings.md) -- User preferences management
   - [Notifications](lld/flow-notifications.md) -- Push notification flow
2. **Database**
   - [Database Design](database/database-design.md) -- Schema rationale and entity relationships
   - [Migration Strategy](database/migration-strategy.md) -- SQLite to PostgreSQL migration
   - [Data Lifecycle](database/data-lifecycle.md) -- Retention, archival, and deletion policies
   - [Audit Architecture](database/audit-architecture.md) -- Compliance audit trail design
   - [Indexing Strategy](database/indexing-strategy.md) -- Database performance optimization
3. **Key ADRs for Developers**
   - [ADR-004: JWT httpOnly Cookies](adr/ADR-004-jwt-httponly-cookies.md) -- Token storage security
   - [ADR-006: SQLite to PostgreSQL](adr/ADR-006-sqlite-to-postgresql.md) -- **SUPERSEDED** by ADR-014
   - [ADR-008: Hono API Framework](adr/ADR-008-hono-api-framework.md) -- Mobile API choice
   - [ADR-009: Feature Flag System](adr/ADR-009-feature-flag-system.md) -- Runtime feature toggles
   - [ADR-010: Dual Database Driver](adr/ADR-010-dual-database-driver.md) -- **SUPERSEDED** by ADR-014
   - [ADR-014: PostgreSQL-Only Architecture](adr/ADR-014-postgresql-only.md) -- PostgreSQL 16 + Drizzle ORM (all environments)

### Compliance Track

For regulatory compliance review and audit preparation.

1. [Security Architecture](hld/security-architecture.md) -- Authentication, authorization, data protection
2. [KYC/AML Flow](lld/flow-kyc-aml.md) -- Customer due diligence, transaction monitoring, STR filing
3. [Data Lifecycle](database/data-lifecycle.md) -- GDPR retention policies, right to erasure
4. [Audit Architecture](database/audit-architecture.md) -- Audit trail for regulatory reporting
5. [Registration & Onboarding](lld/flow-registration-onboarding.md) -- Consent collection, age verification
6. [ADR-003: PSD2 Pass-through](adr/ADR-003-psd2-pass-through.md) -- Regulatory model decision
7. [ADR-007: BankID OIDC Auth](adr/ADR-007-bankid-oidc-auth.md) -- SCA compliance

---

## Document Index

### High-Level Design (HLD)

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

### Architecture Decision Records (ADR)

| ADR | Title | Category | Status |
|-----|-------|----------|--------|
| [ADR-001](adr/ADR-001-consolidate-backends.md) | Consolidate to Single Backend | Architecture | Accepted |
| [ADR-002](adr/ADR-002-separate-fontelepay.md) | Separate FontelePay from Drop | Architecture | Accepted |
| [ADR-003](adr/ADR-003-psd2-pass-through.md) | PSD2 Pass-through Model (No Wallet) | Architecture | Accepted |
| [ADR-004](adr/ADR-004-jwt-httponly-cookies.md) | JWT in httpOnly Cookies | Security | Accepted |
| [ADR-005](adr/ADR-005-monolith-first.md) | Monolith-First Architecture | Architecture | Accepted |
| [ADR-006](adr/ADR-006-sqlite-to-postgresql.md) | SQLite Dev, PostgreSQL Prod | Database | Superseded by ADR-014 |
| [ADR-007](adr/ADR-007-bankid-oidc-auth.md) | BankID as Sole Auth Provider | Security | Accepted |
| [ADR-008](adr/ADR-008-hono-api-framework.md) | Hono v4 for Mobile API | Backend | Accepted |
| [ADR-009](adr/ADR-009-feature-flag-system.md) | Custom Feature Flag System | Backend | Accepted |
| [ADR-010](adr/ADR-010-dual-database-driver.md) | Dual Database Driver Abstraction | Database | Superseded by ADR-014 |
| [ADR-011](adr/ADR-011-expo-mobile-framework.md) | Expo SDK 54 for Mobile | Mobile | Accepted |
| [ADR-012](adr/ADR-012-aws-app-runner-deploy.md) | AWS App Runner Deployment | Infrastructure | Accepted |
| [ADR-014](adr/ADR-014-postgresql-only.md) | PostgreSQL-Only Architecture (Drizzle ORM) | Database | Accepted |

### Integration Specifications

| Document | Description | External System |
|----------|-------------|-----------------|
| [Open Banking AISP/PISP](integration/open-banking-aisp-pisp.md) | PSD2 account access and payment initiation | Nordic banks (DNB, SpareBank1, Nordea) |
| [BankID OIDC Integration](integration/bankid-oidc-integration.md) | Norwegian eID authentication and SCA | BankID Norge |
| [Sumsub KYC Integration](integration/sumsub-kyc-integration.md) | Document verification and screening | Sumsub |
| [Payment Processing](integration/payment-processing.md) | Remittance and QR payment orchestration | Banks, SEPA, SWIFT |
| [Sentry Observability](integration/sentry-observability.md) | Error tracking and performance monitoring | Sentry |

### Low-Level Design (LLD) -- User Flows

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

### Database Architecture

| Document | Description |
|----------|-------------|
| [Database Design](database/database-design.md) | Schema rationale, entity relationships, 19-table overview |
| [Migration Strategy](database/migration-strategy.md) | Historical SQLite to PostgreSQL migration record (completed; see ADR-014) |
| [Data Lifecycle](database/data-lifecycle.md) | GDPR retention, AML record keeping, deletion policies |
| [Audit Architecture](database/audit-architecture.md) | `audit_log` table design and compliance trail |
| [Indexing Strategy](database/indexing-strategy.md) | Performance indexes for queries, compliance, and reporting |

---

## Related Documentation

| Document | Location | Description |
|----------|----------|-------------|
| [Main Architecture Document](../../project/architecture/architecture-document.md) | `project/architecture/` | Original architecture overview (v1.1) |
| [API Reference](../backend/API-REFERENCE.md) | `docs/backend/` | All 24+ API endpoints |
| [Database Schema](../backend/DATABASE-SCHEMA.md) | `docs/backend/` | Full table definitions |
| [Authentication System](../backend/AUTHENTICATION.md) | `docs/backend/` | BankID OIDC implementation |
| [Middleware](../backend/MIDDLEWARE.md) | `docs/backend/` | Auth, rate limiting, validation |
| [Feature Flags](../backend/FEATURE-FLAGS.md) | `docs/backend/` | Runtime feature toggles |
| [Security Architecture](../security/SECURITY-ARCHITECTURE.md) | `docs/security/` | Security controls reference |
| [Compliance Status](../security/COMPLIANCE.md) | `docs/security/` | Regulatory compliance tracking |
| [Roadmap](../../ROADMAP.md) | 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.