# wolwerr/agentcleanarch architecture

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

- Interactive diagram: https://gitdiagram.com/wolwerr/agentcleanarch
- Repository: https://github.com/wolwerr/agentcleanarch

## Overview

##### Project Type and Purpose
- This is a backend service (no UI) implemented in Java 21 with Quarkus.
- It follows Clean Architecture to perform automated code reviews by scanning a project, building prompts, invoking an AI agent (OpenAI), aggregating results, and returning a structured review report via a REST API.

##### Key Architectural Layers (from file tree and README)
- Domain
- Entities: ReviewReport
- Gateways (interfaces): AiAgentGateway, ProjectScannerGateway, PromptBuilderGateway
- Exceptions: domain-level errors
- Application (Use Cases)
- ReviewProjectUseCase orchestrates the entire review flow
- Infra (Adapters & Utilities)
- Web Adapter: ReviewController, request/validator/exception mappers
- Config: OpenApiConfig
- Utilities: RepoHelper (file I/O), ChunkSplitter, PromptBuilder, ReportAggregator, OpenAiHttpClient
- External Integrations:
– ProjectScanner (scans filesystem or GitHub)
– OpenAiAgent (calls OpenAI REST API)
- Testing module mirrors all production packages for unit/integration tests.
- Deployment: Dockerfiles (JVM, native, legacy), docker-compose, Quarkus dev mode

##### Main Components
a. API Layer
– HTTP POST /api/review → ReviewController
– Request Validator & Exception Mappers
b. Use Case Layer
– ReviewProjectUseCase
c. Domain Layer
– Entities & Gateways interfaces
d. Infra Layer (Adapters)
– ProjectScanner (implements ProjectScannerGateway)
– PromptBuilder (implements PromptBuilderGateway)
– OpenAiAgent / OpenAiHttpClient (implements AiAgentGateway)
– ReportAggregator, ChunkSplitter, RepoHelper
e. External Systems
– Local file-system or GitHub repository
– OpenAI API service

##### Component Relationships / Data Flow
1. Client → ReviewController (HTTP JSON)
2. Controller → ReviewRequestValidator → ReviewProjectUseCase
3. UseCase calls ProjectScanner → returns raw code/text
4. UseCase calls PromptBuilder → builds AI prompt
5. UseCase calls OpenAiAgent → sends prompt, receives raw AI response
6. UseCase calls ReportAggregator → transforms raw response into ReviewReport
7. UseCase returns ReviewReport to Controller → serialized JSON to client

##### Important Patterns & Principles
- Clean Architecture layers strictly depend inwards (Adapters → Application → Domain)
- Gateways abstract external dependencies (file system, HTTP client) behind interfaces
- Controllers and exception mappers form the entry point (Hexagonal/Ports & Adapters)
- Utilities (ChunkSplitter, RepoHelper) encapsulate cross-cutting concerns

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Client["Client"]:::external

    %% API Layer
    subgraph "API Layer"
        RC["ReviewController"]:::infra
        RV["ReviewRequestValidator"]:::infra
        GEM["GenericExceptionMapper"]:::infra
        IREM["InvalidRequestExceptionMapper"]:::infra
    end

    %% Application Layer
    subgraph "Application Layer"
        UC["ReviewProjectUseCase"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        RR["ReviewReport"]:::domain
        AAGW["AiAgentGateway (interface)"]:::domain_int
        PSGW["ProjectScannerGateway"]:::domain_int
        PBGW["PromptBuilderGateway"]:::domain_int
        AE["AgentAnalysisException"]:::domain_exc
        ACE["AiClientException"]:::domain_exc
        PSE["ProjectScanException"]:::domain_exc
    end

    %% Infra Layer
    subgraph "Infra Layer"
        PS["ProjectScanner"]:::infra
        OA["OpenAiAgent"]:::infra
        PB["PromptBuilder"]:::infra
        RA["ReportAggregator"]:::infra
        CS["ChunkSplitter"]:::infra
        RH["RepoHelper"]:::infra
        OAC["OpenAiHttpClient"]:::infra
        OACfg["OpenApiConfig"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        FS["File System / GitHub"]:::external
        AIAPI["OpenAI API"]:::external
    end

    %% Deployment
    subgraph "Deployment"
        DFJVM["Dockerfile.jvm"]:::infra
        DFN["Dockerfile.native"]:::infra
        DC["docker-compose.yml"]:::infra
    end

    %% Connections
    Client -->|"POST /api/review"| RC
    RC -->|"validates request"| RV
    RC -->|"handles exceptions"| GEM
    RC -->|"handles invalid"| IREM
    RV -->|"valid data"| UC
    UC -->|"scan project"| PS
    PS -->|"reads code"| FS
    UC -->|"build prompt"| PB
    PB -->|"splits chunks"| CS
    PB -->|"reads files"| RH
    UC -->|"send prompt"| OA
    OA -->|"HTTP request"| OAC
    OAC -->|"calls"| AIAPI
    AIAPI -->|"response"| OAC
    OA -->|"returns ai response"| UC
    UC -->|"aggregate report"| RA
    RA -->|"produces"| RR
    UC -->|"returns report"| RC

    %% Click Events
    click RC "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/adpter/web/ReviewController.java"
    click RV "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/adpter/web/validator/ReviewRequestValidator.java"
    click GEM "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/adpter/web/handler/GenericExceptionMapper.java"
    click IREM "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/adpter/web/handler/InvalidRequestExceptionMapper.java"
    click UC "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/application/useCase/ReviewProjectUseCase.java"
    click RR "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/entity/ReviewReport.java"
    click AAGW "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/gateway/AiAgentGateway.java"
    click PSGW "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/gateway/ProjectScannerGateway.java"
    click PBGW "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/gateway/PromptBuilderGateway.java"
    click AE "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/exception/AgentAnalysisException.java"
    click ACE "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/exception/AiClientException.java"
    click PSE "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/domain/exception/ProjectScanException.java"
    click PS "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/ProjectScanner.java"
    click OA "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/OpenAiAgent.java"
    click PB "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/util/PromptBuilder.java"
    click RA "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/util/ReportAggregator.java"
    click CS "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/util/ChunkSplitter.java"
    click RH "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/util/RepoHelper.java"
    click OAC "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/util/OpenAiHttpClient.java"
    click OACfg "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/java/com/poc/infra/config/OpenApiConfig.java"
    click DFJVM "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/docker/Dockerfile.jvm"
    click DFN "https://github.com/wolwerr/agentcleanarch/blob/main/src/main/docker/Dockerfile.native"
    click DC "https://github.com/wolwerr/agentcleanarch/blob/main/docker-compose.yml"

    %% Styles
    classDef domain fill:#cce5ff,stroke:#004085,stroke-width:1px
    classDef domain_int fill:#e2e3e5,stroke:#6c757d
    classDef domain_exc fill:#f8d7da,stroke:#721c24
    classDef app fill:#d4edda,stroke:#155724
    classDef infra fill:#fff3cd,stroke:#856404
    classDef external fill:#e2e3e5,stroke:#6c757d
```
