GoLedger

A financial API service built in Go, demonstrating backend engineering with thread-safe concurrency, financial scenario simulations, and a scalable architecture. This project showcases advanced Go patterns, including mutex-based concurrency control and comprehensive testing (with context-based cancellation).

🏆 Key Metrics

• 186,075 operations/second - Enterprise-grade performance
• Zero race conditions - Thread-safe financial operations
• Sub-millisecond latency - 0.537ms average response time
• Financial scenario simulations & compliance - High-Frequency Trading simulations, payment processing workflows, deadlock prevention testing, and auditing
• Production-ready - Comprehensive error handling and monitoring

🏗️ Architecture Overview

Clean Architecture Pattern

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP Layer    │───▶│  Business Logic │───▶│   Data Layer    │
│   (Handlers)    │    │   (Services)    │    │   (Database)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
    ┌────▼────┐             ┌────▼────┐             ┌────▼────┐
    │ Chi     │             │ Domain  │             │ Mock DB │
    │ Router  │             │ Models  │             │ + Tests │
    └─────────┘             └─────────┘             └─────────┘

Concurrency Model

• RWMutex: Concurrent reads, exclusive writes
• Multi-level locking: Separate mutexes for data, audit, and health monitoring
• Context cancellation: Timeout and cancellation support
• Optimistic locking: Version-based conflict detection

📂 Project Structure

goapi/
├── cmd/api/main.go              # Application entry point
├── api/api.go                   # API contracts & response types
├── internal/
│   ├── handlers/                # HTTP request handlers
│   │   ├── api.go              # Route definitions & middleware
│   │   ├── get_coin_balance.go # Balance inquiry endpoint
│   │   ├── add_coins.go        # Deposit endpoint
│   │   ├── withdraw_coins.go   # Withdrawal endpoint
│   │   └── transfer_coins.go   # Transfer endpoint
│   ├── middleware/
│   │   └── authorization.go    # Token-based authentication
│   └── tools/
│       ├── database.go         # Database interface & contracts
│       ├── mockdb.go          # High-performance implementation
│       └── mockdb_race_test.go # Financial system test suite
├── go.mod                      # Go module dependencies
└── README.md                   # Project documentation

🧪 Testing & Quality Assurance

The project includes a two-tier testing strategy that demonstrates both fundamental concurrency safety and real-world financial scenario simulations:

internal/tools/
├── basic_test.go      # Core concurrency & race condition testing
├── financial_test.go  # Financial system scenarios
├── database.go        # Interface definitions
└── mockdb.go         # High-performance implementation

Basic Concurrency Tests (basic_test.go)

Purpose: Validates fundamental thread safety and concurrency patterns essential for any financial system.

Test Coverage

• ✅ Concurrent Deposits - Multiple simultaneous balance additions
• ✅ Mixed Operations - Deposits and withdrawals running concurrently
• ✅ Concurrent Transfers - Multi-user transfer scenarios
• ✅ Read-Write Concurrency - Simultaneous reads and writes with RWMutex
• ✅ Performance Benchmarks - Individual operation performance testing

Key Validations

• Race condition detection and prevention
• Money conservation across all operations
• Data integrity under concurrent load
• Sub-millisecond operation performance

Running Basic Tests

# Run basic concurrency tests
go test ./internal/tools/ -run TestBasicConcurrency -v
go test ./internal/tools/ -run TestPerformance -v

# Run performance benchmarks
go test -bench=BenchmarkBasicOperations ./internal/tools/

Financial System Tests (financial_test.go)

Purpose: Demonstrates understanding of financial scenarios and compliance requirements.

Advanced Scenarios

1. High-Frequency Trading Simulation

• Simulates 50 concurrent trades between traders and exchange
• Tests context-based timeouts and cancellation
• Validates money conservation under extreme load
• Measures successful vs failed trade ratios

2. Bank Run Stress Testing

• Simulates panic withdrawals from multiple customers
• Tests system stability under extreme withdrawal pressure
• Validates no negative balance scenarios
• Ensures graceful degradation under stress

3. Payment Processing Workflow

• Two-phase payment processing (customer → processor → merchant)
• 1% processing fee calculation and collection
• Automatic rollback on payment failures
• E-commerce transaction pattern simulation

4. Deadlock Prevention Testing

• Circular transfer scenarios (A→B while B→A)
• Timeout-based deadlock detection
• System responsiveness under potential deadlock conditions
• Money conservation during complex transfer patterns

5. Compliance & Auditing

• Complete audit trail verification
• Transaction history tracking for regulatory compliance
• System health monitoring and reporting
• Data integrity validation across all operations

Running Financial Tests

# Run financial system scenarios
go test ./internal/tools/ -run TestFinancialSystemScenarios -v

# Run compliance and auditing tests
go test ./internal/tools/ -run TestComplianceAndAuditing -v

Test Execution Commands

# Run all tests with race detection
go test -race ./internal/tools/ -v

# Run specific test categories
go test ./internal/tools/ -run TestBasicConcurrency -v
go test ./internal/tools/ -run TestFinancialSystemScenarios -v

# Performance benchmarking
go test -bench=. ./internal/tools/ -benchmem

# Generate test coverage report
go test ./internal/tools/ -cover -coverprofile=coverage.out
go tool cover -html=coverage.out

📊 Monitoring & Observability

Health Endpoint

# System health and metrics
GET /system/health

Response:

{
  "status": "healthy",
  "uptime_seconds": 3600.5,
  "operation_count": 1000000,
  "components": {
    "database": true,
    "audit_log": true,
    "performance": true
  }
}

Audit Trail

• Complete transaction history
• Unique transaction IDs
• Timestamp tracking
• Status monitoring (SUCCESS/FAILED)

🌐 API Endpoints

Authentication

All endpoints require:

• Authorization header with valid token
• username query parameter

Available Operations

Method	Endpoint	Description	Performance
GET	/account/coins	Get user balance	~0.1ms
POST	/account/coins/add	Deposit coins	~0.5ms
POST	/account/coins/withdraw	Withdraw coins	~0.5ms
POST	/account/coins/transfer	Transfer between users	~0.6ms

Example Usage

Get Balance:

curl -H "Authorization: 1" \
     "http://localhost:3000/account/coins?username=aaron"

Transfer Coins:

curl -X POST \
     -H "Authorization: 1" \
     "http://localhost:3000/account/coins/transfer?username=aaron&from=aaron&to=bryan&amount=100"

⚡ Performance Benchmarks

Throughput Testing

Performance: 100 operations in 537.417µs (186,075.25 ops/sec)