# jaruizes-paradigma/fraud-checker-kstreams-springboot architecture

> Architecture diagram of the GitHub repository jaruizes-paradigma/fraud-checker-kstreams-springboot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jaruizes-paradigma/fraud-checker-kstreams-springboot
- Repository: https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot

## Overview

##### Project type and purpose
- This is a streaming data pipeline / microservices project for real‐time fraud detection using Kafka Streams.
- Two Spring Boot applications:
- Movement Generator (a REST‐exposed producer of “movements”)
- Fraud Checker (a Kafka Streams consumer/processor that emits “fraud‐cases”)
- A Docker‐Compose “platform” orchestrates Zookeeper, Kafka broker, Kafka UI, and the two services for a live demo.

##### File structure
- Top‐level folders:
- apps/fraud-checker-generator → Spring Boot app exposing REST endpoints and publishing Movement events to Kafka.
- apps/fraud-checker → Kafka Streams Processor API application that consumes “movements,” applies fraud‐detection topologies, and outputs “fraud-cases.”
- platform/docker-compose.yml → defines containers (ZK, Kafka, UI, both apps).
- demo → shell scripts to build images and drive the demo.
- Each app follows Maven layout, has config classes (KafkaProducerConfig, KafkaStreamsConfig), controllers/models/serializers, and resource property files.

##### README for additional insights
- The README explains the use case, motivation, and desired patterns to detect (multiple ATM events, volume thresholds, cross‐device within time windows).
- It clarifies that movements arrive real‐time to a topic “movements” → Fraud Checker processes stream → suspicious events go to topic “fraud-cases.”
- It describes demo orchestration with Docker Compose and client scripts.

a. Main components
- Client (script or UI invoking the Movement Generator REST API)
- Movement Generator Service
- Kafka Cluster (Zookeeper + Broker)
- Fraud Checker Service (Kafka Streams Application)
- Kafka UI (external viewer for topics)
- Docker Network (platform_default)
b. Relationships & data flows
1. Client → Movement Generator (HTTP POST /movements)
2. Movement Generator → Kafka (“movements” topic)
3. Fraud Checker subscribes to “movements” topic
4. Fraud Checker applies topologies (aggregation, windowing, multi‐stage Processor nodes)
5. On detection, Fraud Checker → Kafka (“fraud-cases” topic)
6. Kafka UI reads both topics for debugging/monitoring
c. Architectural patterns & design principles
- Event‐driven, reactive microservices
- Kafka Streams DSL / Processor API for stateful stream processing
- Containerization via Docker Compose for reproducible environments
- Separation of concerns: REST API producer vs. stream processor
d. Key technologies/frameworks
- Java 11, Spring Boot
- Apache Kafka + Kafka Streams
- Maven for build
- Docker & Docker Compose
- Kafka UI (for topic inspection)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entities
    Client["Client (demo script)"]:::client
    subgraph "platform_default network"
        direction TB
        MG["MovementGeneratorApp\n(REST Producer)"]:::service
        FC["FraudCheckerApp\n(Kafka Streams)"]:::service
        ZK["Zookeeper"]:::infra
        KB["Kafka Broker\n(movements & fraud-cases)"]:::kafka
        MovementsTopic[/"movements topic"/]:::kafka
        FraudCasesTopic[/"fraud-cases topic"/]:::kafka
        KUI["Kafka UI"]:::ui
        DC["docker-compose.yml"]:::infra
    end
    Demo["Demo Scripts"]:::docs
    Doc["Doc Scenarios"]:::docs

    %% Relationships
    Client -->|"HTTP POST /movements"| MG
    MG -->|"produces"| MovementsTopic
    MovementsTopic -->|"consumes"| FC
    FC -->|"produces"| FraudCasesTopic
    KB --> KUI
    KB --> MovementsTopic
    KB --> FraudCasesTopic
    ZK --> KB

    %% Demo & Docs
    Demo --> Client
    Doc --> Client

    %% Click Events
    click MG "https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot/tree/main/apps/fraud-checker-generator"
    click FC "https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot/tree/main/apps/fraud-checker"
    click DC "https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot/blob/main/platform/docker-compose.yml"
    click Demo "https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot/tree/main/demo"
    click Doc "https://github.com/jaruizes-paradigma/fraud-checker-kstreams-springboot/tree/main/doc/scenarios"

    %% Styles
    classDef client fill:#e2f7e2,stroke:#2d7d2d,color:#2d7d2d;
    classDef service fill:#e0ebff,stroke:#3357a3,color:#3357a3;
    classDef kafka fill:#ffe0b3,stroke:#cc8400,color:#663d00;
    classDef infra fill:#f2f2f2,stroke:#666666,color:#333333;
    classDef ui fill:#e2f7e2,stroke:#2d7d2d,color:#2d7d2d;
    classDef docs fill:#f9e6ff,stroke:#a64dff,color:#4d004d;
```
