Purpose
This document captures the current state, target state, and migration path for each area of the Convenient Checkout v2 platform. In a highly regulated payments industry, engineering excellence is not optional — it directly impacts compliance, reliability, customer trust, and speed of delivery.
Every improvement listed here is grounded in industry best practices for payment platforms: data protection, observability-driven operations, schema-first API development, and domain-driven design.
Roadmap Summary
Phase 1 — Foundation (Current Focus)
1. Commons Library Consolidation
| Aspect | Current State | Target State |
|---|
| Package structure | v1 DTOs in event/, v2 DTOs in events/v2/, POJOs in pojo/ — significant overlap | Single v2/ package hierarchy; event/ and pojo/ deprecated |
| Enum duplication | PaymentStatus exists in both enums.payment and event.shared.payment | Single canonical location in enums/ |
| v1/v2 coexistence | Both ErrorResponse (v1) and Problem (v2) actively consumed | All services migrated to Problem; ErrorResponse deprecated |
| Javadoc | Partial — some classes documented, some not | 100% of public classes and enums documented |
Migration Steps:
- Audit all services for v1 DTO usage → produce dependency matrix
- Create
@Deprecated annotations on all v1 classes with Javadoc pointing to v2 replacement
- Service-by-service migration: replace v1 imports with v2 equivalents
- Remove deprecated v1 classes after all services migrated (min 2-sprint window)
- Clean up duplicate enums — keep
enums/ as the canonical source
2. Error Model Unification
| Aspect | Current State | Target State |
|---|
| Error response DTO | ErrorResponse (v1) with ErrorDetails and ErrorGroup → Problem (v2) with RFC 7807 alignment | Problem as the only error response DTO |
| Error propagation | Inconsistent: some services return raw exception messages | All errors flow through Problem.from(ErrorResponse) or factory methods |
| Error codes | JSON files in docs site (payment-api.json, refund-api.json) | JSON files as source of truth; generated documentation |
Migration Steps:
- Ensure all v2 controller exception handlers return
Problem instances
- Replace all raw
ErrorResponse returns with Problem.from() conversions
- Add
Problem builder validation: status must match title semantics
- Update all integration tests to assert against
Problem structure
Phase 2 — Quality & Observability
3. Domain Boundary Enforcement
| Aspect | Current State | Target State |
|---|
| Service responsibilities | Some services handle concerns from multiple domains | Each service owns a single bounded context |
| Cross-service communication | Direct REST calls + shared database access in some cases | Event-driven communication; no shared databases |
| Commons coupling | Services depend on DTOs they don't need | Domain-specific commons modules (e.g., commons-payment, commons-merchant) |
Migration Steps:
- Map current cross-domain dependencies per service
- Identify and extract domain-specific modules from
wallet-event-commons
- Implement anti-corruption layers at service boundaries
- Replace any shared database access with API calls or events
4. Test Coverage & Contract Testing
| Aspect | Current State | Target State |
|---|
| Unit test coverage | Varies by service (30-80%) | ≥80% on all services, enforced in CI |
| Integration tests | Present but inconsistent | Testcontainers-based, running on every PR |
| Contract tests | Not consistently applied | Consumer-driven contracts between all service pairs |
| Webhook schema validation | Manual | Automated validation against openapi/v2/webhooks.yaml |
Migration Steps:
- Add JaCoCo coverage reporting to all service CI pipelines
- Set minimum coverage gates (fail build below threshold)
- Implement Pact or Spring Cloud Contract for inter-service contracts
- Add webhook payload schema validation in integration tests
5. Observability & Structured Logging
| Aspect | Current State | Target State |
|---|
| Logging | Mixed format; some structured, some freeform | 100% structured JSON logging with standard fields across all services |
| Correlation IDs | Partially propagated | Full X-Request-Id propagation across all service hops |
| Azure Application Insights | Basic integration | Full distributed tracing with custom dimensions (merchantId, resourceId, requestId) on all telemetry |
| Splunk | Logs shipped but inconsistent format | Structured JSON logs with standardized fields; operational dashboards per service |
| Dashboards | Limited | Per-domain dashboards in Splunk and Application Insights: success rate, latency P50/P95/P99, error rate by code |
| Alerting | Ad-hoc | Standardized actionable alerts: error rate, latency, availability, dependency health |
| Sensitive data in logs | Manual review | Automated sensitive-field detection in log pipelines |
Migration Steps:
- Standardize logging library and structured JSON format across all services
- Implement
X-Request-Id propagation middleware in every service
- Add custom dimensions to Application Insights telemetry (
merchantId, resourceId, requestId)
- Build per-domain dashboards in Splunk and Application Insights
- Configure actionable alerts with proper severity levels and escalation paths
- Add log scanning for sensitive data in CI
See the Observability guide for the full standards.
Phase 3 — Excellence
6. Schema-First API Development
| Aspect | Current State | Target State |
|---|
| API design | Code-first; OpenAPI spec maintained manually | Schema-first: OpenAPI spec is the source of truth |
| Request validation | Bean validation annotations; manually synchronized with spec | Generated validators from OpenAPI schema |
| Response contracts | Manually maintained DTOs | Generated response models from schema |
7. Event-Driven Architecture
| Aspect | Current State | Target State |
|---|
| Event publishing | Webhooks dispatched synchronously from service | Async event bus (Kafka/SQS) with webhook adapter |
| Audit trail | Database records with timestamps | Full event sourcing for payment state changes |
| Replay capability | Not available | Ability to replay events for debugging or reconciliation |
8. Automated Compliance Checks
| Aspect | Current State | Target State |
|---|
| Security scanning | Manual code review | Automated SAST rules for sensitive data patterns |
| Dependency scanning | Basic | Automated CVE scanning with blocking gates |
| Secret detection | Manual | Pre-commit hooks + CI scanning for secrets/keys |
| Audit log verification | Manual | Automated tests verifying all state transitions produce audit records |
Measuring Progress
| Metric | Current | Phase 1 Target | Phase 2 Target | Phase 3 Target |
|---|
| v1 DTO usage (count of imports) | ~150+ across services | < 50 | 0 | 0 |
| Unit test coverage (avg) | ~55% | 65% | 80% | 85% |
| Contract test coverage | 0 service pairs | 2 pairs | All pairs | All pairs |
| Structured logging adoption | ~40% of services | 60% | 100% | 100% |
| Sensitive data log violations (monthly) | Unknown | Tracked | < 5 | 0 |
| Mean time to detect (MTTD) | ~30 min | 15 min | 5 min | < 2 min |