{"id":30177584,"url":"https://github.com/en-atul/banking-system","last_synced_at":"2026-04-10T00:53:45.511Z","repository":{"id":305583145,"uuid":"1023024213","full_name":"en-atul/banking-system","owner":"en-atul","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-09T17:53:08.000Z","size":88,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-09T19:31:33.598Z","etag":null,"topics":["api-gateway","config-server","distributed-tracing","eureka-server","feign","jwt-auth","kafka","micrometer","microservices","mongodb","opentelemetry","postgresql","rabbitmq","resilience4j","spring-boot","spring-cloud","spring-gateway-security","spring-security","zipkin"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/en-atul.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-20T11:14:19.000Z","updated_at":"2025-08-09T17:53:11.000Z","dependencies_parsed_at":"2025-07-21T00:22:30.616Z","dependency_job_id":null,"html_url":"https://github.com/en-atul/banking-system","commit_stats":null,"previous_names":["en-atul/banking-system"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/en-atul/banking-system","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/en-atul%2Fbanking-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/en-atul%2Fbanking-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/en-atul%2Fbanking-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/en-atul%2Fbanking-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/en-atul","download_url":"https://codeload.github.com/en-atul/banking-system/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/en-atul%2Fbanking-system/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270005547,"owners_count":24510933,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-12T02:00:09.011Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","config-server","distributed-tracing","eureka-server","feign","jwt-auth","kafka","micrometer","microservices","mongodb","opentelemetry","postgresql","rabbitmq","resilience4j","spring-boot","spring-cloud","spring-gateway-security","spring-security","zipkin"],"created_at":"2025-08-12T05:00:23.404Z","updated_at":"2025-12-30T21:38:35.893Z","avatar_url":"https://github.com/en-atul.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Banking System Microservices with JWT Authentication\n\nThis project implements a microservices banking system with centralized JWT authentication at the API Gateway level.\n\n## 🚀 Quick Start\n\n### Entry Point\n**All API requests must go through the API Gateway at:**\n```\nhttp://localhost:8765\n```\n\n**⚠️ Important:** Do NOT access services directly. Always use the API Gateway as the single entry point.\n\n### Service Discovery\n- **Eureka Server**: http://localhost:8761/\n- **Kafka UI**: http://localhost:4002/\n- **Kafdrop**: http://localhost:9000/\n\n## Architecture Overview\n\n### Authentication Flow\n1. **API Gateway** acts as the central authentication point\n2. **Auth Service** handles user registration, login, and token generation\n3. **Shared JWT Utility** provides common JWT validation logic\n4. **All other services** receive pre-validated requests with user information in headers\n\n### Security Implementation\n\n#### API Gateway Authentication Filter\n- **Global Filter**: Intercepts all requests before routing\n- **Public Endpoints**: `/auth/**`, `/actuator/**`, `/swagger-ui/**`, `/v3/api-docs/**`\n- **Token Validation**: Validates JWT signature and expiration\n- **Role-Based Access Control**: Enforces role requirements per endpoint\n- **User Information**: Adds user details to headers for downstream services\n\n#### Role-Based Access Control\n- **Account Service**: Requires `USER` or `ADMIN` role\n- **Customer Service**: Requires `USER` or `ADMIN` role  \n- **Transaction Service**: Requires `USER` or `ADMIN` role\n- **Ledger Service**: Requires `ADMIN` role only\n- **Notification Service**: Requires `USER` or `ADMIN` role\n\n#### Error Responses\nThe API Gateway returns standardized error responses:\n```json\n{\n  \"error\": \"UNAUTHORIZED\",\n  \"message\": \"Access token is missing or invalid\",\n  \"path\": \"/account/123\",\n  \"timestamp\": \"2024-01-15T10:30:00\",\n  \"status\": 401\n}\n```\n\n### Shared JWT Utility\n\nThe `shared-jwt-util` module provides:\n- `JwtClaims`: DTO for token claims\n- `JwtValidator`: Interface for token validation\n- `AbstractJwtValidator`: Base implementation with common parsing logic\n- `AuthErrorResponse`: Standardized error response format\n\n### Service-Specific Implementations\n\n#### Auth Service\n- Uses `AuthServiceJwtValidator` with database validation\n- Validates tokens against stored token records\n- Handles token refresh and cleanup\n\n#### API Gateway  \n- Uses `GatewayJwtValidator` with signature-only validation\n- No database dependency for performance\n- Validates token structure and expiration\n\n## 🏗️ Building and Running\n\n### Prerequisites\n- Java 17+\n- Maven 3.6+\n- Docker \u0026 Docker Compose\n\n### Configuration Setup\n\n**⚠️ IMPORTANT: External Configuration Repository Required**\n\nThis project uses centralized configuration managed via [Spring Cloud Config](https://spring.io/projects/spring-cloud-config) from an external repository:\n\n**Configuration Repository**: [https://github.com/en-atul/banking-system-config](https://github.com/en-atul/banking-system-config)\n\n#### Option 1: Use Remote GitHub Repository (Recommended)\nThe config server is pre-configured to fetch configuration from the remote GitHub repository. No additional setup required.\n\n#### Option 2: Clone and Use Local Repository\nIf you want to modify configurations locally:\n\n1. **Clone the config repository:**\n   ```bash\n   git clone https://github.com/en-atul/banking-system-config.git\n   cd banking-system-config\n   ```\n\n2. **Update config server path** in `config-server/src/main/resources/application.properties`:\n   ```properties\n   spring.cloud.config.server.git.uri=file:///path/to/your/local/banking-system-config\n   ```\n\n3. **Restart config server** after making changes\n\n#### Configuration Files Available\nThe external repository contains configuration for all services:\n- `account-service.properties` / `account-service-dev.properties`\n- `auth-service.properties` / `auth-service-dev.properties`\n- `customer-service.properties` / `customer-service-dev.properties`\n- `notification-service.properties` / `notification-service-dev.properties`\n- `transaction-service.properties` / `transaction-service-dev.properties`\n- `ledger-service.properties` / `ledger-service-dev.properties`\n\n### Build Order\n1. Build shared-jwt-util first:\n   ```bash\n   cd shared-jwt-util\n   mvn clean install\n   ```\n\n2. Build all services:\n   ```bash\n   mvn clean install\n   ```\n\n## 🚀 Step-by-Step Application Startup\n\n### ⚠️ **IMPORTANT: Docker is Essential**\n\n**Docker must be started FIRST** because it provides all the required infrastructure services:\n- **PostgreSQL** - Database for Account and Customer services\n- **MongoDB** - Database for Notification service  \n- **Kafka** - Message broker for asynchronous communication\n- **Zookeeper** - Required for Kafka cluster management\n- **Kafka UI** - Web interface for Kafka monitoring\n- **Zipkin** - Distributed tracing system\n- **Eureka Server** - Service discovery and registry\n\n### Step 1: Start Infrastructure Services\n\n**For Development:**\n```bash\n# Start all infrastructure services (PostgreSQL, MongoDB, Kafka, Zookeeper, Eureka, Zipkin)\ndocker-compose -f docker-compose.yml -f docker-compose.dev.yml up\n```\n\n**For Production:**\n```bash\n# Start production infrastructure\ndocker-compose -f docker-compose.yml -f docker-compose.prod.yml up\n```\n\n**Verify Infrastructure is Running:**\n```bash\n# Check if all containers are running\ndocker ps\n\n# Expected containers:\n# - postgres (PostgreSQL database)\n# - mongo (MongoDB database)\n# - zookeeper (Kafka dependency)\n# - kafka (Message broker)\n# - kafka-ui (Kafka monitoring)\n# - kafdrop (Alternative Kafka UI)\n# - zipkin (Distributed tracing)\n```\n\n### Step 2: Verify Infrastructure Services\n\n**Check Service Health:**\n- **Eureka Server**: http://localhost:8761/ (should show empty service list initially)\n- **Kafka UI**: http://localhost:4002/ (should show Kafka cluster)\n- **Kafdrop**: http://localhost:9000/ (alternative Kafka UI)\n- **Zipkin**: http://localhost:9411/ (distributed tracing)\n\n### Step 3: Start Microservices in Order\n\n**⚠️ Start services in this specific order:**\n\n1. **Config Server** (Port: 8888)\n   ```bash\n   cd config-server\n   mvn spring-boot:run\n   ```\n   - Provides centralized configuration from external repository\n   - Fetches config from [https://github.com/en-atul/banking-system-config](https://github.com/en-atul/banking-system-config)\n   - Other services depend on this for configuration\n\n2. **Naming Server/Eureka** (Port: 8761)\n   ```bash\n   cd naming-server\n   mvn spring-boot:run\n   ```\n   - Service discovery registry\n   - All services register here\n\n3. **API Gateway** (Port: 8765)\n   ```bash\n   cd api-gateway\n   mvn spring-boot:run\n   ```\n   - Main entry point for all API requests\n   - Requires Eureka for service discovery\n\n4. **Auth Service** (Port: 8000)\n   ```bash\n   cd services/auth-service\n   mvn spring-boot:run\n   ```\n   - Handles user authentication and JWT tokens\n   - Required for all protected endpoints\n\n5. **Account Service** (Port: 8001)\n   ```bash\n   cd services/account-service\n   mvn spring-boot:run\n   ```\n   - Manages bank accounts\n   - Requires Kafka for notifications\n\n6. **Customer Service** (Port: 8002)\n   ```bash\n   cd services/customer-service\n   mvn spring-boot:run\n   ```\n   - Manages customer information\n\n7. **Notification Service** (Port: 8500)\n   ```bash\n   cd services/notification-service\n   mvn spring-boot:run\n   ```\n   - Handles notifications via Kafka\n   - Requires MongoDB and Kafka\n\n8. **Transaction Service** (Port: 8003)\n   ```bash\n   cd services/transaction-service\n   mvn spring-boot:run\n   ```\n   - Manages financial transactions\n\n9. **Ledger Service** (Port: 8004)\n   ```bash\n   cd services/ledger-service\n   mvn spring-boot:run\n   ```\n   - Manages ledger entries (Admin only)\n\n### Step 4: Verify All Services are Running\n\n**Check Eureka Dashboard**: http://localhost:8761/\n- Should show all services registered\n- All services should have status \"UP\"\n\n**Check API Gateway Health**: http://localhost:8765/actuator/health\n- Should return healthy status\n\n**Test Authentication Flow**:\n```bash\n# Register a user\ncurl -X POST http://localhost:8765/auth/api/v1/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"testuser\",\n    \"email\": \"test@example.com\", \n    \"password\": \"password123\",\n    \"firstName\": \"Test\",\n    \"lastName\": \"User\"\n  }'\n```\n\n### Infrastructure Services Overview\n\n| Service | Port | URL | Description | Status Check |\n|---------|------|-----|-------------|--------------|\n| **API Gateway** | 8765 | http://localhost:8765 | Main entry point for all API requests | `/actuator/health` |\n| **Eureka Server** | 8761 | http://localhost:8761/ | Service discovery and registry | Dashboard |\n| **Config Server** | 8888 | http://localhost:8888 | Centralized configuration | `/actuator/health` |\n| **Kafka UI** | 4002 | http://localhost:4002/ | Kafka cluster monitoring and management | Dashboard |\n| **Kafdrop** | 9000 | http://localhost:9000/ | Alternative Kafka UI | Dashboard |\n| **Zipkin** | 9411 | http://localhost:9411/ | Distributed tracing system | Dashboard |\n| **PostgreSQL** | 5336 | localhost:5336 | Account and Customer data | `docker ps` |\n| **MongoDB** | 27017 | localhost:27017 | Notification data | `docker ps` |\n| **Kafka** | 9092 | localhost:9092 | Message broker | Kafka UI |\n| **Zookeeper** | 2181 | localhost:2181 | Kafka dependency | `docker ps` |\n\n### 🚨 **Common Startup Issues**\n\n1. **\"Connection refused\" errors**\n   - Ensure Docker containers are running: `docker ps`\n   - Check if ports are available: `lsof -i :PORT`\n\n2. **\"Service not found\" in Eureka**\n   - Verify Config Server is running first\n   - Check service registration logs\n   - Ensure Eureka server is accessible\n\n3. **Kafka connection issues**\n   - Wait for Zookeeper to fully start\n   - Check Kafka UI at http://localhost:4002/\n   - Verify Kafka is advertising correct listeners\n\n4. **Database connection failures**\n   - Ensure PostgreSQL/MongoDB containers are healthy\n   - Check database credentials in config\n   - Verify network connectivity between services\n\n5. **Config server connection issues**\n   - Verify config server can access [https://github.com/en-atul/banking-system-config](https://github.com/en-atul/banking-system-config)\n   - Check config server logs for Git repository access errors\n   - Ensure internet connectivity for remote config fetch\n   - If using local config, verify file path in config server properties\n\n## 🔄 Asynchronous Communication\n\n### Kafka Integration\n- **Kafka is required** for account creation and updates\n- When an account is created/updated, notifications are sent asynchronously via Kafka\n- **Kafka UI** at http://localhost:4002/ shows:\n  - Topics: `account-notifications`\n  - Message flow between Account Service and Notification Service\n  - Consumer groups and offsets\n\n### Notification Flow\n1. **Account Service** creates/updates account\n2. **Kafka Producer** sends notification event to `account-notifications` topic\n3. **Notification Service** consumes the event asynchronously\n4. **Notification** is saved to MongoDB\n5. **User** can retrieve notifications via API\n\n## 🔐 Testing Authentication\n\n### 1. Register a user:\n```bash\ncurl -X POST http://localhost:8765/auth/api/v1/users \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"testuser\",\n    \"email\": \"test@example.com\",\n    \"password\": \"password123\",\n    \"firstName\": \"Test\",\n    \"lastName\": \"User\"\n  }'\n```\n\n### 2. Login to get access token:\n```bash\ncurl -X POST http://localhost:8765/auth/api/v1/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\": \"testuser\",\n    \"password\": \"password123\"\n  }'\n```\n\n**Response:**\n```json\n{\n  \"message\": \"Login successful\",\n  \"data\": {\n    \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"refreshToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n    \"tokenType\": \"Bearer\",\n    \"expiresIn\": 1800\n  }\n}\n```\n\n### 3. Access protected endpoints with access token:\n```bash\n# Create account (requires USER or ADMIN role)\ncurl -X POST http://localhost:8765/account/api/v1/accounts \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"customerId\": 1,\n    \"accountType\": \"SAVING\",\n    \"balance\": 10000\n  }'\n\n# Get account details\ncurl -X GET http://localhost:8765/account/api/v1/accounts/1 \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n\n# Get notifications\ncurl -X GET http://localhost:8765/notification/api/v1/notifications \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## 📋 API Endpoints\n\n### Public Endpoints (No Authentication Required)\n- `POST /auth/api/v1/users` - Register user\n- `POST /auth/api/v1/auth/login` - Login\n- `POST /auth/api/v1/auth/refresh` - Refresh token\n\n### Protected Endpoints (Require Access Token)\n- `GET/POST/PUT/DELETE /account/api/v1/accounts/**` - Account management\n- `GET/POST/PUT/DELETE /customer/api/v1/customers/**` - Customer management\n- `GET/POST/PUT/DELETE /transaction/api/v1/transactions/**` - Transaction management\n- `GET/POST/PUT/DELETE /ledger/api/v1/ledgers/**` - Ledger management (ADMIN only)\n- `GET/POST/PUT/DELETE /notification/api/v1/notifications/**` - Notification management\n\n## 🔍 Monitoring and Debugging\n\n### Service Discovery\n- **Eureka Dashboard**: http://localhost:8761/\n  - View all registered services\n  - Check service health status\n  - Monitor service instances\n\n### Kafka Monitoring\n- **Kafka UI**: http://localhost:4002/\n  - Monitor topics and partitions\n  - View message flow\n  - Check consumer groups\n  - Browse messages in topics\n\n- **Kafdrop**: http://localhost:9000/\n  - Alternative Kafka UI\n  - Message browsing and inspection\n\n### Health Checks\n- **API Gateway**: http://localhost:8765/actuator/health\n- **Auth Service**: http://localhost:8000/actuator/health\n- **Account Service**: http://localhost:8001/actuator/health\n- **Customer Service**: http://localhost:8002/actuator/health\n- **Notification Service**: http://localhost:8500/actuator/health\n\n## 🚨 Troubleshooting\n\n### Common Issues\n1. **\"Access token is missing or invalid\"**\n   - Ensure you're using the API Gateway (port 8765)\n   - Include `Authorization: Bearer YOUR_TOKEN` header\n   - Check if token is expired\n\n2. **\"Service not found\"**\n   - Check Eureka dashboard at http://localhost:8761/\n   - Ensure all services are running and registered\n\n3. **Kafka connection issues**\n   - Verify Kafka is running: `docker ps | grep kafka`\n   - Check Kafka UI at http://localhost:4002/\n   - Ensure notification service can connect to Kafka\n\n4. **Database connection issues**\n   - Check if PostgreSQL/MongoDB containers are running\n   - Verify database credentials in application properties","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fen-atul%2Fbanking-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fen-atul%2Fbanking-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fen-atul%2Fbanking-system/lists"}