# mudassarhakim/common-debit-card architecture

> Architecture diagram of the GitHub repository mudassarhakim/common-debit-card, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mudassarhakim/common-debit-card
- Repository: https://github.com/mudassarhakim/common-debit-card

## Overview

##### Project type and purpose
- This is a full-stack, event-driven microservices system for managing debit-card metadata.
- It comprises two Spring Boot microservices:
- **Card Repo Service** (internal, Kafka consumer + MySQL + sync)
- **Cards Microservice** (public REST API, facade + circuit breaker + Redis cache)

##### File structure
- Top-level modules:
- **card-repo/** – Spring Boot service, consumes Kafka events, persists to MySQL, syncs to Customer360.
- **cards-service/** – Spring Boot web service, exposes REST endpoints, uses circuit breaker and Redis.
- Shared root files:
- **docker-compose.yml** – brings up MySQL, Kafka, Zookeeper, Redis.
- **pom.xml** – multi-module Maven parent.
- **docs/** & **postman/** – integration guides, API tests.
- Patterns visible:
- Event-driven ingestion (Spring Kafka consumer).
- Persistence via Spring Data JPA.
- DTO layering (controller-dto-entity).
- Circuit breaker (Resilience4j) in the public API.
- Docker Compose for infrastructure orchestration.

##### README for additional insights
- Two main microservices with clearly defined responsibilities.
- Technology stack: Java 17, Spring Boot 3, Kafka, MySQL, Redis, Resilience4j.
- Infrastructure: Docker Compose includes Kafka & Zookeeper, MySQL, Redis.
- Provides high-level flow: produce card events → card-repo consumes → store and sync → cards-service facades and serves public APIs → frontends.

##### Elements
- Clear labels for each component (e.g., “CardEventConsumer,” “CardController,” “MySQL”).
- From Kafka → Card Repo
- From Card Repo → MySQL
- From Card Repo → Customer360 Sync
- From Clients → Cards Service → Redis → Card Repo → Redis → Clients
- Internal service (card-repo) in blue
- Public service (cards-service) in green
- External Clients in orange

##### Detailed capture of essential architectural elements
- Docker Compose as the deployment boundary, with all infra components grouped under it.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef infra fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef internal fill:#D6EAF8,stroke:#333,stroke-width:1px
    classDef public fill:#D5F5E3,stroke:#333,stroke-width:1px
    classDef external fill:#FCF3CF,stroke:#333,stroke-width:1px

    subgraph "External Clients" 
        direction TB
        Clients["Clients\n(UI / Mobile / Postman)"]:::external
    end

    subgraph "Infrastructure (Docker Compose)" 
        direction TB
        ZK["Zookeeper"]:::infra
        Kafka["Kafka Cluster\nTopic: card-events"]:::infra
        MySQL["MySQL Database"]:::infra
        RedisInfra["Redis Cache"]:::infra
    end

    subgraph "card-repo (Internal Service)" 
        direction TB
        CRApp["CardRepoApplication"]:::internal
        CardConsumer["CardEventConsumer"]:::internal
        InternalAPI["InternalCardController\n(/internal/cards)"]:::internal
        DTOs["DTOs\nCardEventDto, CardResponseDto"]:::internal
        Repo["CardRepository\n(JPA)"]:::internal
        CardEntity["Card Entity"]:::internal
        C360["C360SyncService"]:::internal
    end

    subgraph "cards-service (Public Service)" 
        direction TB
        CSApp["CardsServiceApplication"]:::public
        Controller["CardController\n(/cards, /cards/eligible)"]:::public
        Integration["CardIntegrationService"]:::public
        Fallback["GlobalExceptionHandler\n(Resilience4j Fallback)"]:::public
    end

    Clients -->|"POST events"| Kafka
    Kafka -->|"consume events"| CardConsumer
    CardConsumer -->|"save/update"| Repo
    Repo -->|"persist"| MySQL
    CardConsumer -->|"Sync → C360"| C360

    Clients -->|"HTTP GET /cards"| Controller
    Controller -->|"check cache"| RedisInfra
    RedisInfra -->|"cache miss"| Integration
    Integration -->|"HTTP call"| InternalAPI
    InternalAPI -->|"fetch data"| Repo
    Repo -->|"read data"| MySQL
    Integration -->|"cache result"| RedisInfra
    RedisInfra -->|"return cached"| Controller

    %% Click Events infra
    click ZK "https://github.com/mudassarhakim/common-debit-card/blob/main/docker-compose.yml"
    click Kafka "https://github.com/mudassarhakim/common-debit-card/blob/main/docker-compose.yml"
    click MySQL "https://github.com/mudassarhakim/common-debit-card/blob/main/docker-compose.yml"
    click RedisInfra "https://github.com/mudassarhakim/common-debit-card/blob/main/docker-compose.yml"

    %% Click Events card-repo
    click CRApp "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/CardRepoApplication.java"
    click CardConsumer "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/consumer/CardEventConsumer.java"
    click InternalAPI "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/controller/InternalCardController.java"
    click DTOs "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/dto/CardEventDto.java"
    click Repo "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/repository/CardRepository.java"
    click CardEntity "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/entity/Card.java"
    click C360 "https://github.com/mudassarhakim/common-debit-card/blob/main/card-repo/src/main/java/com/example/cardrepo/service/C360SyncService.java"

    %% Click Events cards-service
    click CSApp "https://github.com/mudassarhakim/common-debit-card/blob/main/cards-service/src/main/java/com/example/cardsservice/CardsServiceApplication.java"
    click Controller "https://github.com/mudassarhakim/common-debit-card/blob/main/cards-service/src/main/java/com/example/cardsservice/controller/CardController.java"
    click Integration "https://github.com/mudassarhakim/common-debit-card/blob/main/cards-service/src/main/java/com/example/cardsservice/service/CardIntegrationService.java"
    click Fallback "https://github.com/mudassarhakim/common-debit-card/blob/main/cards-service/src/main/java/com/example/cardsservice/exception/GlobalExceptionHandler.java"

    class Clients external
    class ZK,Kafka,MySQL,RedisInfra infra
    class CRApp,CardConsumer,InternalAPI,DTOs,Repo,CardEntity,C360 internal
    class CSApp,Controller,Integration,Fallback public
```
