Backend Architecture
Backend Architecture Document
Project:
{{PROJECT_NAME}}Drop Version:{{VERSION}}0.1.0 Date:{{DATE}}2026-02-23 Author:{{AUTHOR}}Platform Architect (AI) Status:Draft |In Review| ApprovedReviewers:{{REVIEWERS}}Alem Bašić (CEO)
Document History
| Version | Date | Author | Changes |
|---|---|---|---|
| 0.1 | Initial draft from source code analysis |
1. Architecture Pattern
Pattern: {{Modular Monolith |— MicroservicesNext.js |App MonolithRouter |with Event-Drivenco-located Microservices}}
| Pattern Considered | Pros | Cons | Decision |
|---|---|---|---|
| Monolith (Next.js all-in-one) | Simple deploy, |
Scaling bottleneck, |
|
| Modular Monolith | |
||
| Microservices | Independent |
Operational |
|
Rationale:
Drop
TODO:is3-5asentencestwo-personexplainingMVP (Alem + AI). The Next.js App Router pattern co-locates API routes (app/api/) with thedecisionfrontend,consideringenablingteamfull-stacksize,developmentscaleinrequirements,aandsingleoperationalTypeScriptmaturity.codebase with zero additional runtime complexity. Thesrc/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
| Layer | Technology | Version | Notes | ||
|---|---|---|---|---|---|
| Runtime | |
|
LTS, Dockerfile base image | ||
| Framework | |
|
Standalone output for Docker | ||
| Frontend | React | 19.2.3 | |||
|
|
Strict mode | |||
PostgreSQL (via pg) |
16 (RDS) | | pg | |
|
SQLite (via |
|
| |||
| | ||||
| | ||||
| |||||
| Auth | |
^6.1.3 | HS256, httpOnly cookie | ||
| Password hashing | bcryptjs | ^3.0.3 | Legacy — BankID replaces email/password | ||
| Identity (eID) | BankID OIDC | Norwegian eID | Mandatory for all users | ||
| KYC | Sumsub WebSDK + API | Production-ready | Only connected external service | ||
| Open Banking | TBD (Swan deprecated) | — | AISP/PISP provider selection pending | ||
| Styling | Tailwind CSS | ^4 | |||
|
|
|
|||
|
^0.563.0 | ||||
|
|
Dark/light mode | |||
| Toasts | Sonner | ^2.0.7 | |||
| Testing (unit) | Vitest | ^4.0.18 | |||
| Testing (E2E) | Playwright | ^1.58.2 | |||
| Linting | ESLint | ^9 |
3. ProjectApplication Structure
src/drop-app/
├── modules/ # Feature modules (NestJS) / route handlers (Express)src/
│ ├── users/app/ # Next.js App Router
│ │ ├── users.module.tsapi/ │# │API ├──route users.controller.tshandlers │(REST │ ├── users.service.ts
│ │ ├── users.repository.ts
│ │ ├── dto/endpoints)
│ │ │ ├── create-user.dto.tsauth/ # BankID OIDC + session management
│ │ │ │ ├── bankid/ # initiate + callback endpoints
│ │ │ │ ├── me/ # current user + bank accounts
│ │ │ │ ├── logout/ # session revocation
│ │ │ │ └── update-user.dto.tsrefresh/ # 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
│ │ │ └── entities/health/ # health check endpoint
│ │ └── user.entity.(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
│ ├── auth/
│ ├── notifications/
│ └── {{FEATURE}}/
├── common/
│ ├── decorators/ # Custom decorators
│ ├── filters/ # Exception filters
│ ├── guards/ # Auth / role guards
│ ├── interceptors/ # Logging, transform interceptors
│ ├── pipes/ # Validation pipes
│ └── middleware/ # Request middleware
├── database/
│ ├── migrations/
│ └── seeds/
├── config/
│ ├── app.config.ts
│ ├── database.config.full-flows.spec.ts
│ └── redis.config.input-chaos.spec.ts
└── scripts/
├── jobs/backup.sh # BackgroundSQLite jobbackup definitionsscript
└── main.tsqa-report.js # ApplicationQA entrymetrics point
test/
├── unit/
├── integration/
└── e2e/generator
4. RequestDatabase Processing PipelineLayer
4.1 Dual-Database Architecture
Drop auto-detects the database driver at startup:
sequenceDiagramDATABASE_URLparticipantsetClient→participantPostgreSQLGateway(pgasdriver)DATABASE_URLGatewaynot/setLB→participantSQLiteMiddleware(better-sqlite3)
Source: Stacksrc/lib/db.ts
4.2 Guard as Guards
participant Pipe as Validation Pipe
participant Controller
participant Service
participant Repository
participant DB asKey Database Client->>Gateway: HTTP Request
Gateway->>Middleware: Forward (with tracing headers)
Middleware->>Middleware: Request ID, CORS, Security Headers, Rate Limit
Middleware->>Guard: Authenticated request
Guard->>Guard: JWT verification, Role check
Guard->>Pipe: Authorized request
Pipe->>Pipe: Schema validation (Zod/class-validator)
Pipe->>Controller: Validated DTO
Controller->>Service: Business method call
Service->>Repository: Data access call
Repository->>DB: Query
DB-->>Repository: Result
Repository-->>Service: Domain entity
Service-->>Controller: Response data
Controller-->>Client: HTTP Response (transformed)
5. Middleware Stack Configuration
Execution order (applied left-to-right):
| Purpose | ||||
|---|---|---|---|---|
users |
User accounts, KYC status, BankID linkage | | : national_id_hash: | BankID |
|
revoked flag |
|||
bank_accounts |
Linked bank accounts (AISP data) | | | = |
transactions |
All payments (remittance + QR) | | : status: | |
|
||||
merchants |
Merchant profiles, QR data | |
||
notifications |
User notifications | Feature-flagged | ||
rate_limits |
IP-based rate limiting ( |
key: IP address, window-based counter |
||
audit_log |
Security + compliance audit trail | | , resource_type, resource_id, | details |
aml_alerts |
status: |
Security headers configured via Helmet:
app.use(helmet({
contentSecurityPolicy: { /* ... */ },
hsts: { maxAge: 31536000, includeSubDomains: true, preload: true },
referrerPolicy: { policy: 'same-origin' },
}));
6. Authentication & Authorization Flow
flowchart TD
Login["POST /auth/login\n{email, password}"] --> ValidateCreds["Validate credentials\n(bcrypt compare)"]
ValidateCreds -->|Invalid| Reject["401 Unauthorized"]
ValidateCreds -->|Valid| IssuePair["Issue token pair\naccess (15m) + refresh (30d)"]
IssuePair --> StoreRefresh["Store refresh token\n(hashed, Redis or DB)"]
IssuePair --> ReturnTokens["Return tokens to client"]
AuthReq["Authenticated Request"] --> ExtractJWT["Extract Bearer token"]
ExtractJWT --> VerifyJWT["Verify signature + expiry"]
VerifyJWT -->|Invalid/Expired| RefreshFlow["POST /auth/refresh"]
VerifyJWT -->|Valid| CheckRoles["Role/permission check"]
CheckRoles -->|Unauthorized| Forbidden["403 Forbidden"]
CheckRoles -->|Authorized| Handler["Route Handler"]
RefreshFlow --> VerifyRefresh["Verify refresh token\n(hash match, not revoked)"]
VerifyRefresh -->|Invalid| Logout["Force logout → 401"]
VerifyRefresh -->|Valid| RotateToken["Rotate tokens\n(old token revoked)"]
RBAC / ABAC:
Roles:{{admin | manager | user | viewer}}Permissions:{{resource:action}}e.g.users:deleteRole-permission mapping:{{database table | config file | code}}
7. Database Access Patterns
Pattern: {{Repository Pattern}}
// Repository interface — decouples business logic from storage
interface UserRepository {
findById(id: string): Promise<User | null>;
findByEmail(email: string): Promise<User | null>;
findMany(filters: UserFilters): Promise<PaginatedResult<User>>;
create(data: CreateUserData): Promise<User>;
update(id: string, data: UpdateUserData): Promise<User>;
delete(id: string): Promise<void>;
}
Query performance rules:
All queries accessing > 1000 rows must have paginatorAll filterable fields must have DB indexes (document in migration)N+1 queries forbidden — useinclude/JOIN ordataloaderpatternRaw SQL allowed only when ORM cannot express the query efficiently
8. Caching Architecture
graph LR
Request --> L1["L1: In-Memory\n(node-cache)"]
L1 -->|Cache miss| L2["L2: Redis\n(shared, distributed)"]
L2 -->|Cache miss| DB["Database"]
DB --> L2
L2 --> L1
L1 --> Response
str_reports |
Suspicious | Filed with Finanstilsynet | ||||
consents |
GDPR consent records | |
||||
data_access_requests |
type: export/erasure |
|||||
complaints |
User complaints (Finansavtaleloven §3-53) | 15-business-day response SLA | ||||
exchange_rates |
NOK → destination currency rates | Updated externally | ||||
feature_flags |
Runtime feature flag overrides | Complement to env-var flags | ||||
cards |
||||||
Cache-aside4.3
patternData Auto-Detection (L2):
async// functionAuto-detects getCachedUser(id:driver string):based Promise<User>on {DATABASE_URL env var
const cacheKeydriver = `user:${id}`process.env.DATABASE_URL ? 'pg' : 'sqlite';
const cached = await redis.get(cacheKey);
if (cached) return JSON.parse(cached);
const user = await userRepository.findById(id);
await redis.setex(cacheKey, 300, JSON.stringify(user)); // 5 min TTL
return user;
}
5. Authentication Architecture
5.1 BankID OIDC Flow (Primary Auth)
CacheAuth invalidationmethod: strategy: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:
GET /api/auth/bankid→ generate state + nonce, setbankid_statecookie, return redirect URL- User authenticates with BankID at provider
GET /api/auth/bankid/callback?code=&state=→ verify state, exchange code for tokens, verify JWKS signature, parsepid, hash pid → SHA-256, find/create user, issue JWT cookie
User creation on first BankID login:
OnParseupdate/delete:pidawait(Norwegianredis.del(cacheKey)Pattern-based:Hash pid with SHA-256 →awaitnational_id_hashredis.del(column- KYC status automatically
approved(BankID = verified identity) - Password set to sentinel
'— no password login possibleuser:*'EIDONLY'
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()(useagainstsparinglyallowed— expensive)origins Tag-based:Mobile:{{ioredis-tagN/A|(Bearercustomtoken,tagging}}
9.6. BackgroundMiddleware Job ProcessingStack
Library: {{BullMQ | Agenda | pg-boss}}
Queue storage: {{Redis | PostgreSQL}}
|
|||
|
requireAuth() role === 'merchant') |
||
|
rate_limits DB table, 60s window |
||
|
x-forwarded-for |
||
jsonError() |
All routes | ||
featureGate(flag) |
Returns 404 if feature flag disabled | Cards, spending limits, notifications | |
| Input validation | validateEmail, validatePhone, validateAmount, validateName, sanitizeText, etc. |
All mutation endpoints | |
| Error handler | AppError class with predefined constructors |
All routes via createErrorResponse() |
7. API Design Principles
-
JobConsistentschema:response envelope:- Success:
interface{EmailJob"data": {type: 'welcome' | 'password_reset' | 'notification'; to: string; templateId: string; data: Record<string, unknown>;... } }{ "data": [...], "pagination": { ... } } - Error:
{ "error": "code", "message": "...", "details": [...] }
- Success:
-
Monitoring:No wallet model: Drop never holds funds.{{Bullbank_accounts.balanceBoardis|AISP-readBullMQcacheMetricsonly.API}} -
KYC gate: Remittance requires
kyc_status === 'approved'—adminenforcedUIinatroute handler. -
Atomic transactions: Balance deduction and transaction creation in a single DB transaction.
-
Data masking: Bank account numbers masked in responses (
{{/admin/queues}}*****5678 -
GDPR by design: Data export, account deletion (soft delete), consent records all implemented.
-
Compliance-first: STR reports, AML alerts, audit log, complaint system (Finansavtaleloven §3-53), PITR retention (5 years per hvitvaskingsloven).
10.8. FileSecurity Storage & Media HandlingArchitecture
Storage provider: {{AWS S3 | Cloudflare R2 | MinIO}}
Bucket naming: {{company-project-env}} (e.g., alai-app-production)
Upload flow:
Client requests pre-signed URL from API (POST /uploads/presigned)API validates file type, size, generates pre-signed URL (expiry: 15 min)Client uploads directly to storage (bypasses API server)Client notifies API of upload completion (POST /uploads/confirm)API validates file exists, creates database record, triggers processing job
File size limits:
| Input validation | Custom validators (no external dep) — email, phone, amount, IBAN, name (XSS-resistant) |
| SQL injection | Parameterized queries via pg / better-sqlite3 |
| XSS | CSP headers (strict production — no unsafe-eval) + HTML sanitization in sanitizeText() |
| CSRF | Origin header validation + BankID state parameter |
| Secrets | AWS Secrets Manager / Fly.io secrets — never in code or .env |
| Error masking | createErrorResponse() masks internal errors in production |
| Password hashing | bcryptjs (legacy users) |
| Card data | PCI-masked (never expose full card number or CVV) |
| Audit trail | audit_log table — all sensitive actions logged |
| AML | aml_alerts + str_reports tables — compliance framework |
11.9. LoggingExternal &Service ObservabilityIntegrations
Logger: {{Pino}} — structured JSON logs
Log aggregation: {{Datadog / Loki / CloudWatch}}
Log levels policy:
| Purpose | ||
|---|---|---|
|
KYC/identity verification — WebSDK + webhook | |
|
Norwegian |
|
|
Bank |
|
|
Was |
|
|
Card issuance — |
|
| Slack | PRODUCTION | Operational alerting via webhook |
| BetterStack | PRODUCTION | External uptime monitoring |
Always
log:
10. Related Documents
Request:APImethod, path, request ID, user ID (hashed), status code, durationReferenceErrors:Middlewarefull stack trace, request contextDesignBackgroundServicejobs:Design- External
ID,Servicesqueue,Integration - Deployment
duration,Architecture - Authentication Source
Never log:
Passwords, tokens, API keysFull request/response bodies with PIIPayment card data
12. Configuration Management
Pattern: Typed config module with validation on startup
// config/app.config.ts
const schema = z.object({
NODE_ENV: z.enum(['development', 'staging', 'production']),
PORT: z.coerce.number().default(4000),
DATABASE_URL: z.string().url(),
REDIS_URL: z.string().url(),
JWT_SECRET: z.string().min(32),
// ...
});
export const config = schema.parse(process.env);
// App fails FAST at startup if any required variable is missing/invalid
Secrets management: {{HashiCorp Vault | AWS Secrets Manager | Doppler}}
NO secrets in environment files committed to git.
13. Health Check Endpoints
| ||
| ||
|
Readiness check response:
{
"status": "ok",
"checks": {
"database": { "status": "ok", "latency": 3 },
"redis": { "status": "ok", "latency": 1 },
"queue": { "status": "ok", "pendingJobs": 12 }
},
"version": "1.2.3",
"uptime": 3600
}
14. Architecture Diagram
graph TB
subgraph "Clients"
Web["Web App"]
Mobile["Mobile App"]
end
subgraph "Infrastructure"
LB["Load Balancer\n(Nginx / ALB)"]
API["API Server\n({{FRAMEWORK}})"]
Workers["Background Workers\n(BullMQ)"]
end
subgraph "Data"
DB["PostgreSQL\n(Primary + Replicas)"]
Cache["Redis\n(Cache + Queue)"]
Storage["Object Storage\n(S3 / R2)"]
end
subgraph "Observability"
Logs["Log Aggregation\n(Datadog / Loki)"]
APM["APM / Tracing"]
end
Web --> LB
Mobile --> LB
LB --> API
API --> DB
API --> Cache
API --> Storage
API --> Cache
Workers --> Cache
Workers --> DB
API --> Logs
Workers --> Logs
API --> APM
Approval
| Role | Name | Date | Signature |
|---|---|---|---|
| Author | Platform Architect (AI) | 2026-02-23 | |
| Alem | |||
| Bašić |