NexusPay — Resilient P2P Digital Wallet Platform

NexusPay is a backend platform that simulates a modern, peer-to-peer (P2P) digital wallet (similar to Venmo or Google Pay). It demonstrates a microservices architecture focused on resilience, scalability, and data integrity using an event-driven design powered by Apache Kafka.

🎯 Key Focus: Enterprise-grade architectural patterns for building robust financial technology systems that handle failures gracefully while guaranteeing data consistency.

🏗️ Architecture Overview

graph TD
    subgraph "Client"
        User[📱 User's App]
    end

    subgraph "NexusPay Platform"
        User -- "HTTP Request (w/ Idempotency-Key)" --> Gateway[API Gateway - Spring Cloud Gateway]

        Gateway -- "Routes to..." --> TransactionService[Transaction Service - Accepts & Persists Intent]
        Gateway -- "Routes to..." --> AccountService[Account Service - Manages Balances]

        TransactionService -- "1. Publishes Event" --> Kafka[Apache Kafka - KRaft Mode]
        Kafka -- "2. Delivers Event" --> AccountService

        TransactionService -- "Registers & Discovers" --> Eureka[Discovery Server - Eureka]
        AccountService -- "Registers & Discovers" --> Eureka

        subgraph "Databases"
            TransactionService -- "Writes Intent" --> TxnDB[(PostgreSQL Transaction Log)]
            TransactionService -- "Checks Idempotency" --> Redis[(Redis API Idempotency)]
            AccountService -- "Updates Balances & Checks Idempotency" --> AcctDB[(PostgreSQL Account Balances)]
        end
    end

    style User fill:#cde4ff
    style Gateway fill:#d5e8d4
    style Eureka fill:#fff2cc

Loading

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• (Optional) Java 17 and Maven for local development

Run the Application

# Clone the repository
git clone https://github.com/your-username/NexusPay.git
cd NexusPay

# Build and start all services
docker-compose up --build

# Check service health
docker-compose ps

That's it! The platform is now running at http://localhost:8080

Service URLs

Service	URL	Purpose
API Gateway	http://localhost:8080	Main entry point for all requests
Eureka Dashboard	http://localhost:8761	Service discovery console
Account Service	http://localhost:8081	Direct access (debugging only)
Transaction Service	http://localhost:8082	Direct access (debugging only)

🔧 Configuration & Environment Variables

Key Configuration Files

Service	Config File	Purpose
API Gateway	application.properties	Routing rules, service discovery
Account Service	application.properties	Database connection, Kafka settings
Transaction Service	application.properties	Database connection, Redis settings
All Services	application-docker.properties	Docker-specific overrides

Important Environment Variables

# Database Configuration
SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/nexuspay
SPRING_DATASOURCE_USERNAME=nexuspay_user
SPRING_DATASOURCE_PASSWORD=nexuspay_password

# Kafka Configuration  
SPRING_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
SPRING_KAFKA_CONSUMER_GROUP_ID=nexuspay-group

# Redis Configuration
SPRING_REDIS_HOST=redis
SPRING_REDIS_PORT=6379

# Eureka Configuration
EUREKA_CLIENT_SERVICE_URL_DEFAULTZONE=http://discovery-server:8761/eureka

Database Management

# Connect to PostgreSQL
docker-compose exec postgres psql -U nexuspay_user -d nexuspay

# Check Redis cache
docker-compose exec redis redis-cli
> KEYS *
> GET idempotency:some-key

# Monitor Kafka topics
docker-compose exec kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic transaction-events \
  --from-beginning

🔑 Key Features & Patterns

Pattern	Implementation	Benefit
🔄 Event-Driven Architecture	Apache Kafka for async communication	Loose coupling, fault tolerance
🛡️ Two-Layer Idempotency	Redis + PostgreSQL constraints	Prevents duplicate transactions
📦 Transactional Outbox	Atomic DB + Event publishing	Guaranteed event delivery
🔒 Pessimistic Locking	Database-level account locks	Prevents race conditions
🚪 API Gateway	Single entry point with routing	Security, load balancing
🔍 Service Discovery	Netflix Eureka registration	Dynamic service location
🗄️ Database per Service	Isolated data ownership	Independent scaling, fault isolation

🛠️ Technology Stack

• Backend: Java 17, Spring Boot 3, Spring Cloud Gateway
• Messaging: Apache Kafka (KRaft mode)
• Databases: PostgreSQL, Redis
• Service Discovery: Netflix Eureka
• Containerization: Docker, Docker Compose
• Build: Apache Maven

🔍 Monitoring & Health

# Check all services status
docker-compose ps

# View logs for specific service
docker-compose logs -f transaction-service

# Monitor Kafka topics
docker-compose exec kafka kafka-topics --bootstrap-server localhost:9092 --list

📚 Documentation

For detailed architectural decisions, implementation patterns, and production considerations, see:

📖 DOCUMENTATION.md

Topics covered:

• ⚡ Performance optimization strategies
• 🔒 Security hardening guidelines
• 📊 Observability and monitoring setup
• 🧪 Comprehensive testing approaches
• 🚀 Production deployment patterns
• 🔮 Future enhancement roadmap

🐛 Troubleshooting

Issue	Solution
Port conflicts	Ensure ports 8080, 8081, 8082, 8761, 5432, 9092, 6379 are free
Container startup fails	Check docker-compose logs <service-name>
Database connection errors	Verify PostgreSQL credentials in docker-compose.yml
Kafka not ready	Wait for Kafka health check to pass (~30 seconds)

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is provided for educational purposes. See LICENSE for details.

---

💡 Educational Focus: This project demonstrates production-ready patterns for building resilient financial systems. While functional, additional security hardening would be required for real-world deployment.