{"id":31879409,"url":"https://github.com/jaynightmare/settlement-reconciliation-microservice","last_synced_at":"2025-10-13T00:29:17.952Z","repository":{"id":315989278,"uuid":"1061497586","full_name":"JayNightmare/Settlement-Reconciliation-Microservice","owner":"JayNightmare","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-22T02:10:30.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T04:48:02.571Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/JayNightmare.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-22T02:06:54.000Z","updated_at":"2025-09-22T02:10:34.000Z","dependencies_parsed_at":"2025-09-22T04:17:04.805Z","dependency_job_id":"156f7139-7d12-400a-a44c-e0ea6ccf464e","html_url":"https://github.com/JayNightmare/Settlement-Reconciliation-Microservice","commit_stats":null,"previous_names":["jaynightmare/settlement-reconciliation-microservice"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/JayNightmare/Settlement-Reconciliation-Microservice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayNightmare%2FSettlement-Reconciliation-Microservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayNightmare%2FSettlement-Reconciliation-Microservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayNightmare%2FSettlement-Reconciliation-Microservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayNightmare%2FSettlement-Reconciliation-Microservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JayNightmare","download_url":"https://codeload.github.com/JayNightmare/Settlement-Reconciliation-Microservice/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JayNightmare%2FSettlement-Reconciliation-Microservice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279013645,"owners_count":26085298,"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-10-12T02:00:06.719Z","response_time":53,"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":[],"created_at":"2025-10-13T00:29:14.240Z","updated_at":"2025-10-13T00:29:17.934Z","avatar_url":"https://github.com/JayNightmare.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Settlement Reconciliation Microservice\n\nProduction-ready Spring Boot 3 microservice that ingests trade and ledger transactions, performs settlement reconciliation, and exposes APIs for operations teams at a Tier-1 bank scale.\n\n## Features\n- Spring Batch ingestion pipeline (CSV today, extensible to S3/Azure Blob) for trades and ledger feeds\n- Reconciliation engine with currency-aware tolerances, mismatch persistence, and Kafka event publishing\n- REST APIs to trigger reconciliation, inspect and resolve mismatches, and orchestrate ingestion\n- Scheduled nightly run and SLA-driven escalation emails for unresolved mismatches\n- OAuth2/JWT protected endpoints with role-based access (`OPS_ANALYST`, `ADMIN`)\n- Observability via Micrometer metrics, health checks, and structured logging conventions\n- PostgreSQL persistence with Flyway migrations; Docker Compose stack for local dependencies\n- CI-ready: Maven build, Spotless formatting, Testcontainers integration tests, GitHub Actions workflow\n\n## Getting Started\n1. **Prerequisites**: Java 24, Maven 3.9+, Docker, Docker Compose, local SMTP stub (optional).\n2. **Bootstrap dependencies**: `docker compose up -d` (spins up PostgreSQL, Kafka, Schema Registry).\n3. **Build \u0026 test**: `mvn clean verify` (integration tests require Docker for Testcontainers).\n4. **Run the app**: `mvn spring-boot:run` or build the JAR and run via Docker: `docker build -t settlement-service . \u0026\u0026 docker run --rm -p 8080:8080 settlement-service`.\n5. **Explore APIs**: Swagger UI at `http://localhost:8080/swagger-ui/index.html`, health checks at `/actuator/health`.\n\n## Configuration\nKey configuration lives in `src/main/resources/application.yaml` and supports environment overrides through variables.\n\n| Property | Description |\n| --- | --- |\n| `reconciliation.tolerances` | Currency-specific amount tolerance before flagging a mismatch |\n| `reconciliation.kafka.mismatch-topic` | Kafka topic for mismatch events |\n| `reconciliation.escalation.sla` | Duration before unresolved mismatches are escalated (ISO-8601 duration) |\n| `spring.kafka.bootstrap-servers` | Kafka bootstrap servers (default `localhost:9092`) |\n| `spring.datasource.*` | PostgreSQL connection configuration |\n| `spring.security.oauth2.resourceserver.jwt.*` | Configure issuer/public key for JWT validation |\n\nSecrets (DB password, OAuth issuer, SMTP credentials) should be supplied via environment variables or secret managers (e.g., Vault, Azure Key Vault) before deployment.\n\n## Architecture Highlights\n- **Layers**: REST controllers → service layer → repositories/entities (Spring Data JPA)\n- **Batch ingestion**: Configured in `SettlementBatchConfiguration`, using `IngestionSourceProvider` to abstract storage. Default implementation reads sample CSVs on the classpath for local demos.\n- **Reconciliation**: `DefaultReconciliationService` compares trade vs ledger records, records mismatches, emits Kafka events, and surfaces metrics.\n- **Scheduling**: `ReconciliationScheduler` orchestrates nightly ingestion/reconciliation and SLA escalation emails.\n- **Security**: `SecurityConfig` enables JWT resource server and method-level role checks. Map Keycloak-style `realm_access.roles` into Spring Security authorities.\n- **Observability**: Micrometer timers/counters for reconciliation runs (`reconciliation.run.*`) plus mismatch counters by type.\n\n## Testing\n- **Unit / Integration**: `ReconciliationServiceIntegrationTest` uses Testcontainers-backed PostgreSQL to validate reconciliation flow end-to-end.\n- **Formatting**: Spotless (Google Java Format) enforced via `mvn spotless:apply` and CI check.\n- **Profiles**: Tests run with `application-test.yaml` profile to keep logging quiet and disable batch autostart.\n\n## CI/CD\nGitHub Actions workflow (`.github/workflows/ci.yml`) compiles, runs tests, and enforces formatting on every push/PR targeting `main`. Easily extend with static analysis (SonarQube) or deployment stages.\n\n## Next Steps\n- Integrate with object storage SDK (S3/Azure) by providing a production `IngestionSourceProvider` implementation.\n- Wire Kafka producer to Barclays schema registry and Avro/Protobuf schema evolution policies.\n- Expand Testcontainers coverage for Kafka, add contract tests for REST endpoints, and include performance baselines.\n- Harden reconciliation by supporting multi-leg trades, portfolio filters, and operator workflow audit trails.\n\n## License\nInternal project template for demonstration purposes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaynightmare%2Fsettlement-reconciliation-microservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaynightmare%2Fsettlement-reconciliation-microservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaynightmare%2Fsettlement-reconciliation-microservice/lists"}