# lowes/auditor architecture

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

- Interactive diagram: https://gitdiagram.com/lowes/auditor
- Repository: https://github.com/lowes/auditor

## Overview

##### Main Components
- Core Library: The core module contains shared utilities such as mappers, DTO converters, constants, and common entity definitions. This serves as a base for both the client and server modules.
- Auditor Client Library: This is provided in the “client” module that contains API and implementation details along with packages for event processing, filtering, and logging. It includes functionalities for both standalone and Spring Boot environments.
- Spring Boot Starter: Located in “client-spring-boot-starter”, this module wraps the client library to ease integration for Spring Boot applications. It provides auto-configuration and pre-initialized auditor instances.
- App Server: Found under the “app” module, this is the deployable service that listens to Kafka events and persists or logs audit data to Elasticsearch. It handles asynchronous processing, event consumption, and repository operations.
- Examples: The “client-example” and “client-example-springboot” projects demonstrate integration with both standalone and Spring Boot mode, helping users understand client usage.

##### Out the Relationships and Interactions
- Consumption and Persistence: The app server (in the “app” module) listens to Kafka topics. Once events are consumed, they are processed (possibly via event consumers and service layers) and then stored in Elasticsearch using configurations shown in repository modules.
- Core Dependencies: Illustrate that both the client and app modules depend on the core module for common functionality.
- External Integrations: Mark Kafka for event streaming and Elasticsearch for repository functions, as well as external libraries like Project Reactor and jackson-afterburner.

##### Architectural Patterns & Design Principles
- Asynchronous & Reactive Flow: Emphasize asynchronous processing, using components like separate thread pools and the reactive programming paradigm to highlight performance and scalability.
- Decoupling via Messaging: Show how Kafka decouples the sender (client) from the consumer (app server), enabling eventual consistency.
- Extension Points: Indicate points for configuration, such as auditing event decorators, filters, and runtime configurations that underline customizability.

##### Relevant Technologies & Frameworks
- Project Reactor: For reactive programming in the app server and client processing.
- Kafka: As the event streaming platform.
- Elasticsearch: For storing and indexing audit logs.
- Spring Boot: For simplified integration using the “client-spring-boot-starter”.
- Gradle: Used for build configuration across modules.
- Jackson-afterburner: To enhance the performance of JSON serialization.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Core Module
    subgraph "Core Module"
        CORE("Core Utilities"):::core
    end

    %% Client Modules
    subgraph "Client Modules"
        CLIENT("Auditor Client (Standalone)"):::client
        CLIENT_SPRING("Spring Boot Starter"):::client
        EXAMPLE1("Client Example (Standalone)"):::example
        EXAMPLE2("Client Example (Spring Boot)"):::example
    end

    %% Messaging Layer
    subgraph "Messaging Layer"
        KAFKA("Kafka Event Stream"):::messaging
    end

    %% App Server
    subgraph "App Server"
        APP("Audit App Server"):::app
        ES("Elasticsearch Repository"):::database
    end

    %% External Technologies
    REACTOR("Project Reactor"):::external
    JACKSON("jackson-afterburner"):::external
    SB("Spring Boot Framework"):::external

    %% Relationships: Dependency on Core Module
    CLIENT -->|"uses"| CORE
    CLIENT_SPRING -->|"uses"| CORE
    APP -->|"uses"| CORE

    %% Client Modules sending events to Kafka
    CLIENT -->|"sendsAuditEvents"| KAFKA
    CLIENT_SPRING -->|"sendsAuditEvents"| KAFKA

    %% Examples demonstrating usage of client libraries
    EXAMPLE1 -->|"demonstrates"| CLIENT
    EXAMPLE2 -->|"demonstrates"| CLIENT_SPRING

    %% Kafka delivering events to App Server
    KAFKA -->|"deliversEvents"| APP

    %% App Server persisting audit logs in Elasticsearch
    APP -->|"persistsLogs"| ES

    %% External integrations with reactive and JSON processing
    CLIENT -->|"reactive"| REACTOR
    APP -->|"reactive"| REACTOR
    CLIENT -->|"jsonOptimized"| JACKSON
    APP -->|"jsonOptimized"| JACKSON

    %% Spring Boot integration for enhanced auto-configuration
    CLIENT_SPRING -->|"integratesWith"| SB

    %% Click Events
    click CORE "https://github.com/lowes/auditor/tree/main/core/"
    click CLIENT "https://github.com/lowes/auditor/tree/main/client/"
    click CLIENT_SPRING "https://github.com/lowes/auditor/tree/main/client-spring-boot-starter/"
    click APP "https://github.com/lowes/auditor/tree/main/app/"
    click EXAMPLE1 "https://github.com/lowes/auditor/tree/main/client-example/"
    click EXAMPLE2 "https://github.com/lowes/auditor/tree/main/client-example-springboot/"

    %% Styles
    classDef core fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef client fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef app fill:#f94144,stroke:#333,stroke-width:2px;
    classDef messaging fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef database fill:#80ced6,stroke:#333,stroke-width:2px;
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:2px;
    classDef example fill:#277da1,stroke:#333,stroke-width:2px;
```
