Tech Stack

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