Core Banking Lab

A concurrent banking API demonstrating thread-safe financial operations and production-grade Go architecture.

What This Demonstrates

This project showcases advanced backend engineering skills through a banking API that handles concurrent financial operations safely:

• Event-Driven Architecture: Kafka-based async processing with at-least-once delivery
• Consumer Idempotency: Deterministic deduplication preventing duplicate operations
• Thread-Safe Concurrency: Deadlock-free money transfers using ordered mutex locking
• Production Architecture: Clean Diplomat pattern with separated concerns
• Security Hardening: Rate limiting, input validation, audit logging
• Comprehensive Testing: 30+ integration tests including idempotency scenarios

Key Technical Achievements

🔒 Concurrency Safety

Implements fine-grained locking strategy with per-account mutexes for all banking operations (deposits, withdrawals, transfers, balance queries). Uses ordered lock acquisition to prevent deadlocks in multi-account operations and atomic read-modify-write cycles to ensure balance consistency across concurrent transactions.

Performance Results: Successfully processed 100+ concurrent operations with zero data races, zero deadlocks, and error rate < 0.001%. Future benchmarking planned to measure peak throughput under production load conditions.

🏗️ Clean Architecture

Follows golang-standards/project-layout with clear separation of concerns:

cmd/api/              # Application entry point
internal/
  ├── api/            # HTTP layer (handlers, middleware, routes)
  ├── domain/         # Business logic (account operations, models)
  ├── infrastructure/ # External systems (database, events)
  ├── config/         # Configuration management
  └── pkg/            # Shared utilities (errors, logging, telemetry)
test/                 # Test suites (integration, unit)

• Domain Layer: Pure business logic isolated from infrastructure
• API Layer: HTTP handlers and middleware
• Infrastructure Layer: Database and event broker adapters
• Shared Utilities: Reusable components across layers

This ensures the core banking logic remains isolated, testable, and independent of external dependencies.

Quick Start

# Run the API
git clone https://github.com/fandangolas/core-banking-lab.git
cd core-banking-lab
go run cmd/api/main.go

# Or full stack with Docker
docker-compose up --build

Services:

• API: http://localhost:8080
• Kafka UI: http://localhost:8090
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin123)

API Example

# Create accounts
curl -X POST http://localhost:8080/accounts -d '{"owner": "Alice"}'
curl -X POST http://localhost:8080/accounts -d '{"owner": "Bob"}'

# Deposit money
curl -X POST http://localhost:8080/accounts/1/deposit -d '{"amount": 10000}'

# Transfer (thread-safe, atomic)
curl -X POST http://localhost:8080/accounts/transfer \
  -d '{"from": 1, "to": 2, "amount": 5000}'

Testing

# Run all tests
go test ./...

# Run unit tests only
go test ./test/unit/...

# Run integration tests only
go test ./test/integration/...

# Test for race conditions
go test -race ./...

# Test specific concurrent scenario
go test ./test/integration/account -run TestConcurrentTransfer

Test Coverage: 43 tests passing covering concurrent operations, error handling, and edge cases.

Stack

• Backend: Go 1.23 + Gin + Structured Logging
• Message Broker: Apache Kafka (KRaft mode)
• Database: PostgreSQL 16 with connection pooling
• Monitoring: Prometheus + Grafana
• Infrastructure: Docker + Docker Compose + Kubernetes
• Testing: Testify + httptest + Concurrent scenarios

Documentation

• Architecture - Design patterns and structure
• API Reference - Endpoints and examples
• Concurrency - Thread safety and deadlock prevention
• Observability - Monitoring, logging, and metrics
• Security - Defense-in-depth implementation

---

This project demonstrates production-grade Go development with focus on concurrent programming, clean architecture, and comprehensive testing.