CreditX Microservice Architecture

This diagram shows the complete microservice architecture of the CreditX platform, including all services, infrastructure components, and their interactions.

Architecture Diagram

architecture-beta
    group infra(cloud)[Infrastructure Layer]
    group services(cloud)[Microservices Layer]
    group data(database)[Data Layer]
    
    service kafka(server)[Kafka Message Broker] in infra
    service zipkin(server)[Zipkin Tracing] in infra
    service oracle(database)[Oracle Database] in data
    
    service mainServ(server)[creditMainServ 8080] in services
    service holdServ(server)[creditHoldServ 8081] in services
    service postingServ(server)[creditPostingServ 8082] in services
    service promoServ(server)[creditPromoServ 8083] in services
    
    mainServ:B --> T:oracle
    holdServ:B --> T:oracle
    postingServ:B --> T:oracle
    promoServ:B --> T:oracle
    
    mainServ:R --> L:kafka
    holdServ:R --> L:kafka
    postingServ:R --> L:kafka
    promoServ:R --> L:kafka
    
    mainServ:T --> B:zipkin
    holdServ:T --> B:zipkin
    postingServ:T --> B:zipkin
    promoServ:T --> B:zipkin
    
    mainServ:R --> L:holdServ
    postingServ:L --> R:mainServ
    promoServ:L --> R:mainServ

Loading

Service Flow Diagram

sequenceDiagram
    participant Client
    participant MainServ as creditMainServ<br/>(8080)
    participant HoldServ as creditHoldServ<br/>(8081)
    participant Kafka as Kafka<br/>(holds, transactions topics)
    participant PostingServ as creditPostingServ<br/>(8082)
    participant PromoServ as creditPromoServ<br/>(8083)
    participant Oracle as Oracle DB<br/>(Separate Schemas)
    
    Note over Client,Oracle: Transaction Creation Flow
    Client->>MainServ: POST /api/transactions<br/>(Create Transaction)
    MainServ->>Oracle: Save Transaction (PENDING)
    MainServ->>HoldServ: POST /api/holds<br/>(Create Hold/Authorization)
    HoldServ->>Oracle: Check fraud, blocklist, balance
    HoldServ->>Oracle: Create Hold record
    HoldServ-->>MainServ: Hold Response (AUTHORIZED/DECLINED)
    MainServ->>Oracle: Update Transaction status
    MainServ->>Kafka: Publish transaction.authorized event<br/>(transactions topic)
    MainServ-->>Client: Transaction Response (AUTHORIZED/DECLINED)
    
    Note over Kafka,PromoServ: Async Event Processing
    
    Kafka->>PostingServ: transaction.authorized event
    PostingServ->>Oracle: Save Posting record
    PostingServ->>MainServ: POST /api/transactions/{id}/commit<br/>(Commit Transaction)
    MainServ->>Oracle: Update Transaction (POSTED)
    MainServ->>Kafka: Publish transaction.posted event<br/>(transactions topic)
    
    Kafka->>HoldServ: transaction.authorized event
    HoldServ->>Oracle: Mark Hold as VOIDED
    HoldServ->>Kafka: Publish hold.voided event<br/>(holds topic)
    
    Kafka->>PromoServ: transaction.posted event
    PromoServ->>Oracle: Check eligible promotions
    PromoServ->>Oracle: Calculate cashback
    PromoServ->>MainServ: POST /api/transactions/cashback<br/>(Create Cashback Transaction)
    MainServ->>Oracle: Create cashback transaction
    PromoServ->>Oracle: Save promotion application
    
    Note over HoldServ,Oracle: Hold Expiry (Scheduled)
    HoldServ->>Oracle: Check expired holds (every 5 min)
    HoldServ->>Oracle: Mark expired holds
    HoldServ->>Kafka: Publish hold.expired events<br/>(holds topic)
    Kafka->>MainServ: hold.expired event
    MainServ->>Oracle: Update Transaction (EXPIRED)

Loading

Component Details

creditMainServ (Port 8080)

Role: Transaction orchestration and workflow management

REST Endpoints:

• POST /api/transactions - Create inbound transaction
• POST /api/transactions/{id}/commit - Commit transaction (internal)
• POST /api/transactions/cashback - Create cashback transaction (internal)

Kafka Producers:

• Publishes to transactions topic:
  • transaction.authorized events
  • transaction.posted events
  • transaction.failed events

Kafka Consumers:

• Listens to holds topic:
  • hold.created events
  • hold.expired events
  • hold.voided events

HTTP Clients:

• Calls creditHoldServ to create holds

Database: Oracle schema MAIN (managed by Flyway flyway_schema_history_cms)

---

creditHoldServ (Port 8081)

Role: Hold authorization, fraud detection, and blocklist enforcement

REST Endpoints:

• POST /api/holds - Create hold/authorization (internal)

Kafka Producers:

• Publishes to holds topic:
  • hold.created events
  • hold.expired events
  • hold.voided events

Kafka Consumers:

• Listens to transactions topic:
  • transaction.authorized events
  • transaction.posted events
  • transaction.failed events

Scheduled Jobs:

• Hold expiry checker (runs every 5 minutes - 300,000ms)
• Publishes expired holds via outbox pattern

Database: Oracle schema HOLD (managed by Flyway flyway_schema_history_chs)

---

creditPostingServ (Port 8082)

Role: Transaction settlement and posting

Kafka Consumers:

• Listens to transactions topic:
  • transaction.authorized events

Kafka Producers:

• Publishes to transactions topic (via outbox pattern)

HTTP Clients:

• Calls creditMainServ to commit transactions
  • POST /api/transactions/{id}/commit

Database: Oracle schema POST (managed by Flyway flyway_schema_history_cps)

---

creditPromoServ (Port 8083)

Role: Promotion evaluation and cashback calculation

Kafka Consumers:

• Listens to transactions topic:
  • transaction.posted events

Kafka Producers:

• Publishes to promotions topic (via outbox pattern)

HTTP Clients:

• Calls creditMainServ to create cashback transactions
  • POST /api/transactions/cashback

Database: Oracle schema PROMO (managed by Flyway flyway_schema_history_cprs)

---

Infrastructure Components

Kafka (Port 9092)

• Topics:

  • transactions - Transaction lifecycle events
  • holds - Hold lifecycle events
  • promotions - Promotion/cashback events

• Pattern: Event-driven architecture with transactional outbox pattern

• Replication: Single broker setup (replication factor 1)

Oracle Database (Port 1521)

• Service: FREEPDB1
• Schemas: Separate schema per microservice (MAIN, HOLD, POST, PROMO)
• Migration: Flyway for schema versioning
• Initialization: Custom init scripts in /docker-entrypoint-initdb.d/

Zipkin (Port 9411)

• Purpose: Distributed tracing across all microservices
• Integration: Spring Cloud Sleuth with 100% sampling
• Storage: In-memory (for development)

---

Key Architectural Patterns

1. Transactional Outbox Pattern

All services use an outbox table to ensure reliable event publishing:

• Events are saved to DB in same transaction as business logic
• Background scheduler polls outbox and publishes to Kafka
• Ensures at-least-once delivery guarantee

2. Event-Driven Communication

• Asynchronous: Services communicate via Kafka events
• Synchronous: REST calls only for request-response patterns (Hold creation, Commit, Cashback)

3. Database per Service

Each microservice has its own Oracle schema:

• Loose coupling and independent deployment
• Schema migrations managed independently via Flyway

4. Saga Pattern

Transaction flow implements choreography-based saga:

• MainServ orchestrates initial authorization
• PostingServ commits authorized transactions
• PromoServ applies promotions to posted transactions
• Compensating transactions for failures (hold.expired, transaction.failed)

5. Service Discovery

• No service registry (Eureka/Consul)
• Direct service-to-service HTTP calls via environment variables
• Container networking via Docker Compose

---

Event Flow Summary

Transaction Authorization Flow

1. Client → MainServ: Create transaction
2. MainServ → HoldServ: Create hold (HTTP)
3. HoldServ → Kafka: Publish hold.created
4. MainServ → Kafka: Publish transaction.authorized
5. MainServ → Client: Return response

Transaction Settlement Flow

6. Kafka → PostingServ: Consume transaction.authorized
7. PostingServ → MainServ: Commit transaction (HTTP)
8. MainServ → Kafka: Publish transaction.posted

Hold Cleanup Flow

9. Kafka → HoldServ: Consume transaction.authorized
10. HoldServ: Mark hold as voided
11. HoldServ → Kafka: Publish hold.voided

Promotion Flow

12. Kafka → PromoServ: Consume transaction.posted
13. PromoServ: Calculate eligible cashback
14. PromoServ → MainServ: Create cashback transaction (HTTP)
15. MainServ: Process cashback as new transaction

Expiry Flow

16. HoldServ Scheduler: Check expired holds
17. HoldServ → Kafka: Publish hold.expired
18. Kafka → MainServ: Consume hold.expired
19. MainServ: Update transaction to EXPIRED

---

Technology Stack

• Language: Java (Spring Boot)
• Framework: Spring Cloud Stream, Spring Data JPA, Spring Web
• Messaging: Apache Kafka (Confluent Platform)
• Database: Oracle Database 23c Free
• Schema Migration: Flyway
• Tracing: Zipkin + Spring Cloud Sleuth
• API Documentation: OpenAPI 3.0 (Springdoc)
• Build Tool: Maven
• Containerization: Docker + Docker Compose