---
# System prepended metadata

title: 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<br/>🏛️ Regulatory Processing<br/>💰 Payment Orchestration<br/>📊 Compliance Reporting]
        end

        subgraph "Dependencies (7 Major)"
            AC[Customer Account Mgmt<br/>👤 AC Team<br/>🔐 Profile & Auth]
            Shield[Bank Details/KYC<br/>🛡️ Shield Team<br/>🔒 Verification]
            Epic[Tax Calculations<br/>🧮 Epic Team<br/>📋 HMRC Compliance]
            PM[Plan Management<br/>💼 Multi-Team<br/>📈 Valuations]
            IM[Investment Mgmt<br/>📊 DC Team<br/>🏦 Asset Liquidation]
            SN[Stronger Nudge<br/>🎯 Shared<br/>⚠️ Intervention Logic]
            MC[Marketing Content<br/>📧 Marketing Team<br/>📢 Communications]
        end

        subgraph "Shared Database"
            DB[(Monolith Database<br/>Mixed Ownership<br/>Complex Dependencies)]
        end
    end

    subgraph "TARGET STATE OPTIONS"
        subgraph "� Option 1: Event-Driven Decoupling"
            WS2[Withdrawals Service<br/>⚡ 4-6 months<br/>✅ Low Risk<br/>� Shared DB + Events<br/>🏗️ Modern Architecture Base]
        end

        subgraph "� Option 2: Gradual Domain Extraction"
            WS1[Withdrawals Service<br/>🔄 8-12 months<br/>⚠️ Medium Risk<br/>� Dedicated DB<br/>🏗️ TypeScript Foundation]
        end

        subgraph "🔴 Option 3: Complete Isolation"
            WS3[Withdrawals Service<br/>🎯 12-18 months<br/>🚨 Medium-High Risk<br/>🏛️ Full Independence<br/>🏗️ Enhanced Architecture]
        end
    end

    subgraph "External Integrations"
        SF[Salesforce<br/>📋 Heavy Integration]
        HMRC[HMRC API<br/>🏛️ Tax Reporting]
        Banks[Bank APIs<br/>💳 Payment Processing]
        Providers[Pension Providers<br/>🏦 Asset Liquidation]
    end

    subgraph "Data Storage Options"
        subgraph "Option A: Dedicated Database"
            WDDB[(Withdrawals DB<br/>PostgreSQL<br/>Full Ownership)]
        end

        subgraph "Option B: Event Store + DB"
            WDDB2[(Primary DB<br/>Current State)]
            WDES[(Event Store<br/>Audit Trail)]
        end

        subgraph "Option C: Replicated Data"
            WDDB3[(Withdrawals DB<br/>Own + Replicated)]
            SYNC[Event-Driven Sync<br/>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<br/>🏛️ All teams share tables<br/>❌ Complex dependencies]
    end

    subgraph "Option A: Complete Separation"
        WDB[Withdrawals Database<br/>✅ Full ownership<br/>⚠️ Data replication needed]
        API1[API Calls for Reference Data<br/>Real-time customer/bank data]
    end

    subgraph "Option B: Hybrid Approach"
        WDB2[Withdrawals Database<br/>✅ Core withdrawal data]
        CACHE[Read-Only Cache<br/>Customer/bank reference data]
        EVENTS[Event Stream<br/>Real-time updates]
    end

    subgraph "Option C: Event Sourcing"
        WDB3[Withdrawals Database<br/>Current state queries]
        ES[Event Store<br/>Complete audit trail<br/>Regulatory compliance]
        RM[Read Models<br/>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<br/>2-3 weeks<br/>🟢 Low Risk]
        P1B[Waitlist Management<br/>3-4 weeks<br/>🟡 Medium Risk]
    end

    subgraph "Phase 2: Scale Services"
        direction TB
        P2A[RAF Service<br/>4-5 weeks<br/>🟡 Medium Risk]
        P2B[Document Generation<br/>6-8 weeks<br/>🟡 High Complexity]
    end

    subgraph "Phase 3: Complex Domains"
        direction TB
        P3A[Future Extraction Candidates<br/>Based on learnings]
        P3B[Service Mesh<br/>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