# 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` |