How wolwerr/agentcleanarch works
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