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`

Revision #3
Created 2026-03-04 05:07:44 UTC by John
Updated 2026-05-31 20:04:40 UTC by John