Coding Standards: Drop — Fintech Payment App

Project: Drop — Remittance + QR Payments Version: 1.0 Date: 2026-02-23 Author: John (AI Director) Status: Approved Reviewers: Alem Bašić (CEO)

Document History

Version	Date	Author	Changes
0.1	2026-02-23	John	Initial standards — TypeScript strict, Next.js App Router, fintech security rules

Purpose

These standards apply to all code in Drop. When automated tools enforce a rule, the tool wins. When in doubt, optimize for readability — the next AI agent reading your code is trying to understand intent, not guess it.

Non-negotiable: All new code must pass TypeScript strict check, ESLint, and Prettier formatting before merge. No exceptions.

Fintech non-negotiable: Parameterized SQL everywhere. No stored balances. No stored card numbers or CVV. These are encoded as automated tests — failing these means P0.

1. Language-Specific Conventions

1.1 Naming Conventions

TypeScript (Drop's primary language):

Type	Convention	Example
Variables	`camelCase`	`userId`, `kycStatus`
Functions	`camelCase`	`hashPassword()`, `calculateFee()`
Classes	`PascalCase`	`TransactionService`
Interfaces	`PascalCase` (no `I` prefix)	`User`, `TransactionResult`
Types	`PascalCase`	`KycStatus`, `CurrencyCode`
Enums	`PascalCase`	`TransactionType`, `KycStatus`
Constants	`UPPER_SNAKE_CASE`	`REMITTANCE_FEE_RATE`, `MIN_AMOUNT_NOK`
Files — components	`PascalCase.tsx`	`SendMoneyForm.tsx`
Files — utilities	`camelCase.ts`	`calculateFee.ts`, `verifyJWT.ts`
Files — API routes	`route.ts` (Next.js convention)	`app/api/auth/login/route.ts`
Test files	`{name}.test.ts`	`auth.test.ts`, `db.test.ts`
E2E test files	`{name}.spec.ts`	`user-flows.spec.ts`

Drop-specific constants:

// Fee rates (business rules — change requires CEO approval + ADR)
const REMITTANCE_FEE_RATE = 0.005;  // 0.5%
const QR_MERCHANT_FEE_RATE = 0.01;  // 1%
const MIN_REMITTANCE_NOK = 100;
const MAX_REMITTANCE_NOK = 50_000;

// Supported corridors
const SUPPORTED_CURRENCIES = ['RSD', 'BAM', 'PKR', 'TRY', 'PLN', 'EUR'] as const;
type CurrencyCode = typeof SUPPORTED_CURRENCIES[number];

1.2 File Organization

src/drop-app/src/
├── app/
│   ├── api/                  # Next.js API Routes
│   │   ├── auth/
│   │   │   ├── login/route.ts
│   │   │   ├── register/route.ts
│   │   │   └── me/route.ts
│   │   ├── transactions/
│   │   │   ├── remittance/route.ts
│   │   │   └── qr-payment/route.ts
│   │   └── rates/
│   │       ├── route.ts           # GET /api/rates
│   │       └── [currency]/route.ts # GET /api/rates/RSD
│   └── (app)/               # Protected pages (dashboard, send-money, etc.)
├── lib/
│   ├── auth.ts              # JWT, bcrypt, session helpers
│   ├── db.ts                # SQLite/PostgreSQL client
│   ├── validate.ts          # Zod schemas for input validation
│   └── fee.ts               # Fee calculation functions
└── components/
    ├── drop-logo.tsx        # Brand logo component
    └── ui/                  # Shared UI components

Rules:

One route handler per file (route.ts in Next.js App Router)
Business logic extracted to lib/ — never inline in route handlers
Test files co-located with source files in __tests__/

1.3 Import Ordering

// 1. Node built-ins
import { cookies } from 'next/headers';

// 2. External dependencies (node_modules)
import { z } from 'zod';
import * as bcrypt from 'bcrypt';
import { SignJWT, jwtVerify } from 'jose';

// 3. Internal — absolute paths (@/ alias)
import { db } from '@/lib/db';
import { verifyJWT } from '@/lib/auth';
import type { User } from '@/lib/types';

// 4. Internal — relative paths
import { validateRemittanceBody } from './validate';

Enforced by: ESLint import/order rule

1.4 Error Handling Patterns

// PREFERRED — consistent HTTP error responses in Next.js API routes
export async function POST(request: Request): Promise<Response> {
  let body: unknown;
  try {
    body = await request.json();
  } catch {
    return Response.json({ error: 'Invalid JSON body' }, { status: 400 });
  }

  const validation = remittanceSchema.safeParse(body);
  if (!validation.success) {
    return Response.json(
      { error: 'Validation failed', details: validation.error.flatten() },
      { status: 422 }
    );
  }

  // Business logic in lib/ — throws typed errors
  try {
    const result = await processRemittance(validation.data);
    return Response.json(result, { status: 201 });
  } catch (error) {
    if (error instanceof InsufficientBalanceError) {
      return Response.json({ error: 'Insufficient balance' }, { status: 402 });
    }
    if (error instanceof KycRequiredError) {
      return Response.json({ error: 'KYC verification required' }, { status: 403 });
    }
    // Never expose internal errors
    console.error('Unhandled error in remittance:', error);
    return Response.json({ error: 'Internal server error' }, { status: 500 });
  }
}

Rules:

NEVER return stack traces or DB error messages to the client
NEVER use any type — TypeScript strict mode enforces this
NEVER swallow errors silently
Use 402 for Insufficient Balance (fintech convention), not 400
Error messages in Norwegian for user-facing validation

2. Code Formatting

2.1 Formatter

Language	Tool	Config File	Enforced In
TypeScript / JavaScript	Prettier	`.prettierrc`	CI + pre-commit hook
JSON / YAML	Prettier	`.prettierrc`	CI + pre-commit hook

Key formatting rules:

Indentation: 2 spaces
Max line length: 100 characters
Semicolons: required
Trailing commas: all (ES2020)
Quotes: single quotes

Auto-format on save: Enabled via .vscode/settings.json (see local-development-setup.md)

2.2 Linter

Language	Tool	Config	Rules Severity
TypeScript	ESLint + TypeScript-ESLint	`.eslintrc.json`	Error = blocks CI

Linting rules that are errors (block CI):

@typescript-eslint/no-explicit-any — no any types
no-console (except console.error in server code)
@typescript-eslint/no-unused-vars
SQL string concatenation (custom Drop rule)

Disable linting inline (sparingly):

// eslint-disable-next-line @typescript-eslint/no-explicit-any -- External library returns untyped response
const rawResponse: any = await externalLibrary.call();

Every inline disable must have a comment explaining why.

3. Git Conventions

3.1 Commit Message Format

Standard: Conventional Commits

Format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

Type	When to Use
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation only
`style`	Formatting changes (no logic change)
`refactor`	Code change that neither fixes a bug nor adds a feature
`test`	Adding or updating tests
`chore`	Build system, dependency updates, CI changes
`perf`	Performance improvements
`security`	Security fix or hardening

Drop examples:

feat(auth): add bcrypt rounds configuration via env var
fix(transactions): prevent double-spend with per-user lock
test(db): add assertion that users table has no balance column
security(middleware): add CSRF protection to all mutating endpoints
chore: upgrade Next.js to 15.x patch

Breaking changes:

feat(api)!: rename /api/transactions/send to /api/transactions/remittance

BREAKING CHANGE: All clients must update API calls to new path

3.2 Branch Naming Convention

Type	Pattern	Example
Feature	`feature/MC-{task-id}-description`	`feature/MC-042-rate-limiting`
Bug fix	`fix/MC-{task-id}-description`	`fix/MC-051-double-spend`
Hotfix	`hotfix/MC-{task-id}-description`	`hotfix/MC-060-jwt-bypass`
Security	`security/MC-{task-id}-description`	`security/MC-070-csrf-fix`
Chore	`chore/MC-{task-id}-description`	`chore/MC-080-upgrade-deps`

Rules:

Lowercase only; hyphens, not underscores
Always include Mission Control task ID (MC-{id})

3.3 PR Title & Description Format

Title format: Same as commit message: type(scope): description

Required PR description sections:

What: What does this PR do? (bullet points)
Why: Which Mission Control task / acceptance criterion?
Pass-through model check: Does this change touch DB schema? If yes, confirm no balance/CVV columns added
Tests: What tests were added/modified?
Security: Does this touch auth, payments, or input validation?

3.4 PR Size Guidelines

Size	Lines Changed	Status
Small	< 200	Ideal — review same session
Medium	200-400	Acceptable
Large	400-800	Needs justification — split if possible
Extra Large	> 800	Exceptional only — must be pre-approved by John

4. Code Review Guidelines

4.1 What to Look For (Validator Agent Checklist)

Reviewers must check:

Pass-through model invariant: no balance column; no card_number or cvv
Parameterized SQL — no string interpolation in any DB query
bcrypt used for passwords — SHA-256 explicitly forbidden
JWT secret not hardcoded; not in response body
Rate limiting applies to new auth/transaction endpoints
Input validation (Zod schema) on all new request bodies
Error messages don't leak internal state
Fee calculations correct (0.5% remittance; 1% QR)
Tests cover the change and edge cases

Reviewers should NOT block on:

Personal style preferences covered by Prettier/ESLint (the linter decides)
Minor refactors not related to the PR's scope

4.2 Review Turnaround

PR Type	First review
Security / Critical fix	Same session
Standard feature	Within 1 session

4.3 Approval Requirements

Branch	Required Approvals
`main`	Validator agent approval + John (AI Director) sign-off
Feature branches	Validator agent approval
Hotfix	John (AI Director) or Alem Bašić (CEO) approval — async OK

4.4 Constructive Review Feedback

nit: — Minor issue, not a blocker
question: — Need clarification
suggestion: — Improvement idea (not required)
blocker: — Must be fixed before merge (e.g., SQL injection risk, bcrypt bypass)

5. Testing Standards

5.1 Test Naming Conventions

// Vitest format: describe → it('should [behavior] when [condition]')
describe('hashPassword', () => {
  it('should return a bcrypt hash starting with $2', async () => { ... });
  it('should reject SHA-256 hashes at verify time', async () => { ... });
  it('should reject passwords longer than 1000 characters', async () => { ... });
});

describe('calculateRemittanceFee', () => {
  it('should return 5 NOK fee for 1000 NOK amount', () => { ... });
  it('should reject amounts below 100 NOK', () => { ... });
});

5.2 Test Organization

src/drop-app/__tests__/
├── auth.test.ts              # Unit: bcrypt, JWT, password validation
├── validation.test.ts        # Unit: input validation, XSS, injection
├── transactions.test.ts      # Unit: fee calculation, transaction logic
├── rates.test.ts             # Unit: exchange rates
├── api-endpoints.test.ts     # Integration: all 26 API routes
├── db.test.ts                # Integration: schema compliance, FK constraints
├── middleware.test.ts        # Integration: rate limiting, auth, CSRF
├── api-benchmarks.test.ts    # Performance: bcrypt timing, DB queries
├── feature-flags.test.ts     # Unit: feature flag behavior
├── regression-suite.test.ts  # Regression: critical path smoke
├── sumsub-integration.test.ts # Integration: KYC webhook mock
├── cards-integration.test.ts  # Integration: cards (feature-flagged)
└── e2e/
    ├── user-flows.spec.ts    # E2E: registration, login
    ├── full-flows.spec.ts    # E2E: remittance, QR payment
    └── input-chaos.spec.ts   # E2E: 20+ validation edge cases

5.3 Mocking Guidelines

// PREFERRED: Mock BaaS at the module level (NEXT_PUBLIC_SERVICE_MODE=mock)
// The mock mode is configured via env var — no vi.mock() needed for BaaS

// PREFERRED for unit tests: vi.mock for db queries
vi.mock('@/lib/db', () => ({
  db: {
    query: vi.fn(),
    run: vi.fn(),
  }
}));

// For integration tests: use real SQLite in-memory DB
// (configured in vitest.config.ts — no mock needed)

// NEVER mock the pass-through model assertions in db.test.ts
// NEVER mock the bcrypt rejection tests in auth.test.ts

5.4 Coverage Requirements

Layer	Lines	Branches	Notes
Auth module	100%	100%	Fintech security — strictly enforced
Transaction logic	100%	100%	Fee calculation — strictly enforced
API handlers	≥ 80%	≥ 70%
Input validation	≥ 90%	≥ 85%	Security-critical
DB layer	≥ 90%	—	Compliance assertions required
Overall minimum	≥ 80%	—	CI gate

6. Documentation Standards

6.1 When to Add Comments

// GOOD — explains WHY (not obvious from code)
// Bcrypt rounds set to 12 (not 10) per NFR-SEC02 fintech standard.
// Using 10 rounds would be faster but falls below security threshold.
const BCRYPT_ROUNDS = parseInt(process.env.BCRYPT_ROUNDS ?? '12', 10);

// GOOD — documents non-obvious business rule
// Fee is calculated on gross amount, not total debit (gross + fee)
// This is required by Drop's pass-through model (ADR-003)
const fee = amount * REMITTANCE_FEE_RATE;

// BAD — restates what code says
// Multiply amount by fee rate
const fee = amount * REMITTANCE_FEE_RATE;

Comment when:

A fintech business rule is implemented (always cite the rule)
A security decision was made (e.g., why bcrypt rounds = 12)
A workaround exists for an external system quirk

6.2 ADR Format

Write an Architecture Decision Record when:

Changing the database (SQLite → PostgreSQL)
Changing the authentication mechanism (DOB → BankID)
Modifying the fee model (new corridor, new fee rate)
Adding a new BaaS partner

ADR location: comms/decisions/YYYY-MM-DD-decision-title.md

6.3 API Documentation

When adding a new API endpoint, update docs/backend/API-REFERENCE.md:

Method + path
Authentication required (Yes/No)
Request body schema (Zod type → JSON example)
Response schema (success + all error codes)

7. Security Coding Practices — Drop Fintech Standards

Practice	Rule
SQL queries	NEVER string interpolation. Always parameterized queries (better-sqlite3 `?` placeholders)
Password hashing	bcrypt ONLY with 12 rounds in production. SHA-256 hashes are REJECTED at login
JWT	`jose` library only. Secret via `JWT_SECRET` env var. Fail fast if missing
Input validation	Zod schemas on ALL API route request bodies. Server-side only — never trust client
Pass-through model	NEVER add `balance` column to users. NEVER add `card_number` or `cvv` to cards
Rate limiting	DB-backed rate limiter (not in-memory). Auth: 10/min; General: 60/min
CSRF	CSRF token required on all POST/PATCH/DELETE endpoints
Cookie settings	JWT: httpOnly, SameSite=Strict, Secure in production
Logging	NEVER log passwords, JWT tokens, card numbers, or full phone numbers
Error messages	NEVER expose DB errors, stack traces, or internal state to users
Dependencies	Run `npm audit` before adding any dependency. No HIGH/CRITICAL CVEs

Security review trigger: Any PR touching auth, payments, DB schema, or input validation must be reviewed by Validator agent AND flagged to John (AI Director).

8. Performance Coding Practices

Practice	Rule
Database queries	One bounded query per API call where possible. Use JOIN instead of N+1
Pagination	Never load all transactions in history — always paginate (default: 20 per page)
bcrypt	Password max length = 1,000 chars (validation before bcrypt to prevent DoS)
SQLite	Use WAL mode for concurrent reads. Serialize writes (one at a time)
Next.js	Use Server Components for static/cached data; Client Components for interactive UI
Bundle size	Run `npm run build` and check bundle analyzer before UI changes

Approval

Role	Name	Date	Signature
Author	John (AI Director)	2026-02-23	Approved (AI)
QA Lead	Validator Agent	2026-02-23	Approved (AI)
Tech Lead	John	2026-02-23	Approved
CEO (Alem)	Alem Bašić	TBD

Coding Standards: Drop — Fintech Payment App

Coding Standards: Drop — Fintech Payment App

Document History

Purpose

1. Language-Specific Conventions

1.1 Naming Conventions

1.2 File Organization

1.3 Import Ordering

1.4 Error Handling Patterns

2. Code Formatting

2.1 Formatter

2.2 Linter

3. Git Conventions

3.1 Commit Message Format

3.2 Branch Naming Convention

3.3 PR Title & Description Format

3.4 PR Size Guidelines

4. Code Review Guidelines

4.1 What to Look For (Validator Agent Checklist)

4.2 Review Turnaround

4.3 Approval Requirements

4.4 Constructive Review Feedback

5. Testing Standards

5.1 Test Naming Conventions

5.2 Test Organization

5.3 Mocking Guidelines

5.4 Coverage Requirements

6. Documentation Standards

6.1 When to Add Comments

6.2 ADR Format

6.3 API Documentation

7. Security Coding Practices — Drop Fintech Standards

8. Performance Coding Practices

Related Documents

Approval