# hxh1234/projext-test architecture

> Architecture diagram of the GitHub repository hxh1234/projext-test, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hxh1234/projext-test
- Repository: https://github.com/hxh1234/projext-test

## Overview

##### Project type and purpose
- This is a standalone backend microservice (Spring Boot / Maven) whose job is to process seller-pricing requests, schedule invoice generation, persist data, and emit invoice events. It does not include a UI—it exposes REST endpoints and listens to Kafka topics.

##### File structure
- Top level: configuration files (pom.xml, Dockerfile, docker-compose.yml, Makefile), CI/CD workflows under .github/workflows, and docs.
- src/main/java: a single Spring Boot application (“Application.java”), subdivided into packages:
- configuration (Spring beans, Kafka, Mongo, caching, scheduling)
- controller (REST API layer with exception handlers)
- domain (JPA-style entities / Mongo documents, enums)
- dto (data transfer objects for external APIs: FIT, MailBrew, Salesforce, Seller API)
- kafka (consumer & producer classes)
- mapper (DTO ↔ domain mapping)
- model (internal models used within handlers and services)
- repository (Spring Data Mongo repositories)
- rest/resources (client wrappers for external HTTP services)
- schedule (scheduled jobs for DAC7, pricing, notifications)
- service (business logic, orchestrations, file upload/download, BigQuery integration, caching)
- service/handler (strategy handlers for different pricing flows)
- src/main/resources: Spring profiles, logging, SQL for initial data load
- Tests mirror the same packages plus dedicated test DB dockerfile and init scripts.

##### README
- The README is empty, so we infer architecture purely from code structure and existing docs in docs/pricing-request.

- Kafka cluster (topics: seller-pricing-requests, subscribed pricing updates, seller-invoice-events)
- REST API layer (Controller package serving inbound HTTP requests)
- Business layer (Service & Handler packages orchestrating flows)
- Data persistence (MongoDB for domain data, plus BigQuery for analytics)
- Scheduling subsystem (cron jobs for DAC7 notif., pricing calculations)
- External services:
– Seller API (v3) for seller info
– Salesforce ACL API
– FIT API for invoice requests
– MailBrew API for emailing invoices
– Google Cloud Storage / BigQuery for file I/O
b. Relationships & interactions
- REST Controller → Service → Repository → MongoDB
- Kafka Consumer → Service/Handler → Repository → emit Kafka Producer events
- Scheduled Jobs → Service layer → external services and repository
- Service calls out via REST clients (rest/resources) to FIT / Salesforce / MailBrew / Seller API / GCP
- Optional cache (Caffeine) between Service and Repository/External APIs
c. Architectural patterns & principles
- Layered architecture: Controller → Service → Repository
- Hexagonal/Ports & Adapters: rest/resources and kafka packages are adapters for external I/O
- Strategy pattern: Service/handler package defines interchangeable pricing request handlers
- Event-driven: Kafka for decoupling inbound requests and outbound invoice events
- Scheduled tasks: Spring @Scheduled for timed jobs
d. Key technologies & frameworks
- Spring Boot (web, data-mongodb, kafka, scheduling)
- Spring Data MongoDB
- Apache Kafka
- Caffeine cache
- Google Cloud BigQuery and Storage (via GCP libraries)
- Lombok, Avro serializers in tests
- Docker & Docker-compose for local dev (Mongo, Kafka, schema registry)

→ inbound HTTP POST → controller → service → repo → Mongo
→ Kafka topic → consumer → handler → producer → Kafka topic
→ scheduled trigger → service → external API
→ service → BigQuery / GCS
– Blue: core microservice packages (Controller / Service / Repository)
– Green: message broker (Kafka)
– Orange: external HTTP services
– Yellow: data stores (MongoDB, BigQuery)
– Purple: scheduled tasks

##### Details to capture
- Every adapter/port (Kafka, REST, database)
- The strategy handlers for different pricing flows
- Cache layer and retry configuration
- Docker-compose local environment

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Inbound Flows
    subgraph "Inbound HTTP (REST API)"
        direction TB
        A1["SellerServicePricingController"]:::controller
        A2["RecoveryController"]:::controller
        A3["IndexController"]:::controller
        A4["RestExceptionHandler"]:::controller
    end

    subgraph "Inbound Kafka"
        direction TB
        K1["SellerPricingRequestConsumer"]:::kafka
        K2["SubscribedSellerServicePricingConsumer"]:::kafka
    end

    %% Core Business Layer
    subgraph "Business Services"
        direction TB
        S1["SellerPricingRequestService"]:::service
        S2["SellerInvoiceService"]:::service
        S3["SubscribedSellerServicePricingService"]:::service
        S4["GmvBigQueryService"]:::service
        S5["FitApiService"]:::service
        S6["SalesforceAclApiService"]:::service
        S7["AclMailBrewService"]:::service
        S8["SellerApiService"]:::service
    end

    subgraph "Strategy Handlers"
        direction TB
        H1["ServicePricingRequestHandler"]:::service
        H2["EcocontributionPricingRequestHandler"]:::service
        H3["SellerFulfillmentPricingRequestHandler"]:::service
        H4["FixedSubscriptionServicePricingHandler"]:::service
        H5["FulfillmentSubscriptionServicePricingHandler"]:::service
        H6["PaidAccountManagementSubscriptionServicePricingHandler"]:::service
    end

    %% Data Persistence
    subgraph "Data Persistence"
        direction TB
        R1["SellerPricingRequestRepository"]:::repository
        R2["SellerInvoiceRepository"]:::repository
        R3["SubscribedSellerServicePricingRepository"]:::repository
        R4["PendingSellerInvoiceLinesRepository"]:::repository
        R5["InvoicedSellerServicesRepository"]:::repository
        R6["Dac7SellerInfoRepository"]:::repository
    end

    %% Scheduled Tasks
    subgraph "Scheduling"
        direction TB
        T1["SellerServicePricingScheduler"]:::scheduler
        T2["Dac7Scheduler"]:::scheduler
        T3["Dac7NotificationScheduler"]:::scheduler
        T4["SellerContactScheduler"]:::scheduler
    end

    %% External Adapters
    subgraph "Outbound HTTP (Adapters)"
        direction TB
        E1["FIT API"]:::external
        E2["MailBrew API"]:::external
        E3["Salesforce ACL API"]:::external
        E4["Seller API (v3)"]:::external
        E5["Google Cloud Storage"]:::external
        E6["BigQuery"]:::datastore
    end

    %% Message Broker
    subgraph "Kafka Cluster" 
        direction TB
        M1["Topic: seller-pricing-requests"]:::kafka
        M2["Topic: subscribed-pricing-updates"]:::kafka
        M3["Topic: seller-invoice-events"]:::kafka
    end

    %% Datastore
    DB["MongoDB"]:::datastore

    %% Entry Point
    APP["Application (Spring Boot)"]:::app

    %% Inbound HTTP flow
    APP -->|"/pricing" POST| A1 -->|calls| S1 -->|read/write| R1 -->|persist| DB
    A1 -->|exception| A4

    A2 -->|calls| S1
    A3 -->|health| S1

    %% Inbound Kafka flow
    M1 -->|consume| K1 -->|delegate| S1
    M2 -->|consume| K2 -->|delegate| S3
    K1 -->|uses handlers| H1
    S1 -->|persist| R1 -->|DB| DB
    K2 -->|uses handlers| H2
    K2 -->|uses handlers| H3
    K2 -->|uses handlers| H4
    K2 -->|uses handlers| H5
    K2 -->|uses handlers| H6
    S2 -->|produce| M3
    S3 -->|produce| M3

    %% Scheduling
    T1 -->|trigger| S1
    T2 -->|trigger| S1
    T3 -->|trigger| S2
    T4 -->|trigger| S2

    %% Outbound HTTP
    S1 -->|REST call| E4
    S1 -->|REST call| E3
    S2 -->|REST call| E1
    S2 -->|REST call| E2
    S1 -->|upload/download| E5
    S4 -->|write/read| E6

    %% BigQuery
    S4 -->|query/write| E6

    %% Click Events
    click A1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/controller/SellerServicePricingController.java"
    click A2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/controller/RecoveryController.java"
    click A3 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/controller/IndexController.java"
    click A4 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/controller/exceptions/RestExceptionHandler.java"
    click K1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/kafka/consumer/SellerPricingRequestConsumer.java"
    click K2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/kafka/consumer/SubscribedSellerServicePricingConsumer.java"
    click S1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/SellerPricingRequestService.java"
    click S2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/SellerInvoiceService.java"
    click S3 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/SubscribedSellerServicePricingService.java"
    click S4 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/GmvBigQueryService.java"
    click S5 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/FitApiService.java"
    click S6 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/SalesforceAclApiService.java"
    click S7 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/AclMailBrewService.java"
    click S8 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/SellerApiService.java"
    click H1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/ServicePricingRequestHandler.java"
    click H2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/EcocontributionPricingRequestHandler.java"
    click H3 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/SellerFulfillmentPricingRequestHandler.java"
    click H4 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/FixedSubscriptionServicePricingHandler.java"
    click H5 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/FulfillmentSubscriptionServicePricingHandler.java"
    click H6 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/service/handler/PaidAccountManagementSubscriptionServicePricingHandler.java"
    click R1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/SellerPricingRequestRepository.java"
    click R2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/SellerInvoiceRepository.java"
    click R3 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/SubscribedSellerServicePricingRepository.java"
    click R4 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/PendingSellerInvoiceLinesRepository.java"
    click R5 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/InvoicedSellerServicesRepository.java"
    click R6 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/repository/Dac7SellerInfoRepository.java"
    click T1 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/schedule/SellerServicePricingScheduler.java"
    click T2 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/schedule/Dac7Scheduler.java"
    click T3 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/schedule/Dac7NotificationScheduler.java"
    click T4 "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/schedule/SellerContactScheduler.java"
    click APP "https://github.com/hxh1234/projext-test/blob/main/src/main/java/com/adeo/bomp/sellerpricing/Application.java"

    %% Styles
    classDef controller fill:#D0E7FF,stroke:#000,stroke-width:1px
    classDef service fill:#E0FFD8,stroke:#000,stroke-width:1px
    classDef repository fill:#FFF3B0,stroke:#000,stroke-width:1px
    classDef kafka fill:#DFF7DF,stroke:#000,stroke-width:1px
    classDef external fill:#FFE7C0,stroke:#000,stroke-width:1px
    classDef datastore fill:#FFF5BA,stroke:#000,stroke-width:1px
    classDef scheduler fill:#E8DAFF,stroke:#000,stroke-width:1px
    classDef app fill:#F0F0F0,stroke:#000,stroke-width:1px
```
