Service Architecture
Peak Gateway runs 6 Kotlin/Spring Boot microservices on Google Cloud Run.
Service Map
| Service | Port | Purpose | Key Dependencies |
|---|---|---|---|
| auth | 8081 | OAuth2 token issuance, JWK publishing, client admin | schema, security, Spring Authorization Server |
| processing | 8082 | Core payment engine: sale, auth, capture, void, refund, subscriptions | transit-client, schema, security, notifications |
| management | 8083 | Portal backend: merchants, users, SAML SSO, reports, audit | schema, security, notifications |
| online-txn | 8084 | E-commerce: checkout sessions, hosted payments, webhooks, API keys | transit-client, schema, security, notifications |
| merchant-onboarding | 8085 | CDE-scoped: TransIT credentials, NexGO XTMS device binding | transit-client, xtms-client, schema, security, Cloud KMS |
| status | 8086 | Health aggregator (no database, no Pub/Sub) | security only |
Communication Flow
Auth (:8081) ──JWK──> Public services validate OAuth tokens via JWK endpoint
Processing (:8082) <──IAM── Management (:8083) <──Firebase── Portal
Processing (:8082) <──IAM── Online-Txn (:8084) <──OAuth── Checkout/E-commerce
Merchant-Onboarding (:8085) <──IAM── Management (:8083) --> TransIT + XTMS
Status (:8086) ──health──> All services
Two-tier security model:
- Public-facing (auth, management, online-txn, status): Firebase Auth + OAuth2 via JWK
- Internal-only (processing, merchant-onboarding): Cloud Run IAM only — no public access, no LB route
Shared Library Dependencies
| Service | security | schema | transit-client | xtms-client | notifications |
|---|---|---|---|---|---|
| auth | ✓ | ✓ | |||
| processing | ✓ | ✓ | ✓ | ✓ | |
| management | ✓ | ✓ | ✓ | ||
| online-txn | ✓ | ✓ | ✓ | ✓ | |
| merchant-onboarding | ✓ | ✓ | ✓ | ✓ | |
| status | ✓ |
Tech Stack
| Layer | Technology |
|---|---|
| Language | Kotlin 2.2.2, Java 25 |
| Framework | Spring Boot 4.0.2, Spring Security 7.0 |
| Database | Cloud Spanner (PostgreSQL dialect) via SQLDelight 2.2.1 |
| Auth | OAuth2 (Spring Authorization Server) + Firebase Auth + SAML SSO |
| Messaging | Cloud Pub/Sub (email, SMS, transaction events) |
| External APIs | TSYS TransIT Multipass (payments), NexGO XTMS (devices) |
| Build | Bazel with rules_kotlin 2.2.2 |
| Deployment | GCP Cloud Run (us-east1) |
| Observability | Structured ECS logging, OpenTelemetry -> Cloud Trace |
Environments
| Environment | API Domain | Portal | Cloud Run Prefix |
|---|---|---|---|
| Production | api.peakgateway.co | support.peakgateway.co | gateway-{service} |
| Staging | staging-api.peakgateway.co | staging-support.peakgateway.co | gateway-{service}-staging |
Request Flow
- Client sends request with Bearer token (OAuth2 or Firebase ID token)
- Cloud Run routes to the target service
- Security filters validate the token via JWK endpoint (auth service)
- Controller checks
@RequireScope(API clients) or@RequireRole(portal users) - Service layer executes business logic
- Repository layer queries Cloud Spanner via SQLDelight/PGAdapter
- External calls to TransIT/XTMS if needed
- Response wrapped in
ApiResponse<T>envelope