4. Withdrawals Domain Service Extraction - Visual Architecture

# Withdrawals Domain Service Extraction - Visual Architecture This diagram shows the strategic options for extracting the withdrawals domain (owned by team DC) into an isolated microservice with dedicated database and storage. ```mermaid graph TB subgraph "CURRENT STATE - Monolith" subgraph "Team DC - Withdrawals Domain" WC[Withdrawal Core Logic 🏛️ Regulatory Processing 💰 Payment Orchestration 📊 Compliance Reporting] end subgraph "Dependencies (7 Major)" AC[Customer Account Mgmt 👤 AC Team 🔐 Profile & Auth] Shield[Bank Details/KYC 🛡️ Shield Team 🔒 Verification] Epic[Tax Calculations 🧮 Epic Team 📋 HMRC Compliance] PM[Plan Management 💼 Multi-Team 📈 Valuations] IM[Investment Mgmt 📊 DC Team 🏦 Asset Liquidation] SN[Stronger Nudge 🎯 Shared ⚠️ Intervention Logic] MC[Marketing Content 📧 Marketing Team 📢 Communications] end subgraph "Shared Database" DB[(Monolith Database Mixed Ownership Complex Dependencies)] end end subgraph "TARGET STATE OPTIONS" subgraph "� Option 1: Event-Driven Decoupling" WS2[Withdrawals Service ⚡ 4-6 months ✅ Low Risk � Shared DB + Events 🏗️ Modern Architecture Base] end subgraph "� Option 2: Gradual Domain Extraction" WS1[Withdrawals Service 🔄 8-12 months ⚠️ Medium Risk � Dedicated DB 🏗️ TypeScript Foundation] end subgraph "🔴 Option 3: Complete Isolation" WS3[Withdrawals Service 🎯 12-18 months 🚨 Medium-High Risk 🏛️ Full Independence 🏗️ Enhanced Architecture] end end subgraph "External Integrations" SF[Salesforce 📋 Heavy Integration] HMRC[HMRC API 🏛️ Tax Reporting] Banks[Bank APIs 💳 Payment Processing] Providers[Pension Providers 🏦 Asset Liquidation] end subgraph "Data Storage Options" subgraph "Option A: Dedicated Database" WDDB[(Withdrawals DB PostgreSQL Full Ownership)] end subgraph "Option B: Event Store + DB" WDDB2[(Primary DB Current State)] WDES[(Event Store Audit Trail)] end subgraph "Option C: Replicated Data" WDDB3[(Withdrawals DB Own + Replicated)] SYNC[Event-Driven Sync Real-time Updates] end end %% Current State Dependencies WC --> AC WC --> Shield WC --> Epic WC --> PM WC --> IM WC --> SN WC --> MC WC --> DB WC --> SF %% Target State Options WS1 --> WDDB WS2 --> WDDB2 WS2 --> WDES WS3 --> WDDB3 WS3 --> SYNC %% External Dependencies (all options) WS1 --> SF WS1 --> HMRC WS1 --> Banks WS1 --> Providers WS2 --> SF WS2 --> HMRC WS2 --> Banks WS2 --> Providers WS3 --> SF WS3 --> HMRC WS3 --> Banks WS3 --> Providers %% API Dependencies (target state) WS1 -.-> AC WS1 -.-> Shield WS1 -.-> Epic WS2 -.-> AC WS2 -.-> Shield WS2 -.-> Epic WS3 -.-> AC WS3 -.-> Shield WS3 -.-> Epic %% Styling classDef currentState fill:#f8d7da,stroke:#721c24,stroke-width:2px classDef optionRecommended fill:#fff3cd,stroke:#856404,stroke-width:3px classDef optionSafe fill:#d4edda,stroke:#155724,stroke-width:2px classDef optionRisky fill:#f8d7da,stroke:#721c24,stroke-width:2px classDef external fill:#e2e3e5,stroke:#495057,stroke-width:1px classDef database fill:#cce5ff,stroke:#0056b3,stroke-width:1px class WC,AC,Shield,Epic,PM,IM,SN,MC,DB currentState class WS1 optionRecommended class WS2 optionSafe class WS3 optionRisky class SF,HMRC,Banks,Providers external class WDDB,WDDB2,WDES,WDDB3,SYNC database ``` ## Extraction Strategy Comparison ```mermaid quadrantChart title Withdrawals Domain Extraction Options x-axis Low Complexity --> High Complexity y-axis Low Risk --> High Risk quadrant-1 Ideal quadrant-2 Challenging quadrant-3 Manageable quadrant-4 Avoid Event-Driven Decoupling: [0.2, 0.15] Gradual Domain Extraction: [0.5, 0.35] Complete Service Isolation: [0.8, 0.6] ``` ## Implementation Timeline Comparison ```mermaid gantt title Withdrawals Domain Extraction Timeline Options dateFormat YYYY-MM-DD section Option 1: Event-Driven Event Setup :active, phase1b, 2025-08-01, 2M Service Boundaries :phase2b, after phase1b, 2M Data Ownership :phase3b, after phase2b, 2M section Option 2: Gradual Extraction Domain Boundaries :active, phase1a, 2025-08-01, 3M Event Infrastructure :phase2a, after phase1a, 3M Service Extraction :phase3a, after phase2a, 3M section Option 3: Complete Isolation Service Foundation :active, phase1c, 2025-08-01, 5M Data Migration :phase2c, after phase1c, 6M Integration Layer :phase3c, after phase2c, 3M ``` ## Data Architecture Options ```mermaid flowchart TD subgraph "Current State" MONO[Monolith Database 🏛️ All teams share tables ❌ Complex dependencies] end subgraph "Option A: Complete Separation" WDB[Withdrawals Database ✅ Full ownership ⚠️ Data replication needed] API1[API Calls for Reference Data Real-time customer/bank data] end subgraph "Option B: Hybrid Approach" WDB2[Withdrawals Database ✅ Core withdrawal data] CACHE[Read-Only Cache Customer/bank reference data] EVENTS[Event Stream Real-time updates] end subgraph "Option C: Event Sourcing" WDB3[Withdrawals Database Current state queries] ES[Event Store Complete audit trail Regulatory compliance] RM[Read Models Optimized for queries] end MONO --> WDB MONO --> WDB2 MONO --> WDB3 WDB --> API1 WDB2 --> CACHE WDB2 --> EVENTS WDB3 --> ES ES --> RM classDef current fill:#f8d7da,stroke:#721c24 classDef recommended fill:#fff3cd,stroke:#856404 classDef complex fill:#e2e3e5,stroke:#495057 class MONO current class WDB2,CACHE,EVENTS recommended class WDB,API1,WDB3,ES,RM complex ``` ## Service Integration Patterns ```mermaid sequenceDiagram participant C as Customer participant W as Withdrawals Service participant A as Customer Service (AC) participant S as Bank Service (Shield) participant T as Tax Service (Epic) participant SF as Salesforce Note over C,SF: Option 1: Synchronous API Calls C->>W: Request Withdrawal W->>A: Validate Customer A-->>W: Customer Valid W->>S: Verify Bank Details S-->>W: Bank Verified W->>T: Calculate Tax T-->>W: Tax Calculated W->>SF: Create Withdrawal Record W-->>C: Withdrawal Approved Note over C,SF: Option 2: Event-Driven (Recommended) C->>W: Request Withdrawal W->>W: Validate Internal Rules W->>+EventBus: Publish WithdrawalRequested EventBus->>A: Customer Validation Needed EventBus->>S: Bank Verification Needed EventBus->>T: Tax Calculation Needed A-->>EventBus: Customer Validated S-->>EventBus: Bank Verified T-->>EventBus: Tax Calculated EventBus-->>-W: All Validations Complete W->>SF: Create Withdrawal Record W-->>C: Withdrawal Approved ``` ## Risk Assessment Matrix | Aspect | Event-Driven Decoupling | Gradual Domain Extraction | Complete Service Isolation | |--------|-------------------------|---------------------------|----------------------------| | **Implementation Time** | 🟢 4-6 months | 🟡 8-12 months | 🔴 12-18 months | | **Technical Complexity** | 🟡 Medium | 🟡 Medium-High | 🔴 High | | **Team Coordination** | 🟢 Moderate | 🟡 High | 🔴 Very High | | **Database Migration** | 🟢 None Required | 🟡 Gradual Migration | 🔴 Complete Migration | | **Rollback Difficulty** | 🟢 Easy | 🟡 Moderate | 🔴 Very Difficult | | **Operational Overhead** | 🟡 Medium | 🟡 Medium-High | 🔴 High | | **Business Risk** | 🟢 Low | 🟡 Medium | � Medium-High | | **Learning Value** | 🟡 Medium | 🟢 High | 🟢 Very High | | **Team Independence** | 🟡 Partial | 🟢 High | 🟢 Complete | | **Scalability Benefits** | 🟡 Limited | 🟢 Good | 🟢 Excellent | | **Modern Architecture Leverage** | 🟢 High | 🟢 High | 🟢 Very High | ## Technology Stack Recommendations ### Database Technology ```yaml PostgreSQL (Recommended): Advantages: - Team expertise exists - ACID compliance for financial data - JSON support for flexible schemas - Strong performance Implementation: - Dedicated instance for withdrawals - Read replicas for analytics - Connection pooling - Backup and disaster recovery Event Store Option: Advantages: - Perfect audit trail - Temporal queries - Regulatory compliance Disadvantages: - Learning curve - Limited query capabilities - Additional complexity ``` ### Messaging Infrastructure ```yaml Apache Kafka (Recommended): Advantages: - High throughput - Durable event storage - Multiple consumer support - Strong ordering guarantees Implementation: - Dedicated topics for withdrawal events - Schema registry for event contracts - Monitoring and alerting - Dead letter queues Alternative: RabbitMQ Advantages: - Easier initial setup - Good management UI - Flexible routing Disadvantages: - Lower throughput than Kafka - More complex clustering ``` ### API Technology ```yaml REST APIs: - Standard HTTP patterns - Easy testing and debugging - OpenAPI documentation - Rate limiting and caching GraphQL (Future consideration): - Flexible data fetching - Strong typing - Single endpoint - Better mobile performance gRPC (Internal services): - High performance - Strong typing - HTTP/2 benefits - Code generation ``` ## Success Criteria and Monitoring ### Key Performance Indicators #### Technical KPIs ```yaml Service Performance: - Response time: 95th percentile < 500ms - Availability: > 99.9% uptime - Error rate: < 0.1% - Throughput: Handle 500 requests/minute Data Quality: - Zero data inconsistencies - Event processing success > 99.9% - Complete audit trail maintained - Regulatory compliance 100% ``` #### Business KPIs ```yaml Customer Experience: - Same or faster withdrawal processing - Reduced customer support tickets - Improved error messaging - Better status visibility Team Productivity: - Faster feature delivery - Reduced cross-team dependencies - Independent deployment capability - Improved testing cycles ``` ### Monitoring Strategy ```yaml Application Monitoring: - Service health checks - Response time tracking - Error rate monitoring - Business metric tracking Infrastructure Monitoring: - Database performance - Message queue health - Network latency - Resource utilization Business Monitoring: - Withdrawal completion rates - Processing time trends - Regulatory compliance metrics - Customer satisfaction scores ``` ## Implementation Checklist ### Pre-Implementation - [ ] Executive approval and budget allocation - [ ] Cross-team working group established - [ ] Technical architecture review completed - [ ] Risk assessment and mitigation plans approved - [ ] Customer communication strategy defined ### Phase 1: Foundation - [ ] Domain boundaries clearly defined - [ ] Internal APIs implemented within monolith - [ ] Testing framework established - [ ] Monitoring and logging enhanced - [ ] Documentation created and maintained ### Phase 2: Service Extraction - [ ] Dedicated database schema created - [ ] Event infrastructure implemented - [ ] API contracts defined and agreed - [ ] Service authentication implemented - [ ] Load testing completed ### Phase 3: Production Deployment - [ ] Blue-green deployment strategy implemented - [ ] Gradual traffic migration plan executed - [ ] Performance monitoring validated - [ ] Rollback procedures tested - [ ] Team training completed ## Conclusion and Next Steps ### Recommended Approach: Event-Driven Decoupling (Leveraging Modern Architecture) **Rationale**: 1. **Lowest Risk**: No database migration required initially 2. **Fastest Time to Value**: 4-6 months vs 8-18 months for other options 3. **Modern Foundation**: Leverages existing TypeScript clean architecture 4. **Learning Opportunity**: Establish patterns for future extractions 5. **Reversible**: Easy to rollback if issues arise 6. **Foundation for Future**: Can evolve to complete isolation later ### Immediate Next Steps (Next 30 Days) 1. **Architecture Assessment**: Audit existing TypeScript contexts and identify enhancement opportunities 2. **Team Formation**: Establish cross-team working group with clear roles 3. **Technical Spike**: Proof-of-concept event infrastructure integrated with existing patterns 4. **Modern Architecture Review**: Detailed technical design review leveraging current clean architecture 5. **Project Planning**: Detailed timeline and resource allocation based on existing foundation ### Success Factors - **Clear Communication**: Regular updates to all stakeholders - **Incremental Progress**: Celebrate small wins along the way - **Customer Focus**: Maintain or improve customer experience - **Technical Excellence**: Proper testing, monitoring, and documentation - **Team Collaboration**: Strong coordination between DC, AC, Shield, and Epic teams The withdrawals domain extraction is a significant undertaking that will establish PensionBee's microservice capabilities and enable future domain extractions across the organization. ## Service Dependencies Flow ```mermaid flowchart LR subgraph "Phase 1: Proof of Concept" direction TB P1A[Unit Price Scraping 2-3 weeks 🟢 Low Risk] P1B[Waitlist Management 3-4 weeks 🟡 Medium Risk] end subgraph "Phase 2: Scale Services" direction TB P2A[RAF Service 4-5 weeks 🟡 Medium Risk] P2B[Document Generation 6-8 weeks 🟡 High Complexity] end subgraph "Phase 3: Complex Domains" direction TB P3A[Future Extraction Candidates Based on learnings] P3B[Service Mesh Cross-cutting concerns] end P1A --> P1B P1B --> P2A P2A --> P2B P2B --> P3A P3A --> P3B classDef phase1 fill:#d4edda,stroke:#155724 classDef phase2 fill:#fff3cd,stroke:#856404 classDef phase3 fill:#e2e3e5,stroke:#495057 class P1A,P1B phase1 class P2A,P2B phase2 class P3A,P3B phase3 ``` ## Risk Assessment Summary | Service | Team Ownership | External Deps | SF Coupling | DB Boundaries | Extraction Risk | |---------|---------------|---------------|-------------|---------------|-----------------| | Unit Price Scraping | ✅ Single (Web) | ✅ Minimal | ✅ Light | ✅ Dedicated | 🟢 **Low** | | RAF Service | ✅ Single (Marketing) | ⚠️ Medium | ⚠️ Medium | ✅ Dedicated | 🟡 **Medium** | | Waitlist Management | ✅ Single (Marketing) | ✅ Minimal | ✅ Light | ✅ Dedicated | 🟡 **Medium** | | Document Generation | ❌ Multi-Team | ⚠️ Medium | ❌ Heavy | ❌ Shared | 🟡 **High** | | **Withdrawals** | ❌ **Multi-Team** | ❌ **Heavy** | ❌ **Heavy** | ❌ **Shared** | 🔴 **Very High** | | Customer Account | ❌ Core Platform | ❌ Heavy | ❌ Heavy | ❌ Shared | 🔴 **Very High** | | KYC/Bank Details | ❌ Security Critical | ❌ Heavy | ❌ Heavy | ❌ Shared | 🔴 **Very High** | ## Implementation Success Factors 1. **Start Small**: Begin with Unit Price Scraping service for maximum learning 2. **Validate Patterns**: Use early services to establish microservice patterns 3. **Team Independence**: Ensure each extracted service has clear ownership 4. **Monitoring First**: Implement observability before extraction 5. **Rollback Strategy**: Maintain monolith functionality during transition