Architecture

Tok technical architecture, Kotlin/Ktor, bank adapter pattern, GCP infrastructure

Tech Stack
Bank Adapter Pattern
Development Rules

Tech Stack

Tok is a Kotlin-native backend built for reliability and financial-grade security.

Core Stack

Layer	Technology	Notes
Language	Kotlin	JVM-based, coroutine-native
HTTP Framework	Ktor	Kotlin-idiomatic, coroutines-native routing
Dependency Injection	Koin	Lightweight, Kotlin-first DI
Database	PostgreSQL	Primary data store
ORM	Exposed (Kotlin SQL framework)	Type-safe SQL DSL
Connection Pooling	HikariCP	High-performance JDBC pool
DB Migrations	Flyway	Version-controlled schema migrations
Job Scheduling	Quartz Scheduler + coroutines	Bank sync scheduling
Serialization	kotlinx.serialization	Native Kotlin JSON
Build	Gradle (Kotlin DSL)	Multi-module project

Security & Encryption

Concern	Technology
Token encryption	AES-256-GCM
Key management	GCP Cloud KMS (HSM-backed)
PSD2 mTLS (QWAC)	DigiCert or GlobalSign certificate
CSRF protection	Cryptographic random `state` parameter per consent
Secret storage	GCP Secret Manager

Token encryption flow:

1. Receive OAuth token from bank API
2. Call GCP Cloud KMS generateDataKey (DEK + encrypted DEK)
3. Encrypt token with DEK (AES-256-GCM, random IV)
4. Store: encrypted_dek + iv + ciphertext in PostgreSQL
5. DEK discarded from memory after use

QWAC private key is stored in GCP Cloud KMS HSM — never extracted to filesystem.

Testing

Tool	Purpose
Kotest	Primary test framework (BDD-style)
MockK	Kotlin-idiomatic mocking
Testcontainers	Ephemeral PostgreSQL for integration tests

Cloud Infrastructure — GCP

Service	Purpose
Cloud Run	API server deployment (serverless containers)
Cloud SQL	Managed PostgreSQL
Cloud KMS	HSM-backed key management for OAuth tokens
Secret Manager	QWAC certs, API credentials

Data residency: europe-north1 (Finland) — covers EU/GDPR requirements for Croatian data, and PDPL-equivalent requirements for Serbian data.

API Design

Aspect	Choice
Style	REST + OpenAPI 3.1
Auth	API keys (server-to-server) + OAuth2 (PSD2 consent flows)
Multi-tenant	Organisation-scoped — each client = one organisation
Rate limiting	Per-organisation, tiered: Free / Pro / Enterprise

Core endpoints:

GET /accounts — list bank accounts
GET /transactions — fetch transactions (with date range filters)
POST /consents — initiate PSD2 consent flow
POST /payments — initiate payment (PISP — Phase 2)

Project Structure

Tok/
├── api/                        # Ktor API server (Gradle module)
│   └── src/
│       ├── main/kotlin/io/tokapi/
│       │   ├── Application.kt       # Ktor entry point
│       │   ├── adapters/             # BerlinGroupAdapter, BilateralAdapter
│       │   ├── consent/              # PSD2 consent management
│       │   ├── routes/               # Ktor routing
│       │   ├── services/             # Business logic
│       │   ├── models/               # Domain models + Exposed tables
│       │   └── plugins/              # Auth, rate-limit, logging, serialization
│       └── test/kotlin/io/tokapi/
├── sdk-kotlin/                 # Kotlin client SDK (for Bilko, Drop)
├── sdk-node/                   # Node.js client SDK (for third parties)
├── shared/                     # Shared domain types
├── docs/                       # Documentation
├── infrastructure/
│   ├── docker-compose.yml
│   └── terraform/              # GCP infrastructure as code
├── design/figma/
├── build.gradle.kts            # Root Gradle build
├── settings.gradle.kts         # Multi-module config
└── Dockerfile

SDKs

SDK	Language	Package
`sdk-kotlin/`	Kotlin	`io.tokapi:sdk-kotlin`
`sdk-node/`	TypeScript	`@tokapi/sdk`
`packages/sdk-python/`	Python 3.10+	`tokapi-sdk`

Bank Adapter Pattern

The bank adapter pattern is a core architectural principle in Tok. Every bank integration goes through an abstract BankAdapter interface, isolating the rest of the system from bank-specific API differences.

Why This Pattern?

Banks across Croatia, Serbia, and BiH use different API standards:

Croatia: Berlin Group NextGenPSD2 (standardised, all HUB-registered banks)
Serbia (EU groups): Berlin Group (UniCredit, Raiffeisen, NLB)
Serbia (domestic): No central standard — bilateral per bank (AIK, OTP Serbia, Banca Intesa)
BiH: Bilateral agreements only (no PSD2 mandate)

The adapter pattern hides this complexity behind one interface.

Abstract Interface

interface BankAdapter {
    /** Initiate OAuth consent flow — returns redirect URL */
    suspend fun initiateConsent(
        organizationId: String,
        callbackUrl: String
    ): ConsentRequest

    /** Exchange auth code for access + refresh tokens */
    suspend fun exchangeCode(code: String, state: String): OAuthTokens

    /** Refresh access token using refresh token */
    suspend fun refreshToken(refreshToken: String): OAuthTokens

    /** Fetch transactions for a date range */
    suspend fun fetchTransactions(
        accessToken: String,
        accountId: String,
        fromDate: LocalDate,
        toDate: LocalDate
    ): List<BankTransaction>

    /** Fetch account balance */
    suspend fun fetchBalance(
        accessToken: String,
        accountId: String
    ): BigDecimal

    /** Revoke consent */
    suspend fun revokeConsent(accessToken: String, consentId: String)
}

Implementations

BerlinGroupAdapter

Implements the Berlin Group NextGenPSD2 standard.

Used for:

All Croatian banks (registered with HUB — min. v1.3.8)
EU bank groups in Serbia: UniCredit, Raiffeisen, NLB

Standard endpoints:

Consent URL:  {baseUrl}/v1/consents
Auth URL:     {baseUrl}/v1/oauth/authorize
Token URL:    {baseUrl}/v1/oauth/token
Accounts:     GET {baseUrl}/v1/accounts
Transactions: GET {baseUrl}/v1/accounts/{accountId}/transactions
              ?dateFrom={ISO}&dateTo={ISO}

Required headers:

Authorization: Bearer {access_token}
X-Request-ID:  {uuid}          ← unique per request
PSU-IP-Address: {user-ip}      ← required by some banks

Auth flow: OAuth 2.0 Authorization Code Grant + SCA redirect.

BilateralAdapter

Implements per-bank custom REST integrations for banks without a central standard.

Used for:

Domestic Serbian banks (AIK, OTP Serbia, Banca Intesa Serbia)
BiH banks under bilateral agreements
Any bank that does not adopt Berlin Group

Each bilateral bank gets its own BilateralAdapter subclass with custom field mapping — the interface contract remains identical.

Bank Registry

val BANK_REGISTRY: Map<String, BankAdapterConfig> = mapOf(
    // Croatia (Berlin Group)
    "addiko-hr"    to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://oapideveloper.addiko.hr"
    ),
    "erste-hr"     to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://developers.erstegroup.com"
    ),
    "hpb-hr"       to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://openbanking.hpb.hr"
    ),
    "otp-hr"       to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://api.otpbanka.hr"
    ),
    "pbz-hr"       to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://apiportal.pbz.hr"
    ),
    "raiffeisen-hr" to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://sandbox.rba.hr"
    ),
    "zaba-hr"      to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://developer.unicredit.eu"
    ),
    // Serbia — EU groups (Berlin Group)
    "nlb-rs"       to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://developer.nlbkb.rs"
    ),
    "unicredit-rs" to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://developer.unicredit.eu"
    ),
    "raiffeisen-rs" to BankAdapterConfig(
        adapter = "BerlinGroup",
        baseUrl = "https://api.rbinternational.com"
    ),
    // Domestic Serbian banks — added as bilateral agreements are established
)

Transaction Normalization

Regardless of which adapter is used, all transactions are normalized to the internal BankTransaction format before being stored. This is the adapter's primary responsibility.

Internal format fields:

Field	Type	Source
`externalId`	String	Bank's own transaction ID (dedup key)
`bookingDate`	LocalDate	Berlin Group `bookingDate`
`valueDate`	LocalDate	Berlin Group `valueDate`
`amount`	NUMERIC(19,4)	Normalized — never float
`currency`	CurrencyCode	ISO 4217
`direction`	inbound/outbound	Derived from credit/debit indicator
`creditorIban`	String?	Berlin Group `creditorAccount.iban`
`debtorIban`	String?	Berlin Group `debtorAccount.iban`
`remittanceInfo`	String?	`remittanceInformationUnstructured`
`source`	String	`open_banking` (vs `manual` or `csv_import`)

Adding a New Bank

Determine which adapter applies (Berlin Group or bilateral)
Add entry to BANK_REGISTRY with baseUrl, authUrl, scopes
If bilateral — implement custom fetchTransactions() field mapping
Register sandbox credentials and test against bank sandbox
Add bank to UI: logo, display name, supported countries
Test deduplication against externalId + bankAccountId unique constraint

Development Rules

Seven mandatory rules for all Tok development. These rules exist because financial data and PSD2 compliance leave no room for shortcuts.

Never update or delete a consent record. Each state change creates a new log entry:

consent_created → consent_exchanged → consent_active
                                    → consent_expired (90 days)
                                    → consent_revoked (user action)

All consent events are logged to LoggedAction (append-only). This is a legal compliance requirement under PSD2.

Rule 2 — Token Encryption Mandatory

AES-256-GCM + GCP Cloud KMS for ALL OAuth tokens. No exceptions.

CORRECT:  Store tokens via Cloud KMS envelope encryption → encrypted_dek + iv + ciphertext in DB
WRONG:    Store raw tokens in DB or env vars
WRONG:    Store tokens in logs, files, or memory beyond request lifecycle

QWAC private key must also live in GCP Cloud KMS HSM — signing is done via Cloud KMS API, the key is never extracted.

Rule 3 — Bank Adapter Pattern

Every bank integration goes through the abstract BankAdapter interface.

// Correct
class BerlinGroupAdapter : BankAdapter { ... }
class BilateralAdapter   : BankAdapter { ... }

// Wrong — never call bank HTTP endpoints directly from services/routes

The adapter is the only layer that knows about bank-specific API formats. Services above it work only with normalized BankTransaction objects.

Rule 4 — Deduplication via externalId

externalId (bank's own transaction ID) + bankAccountId = unique constraint.

Duplicate imports are silently skipped — this is intentional, not an error. Never create duplicate transactions.

ALTER TABLE bank_transactions
ADD CONSTRAINT uq_bank_account_external
UNIQUE (bank_account_id, external_id);

Rule 5 — Money = NUMERIC(19,4)

Never use float or double for financial amounts.

// Correct
val amount: BigDecimal  // Kotlin
// Correct in DB
amount NUMERIC(19,4)

// Wrong
val amount: Double  // loses precision
val amount: Float   // loses precision

All amounts from bank APIs must be parsed to BigDecimal before storage. Amount equality comparisons use exact decimal matching.

Rule 6 — CSRF on Consent

// Correct
val state = java.security.SecureRandom()
    .generateSeed(32)
    .toHexString()
// Store in server-side session (NOT cookie, NOT localStorage)
// Validate on callback — reject if mismatch
// One-time use — invalidate after successful exchange

// Wrong
val state = UUID.randomUUID().toString()  // too predictable
val state = "fixed-string"               // completely insecure

Rule 7 — 90-Day Consent Tracking

Every BankConnection must have automated expiry monitoring.

PSD2 (EBA RTS Art. 10) requires re-authentication every 90 days.

Mandatory implementation:

consentValidUntil field on every BankConnection
Daily cron: check all active connections
14 days before expiry: send email to org admin
On expiry: set consentStatus = 'expired', pause sync jobs
UI: show "Bank feed paused — click to reconnect"
One-click re-connect flow (user re-does SCA, new tokens stored)

Without this, bank feed silently breaks for ALL users when consents expire simultaneously.

Summary

Rule	Enforcement
1. Consent immutability	Code review — no UPDATE/DELETE on consent tables
2. Token encryption	No raw token strings in code/DB/logs
3. Bank adapter pattern	No direct HTTP bank calls outside adapter layer
4. Deduplication	DB unique constraint enforced
5. Money = NUMERIC(19,4)	No float/double for amounts anywhere
6. CSRF on consent	State parameter required in every consent initiation
7. 90-day tracking	Daily cron + email notification mandatory

Architecture

Tech Stack

Tech Stack

Core Stack

Security & Encryption

Testing

Cloud Infrastructure — GCP

API Design

Project Structure

SDKs

Bank Adapter Pattern

Bank Adapter Pattern

Why This Pattern?

Abstract Interface

Implementations

BerlinGroupAdapter

BilateralAdapter

Bank Registry

Transaction Normalization

Adding a New Bank

Development Rules

Development Rules

Rule 1 — Consent Immutability

Rule 2 — Token Encryption Mandatory

Rule 3 — Bank Adapter Pattern

Rule 4 — Deduplication via externalId

Rule 5 — Money = NUMERIC(19,4)

Rule 6 — CSRF on Consent

Rule 7 — 90-Day Consent Tracking

Summary