# ussamarei/ai-powered-code-review-assistant architecture

> Architecture diagram of the GitHub repository ussamarei/ai-powered-code-review-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ussamarei/ai-powered-code-review-assistant
- Repository: https://github.com/ussamarei/ai-powered-code-review-assistant

## Overview

AI Code Review Assistant is a GitHub Action that turns pull-request changes into severity-filtered inline review findings. The documented flow fetches changed files, parses diffs and Java structure, enriches each review with related code, calls an LLM with Gemini-to-Groq failover, aggregates findings, and publishes a GitHub review or Actions job summary. App and ReviewOrchestrator are the wiring and coordination layers. Some runtime details are documented but their implementation was not sampled; links for those steps follow the README’s stated architecture.

Main entry points: [`src/main/java/dev/codereviewer/review/FileReviewTask.java`](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/FileReviewTask.java) (Per-file review), [`src/main/java/dev/codereviewer/review/ReviewOrchestrator.java`](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/ReviewOrchestrator.java) (Review orchestrator), [`src/main/java/dev/codereviewer/context/ContextBuilder.java`](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/context/ContextBuilder.java) (Context enrichment), [`src/main/java/dev/codereviewer/App.java`](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/App.java) (Application wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Action entry"]
  node_action["GitHub Action<br/>[action.yml]"]
  node_app["Application wiring<br/>[App.java]"]
  node_config["Review configuration<br/>[ReviewConfig.java]"]
end

subgraph group_github["GitHub integration"]
  node_pr_service["PR data service"]
  node_publisher["Review publisher"]
end

subgraph group_analysis["Code analysis"]
  node_diff_parser["Diff parser<br/>[DiffParser.java]"]
  node_ast_analyzer["AST analyzer<br/>[AstAnalyzer.java]"]
  node_code_context["Structural context<br/>[CodeContext.java]"]
  node_context_builder["Context enrichment"]
  node_chunker["Context chunking"]
end

subgraph group_review["Review pipeline"]
  node_orchestrator["Review orchestrator"]
  node_file_task["Per-file review"]
  node_prompt_builder["Prompt builder<br/>[PromptBuilder.java]"]
  node_response_parser["Response parser"]
  node_finding["Review findings<br/>[ReviewFinding.java]"]
  node_result["Aggregated results<br/>[ReviewResult.java]"]
end

subgraph group_providers["LLM providers"]
  node_llm_router["LLM failover router<br/>[LlmRouter.java]"]
  node_llm_client["Provider interface<br/>[LlmClient.java]"]
  node_gemini["Gemini client<br/>[GeminiClient.java]"]
  node_groq["Groq client<br/>[GroqClient.java]"]
end

node_pr_event(("Pull request event"))
node_github_api["GitHub API"]
node_llm_services["LLM APIs"]
node_job_summary["Actions job summary"]

node_pr_event -->|"triggers"| node_action
node_action -->|"runs"| node_app
node_app -->|"loads"| node_config
node_app -->|"starts"| node_orchestrator
node_orchestrator -->|"fetches files"| node_pr_service
node_pr_service -->|"reads PR data"| node_github_api
node_orchestrator -->|"creates context"| node_context_builder
node_context_builder -->|"fetches source"| node_pr_service
node_context_builder -->|"analyzes source"| node_ast_analyzer
node_orchestrator -->|"dispatches files"| node_file_task
node_file_task -->|"parses patch"| node_diff_parser
node_file_task -->|"analyzes changes"| node_ast_analyzer
node_ast_analyzer -->|"produces structure"| node_code_context
node_file_task -->|"gets related code"| node_context_builder
node_file_task -->|"fits context"| node_chunker
node_file_task -->|"builds prompt"| node_prompt_builder
node_file_task -->|"requests review"| node_llm_router
node_llm_router -->|"tries primary"| node_gemini
node_llm_router -.->|"fails over"| node_groq
node_gemini -->|"implements"| node_llm_client
node_groq -->|"implements"| node_llm_client
node_gemini -->|"sends request"| node_llm_services
node_groq -.->|"sends request"| node_llm_services
node_file_task -->|"parses response"| node_response_parser
node_response_parser -->|"creates findings"| node_finding
node_orchestrator -->|"aggregates findings"| node_result
node_orchestrator -->|"publishes results"| node_publisher
node_publisher -->|"posts review"| node_github_api
node_publisher -.->|"writes fallback"| node_job_summary

click node_action "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/action.yml"
click node_app "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/App.java"
click node_config "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/config/ReviewConfig.java"
click node_orchestrator "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/ReviewOrchestrator.java"
click node_pr_service "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/github/PullRequestService.java"
click node_diff_parser "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/DiffParser.java"
click node_ast_analyzer "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/AstAnalyzer.java"
click node_code_context "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/CodeContext.java"
click node_context_builder "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/context/ContextBuilder.java"
click node_chunker "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/context/ContextChunker.java"
click node_file_task "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/FileReviewTask.java"
click node_prompt_builder "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/PromptBuilder.java"
click node_llm_router "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/LlmRouter.java"
click node_llm_client "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/LlmClient.java"
click node_gemini "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/GeminiClient.java"
click node_groq "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/GroqClient.java"
click node_response_parser "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/ResponseParser.java"
click node_finding "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/ReviewFinding.java"
click node_result "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/ReviewResult.java"
click node_publisher "https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/github/ReviewPublisher.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_action,node_app,node_config toneBlue
class node_pr_service,node_publisher toneAmber
class node_diff_parser,node_ast_analyzer,node_code_context,node_context_builder,node_chunker,node_pr_event,node_github_api,node_llm_services toneMint
class node_orchestrator,node_file_task,node_prompt_builder,node_response_parser,node_finding,node_result toneRose
class node_llm_router,node_llm_client,node_gemini,node_groq,node_job_summary toneIndigo
```

## Components

### Action entry

- [GitHub Action](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/action.yml): `action.yml`
- [Application wiring](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/App.java): `src/main/java/dev/codereviewer/App.java`
- [Review configuration](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/config/ReviewConfig.java): `src/main/java/dev/codereviewer/config/ReviewConfig.java`

### GitHub integration

- [PR data service](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/github/PullRequestService.java): `src/main/java/dev/codereviewer/github/PullRequestService.java`
- [Review publisher](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/github/ReviewPublisher.java): `src/main/java/dev/codereviewer/github/ReviewPublisher.java`

### Code analysis

- [Diff parser](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/DiffParser.java): `src/main/java/dev/codereviewer/parser/DiffParser.java`
- [AST analyzer](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/AstAnalyzer.java): `src/main/java/dev/codereviewer/parser/AstAnalyzer.java`
- [Structural context](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/parser/CodeContext.java): `src/main/java/dev/codereviewer/parser/CodeContext.java`
- [Context enrichment](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/context/ContextBuilder.java): `src/main/java/dev/codereviewer/context/ContextBuilder.java`
- [Context chunking](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/context/ContextChunker.java): `src/main/java/dev/codereviewer/context/ContextChunker.java`

### Review pipeline

- [Review orchestrator](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/ReviewOrchestrator.java): `src/main/java/dev/codereviewer/review/ReviewOrchestrator.java`
- [Per-file review](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/FileReviewTask.java): `src/main/java/dev/codereviewer/review/FileReviewTask.java`
- [Prompt builder](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/PromptBuilder.java): `src/main/java/dev/codereviewer/llm/PromptBuilder.java`
- [Response parser](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/ResponseParser.java): `src/main/java/dev/codereviewer/llm/ResponseParser.java`
- [Review findings](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/ReviewFinding.java): `src/main/java/dev/codereviewer/llm/ReviewFinding.java`
- [Aggregated results](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/review/ReviewResult.java): `src/main/java/dev/codereviewer/review/ReviewResult.java`

### LLM providers

- [LLM failover router](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/LlmRouter.java): `src/main/java/dev/codereviewer/llm/LlmRouter.java`
- [Provider interface](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/LlmClient.java): `src/main/java/dev/codereviewer/llm/LlmClient.java`
- [Gemini client](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/GeminiClient.java): `src/main/java/dev/codereviewer/llm/GeminiClient.java`
- [Groq client](https://github.com/ussamarei/ai-powered-code-review-assistant/blob/main/src/main/java/dev/codereviewer/llm/GroqClient.java): `src/main/java/dev/codereviewer/llm/GroqClient.java`

### Other components

- **Pull request event**
- **GitHub API**
- **LLM APIs**
- **Actions job summary**

## Connections

- Pull request event → GitHub Action: triggers
- GitHub Action → Application wiring: runs
- Application wiring → Review configuration: loads
- Application wiring → Review orchestrator: starts
- Review orchestrator → PR data service: fetches files
- PR data service → GitHub API: reads PR data
- Review orchestrator → Context enrichment: creates context
- Context enrichment → PR data service: fetches source
- Context enrichment → AST analyzer: analyzes source
- Review orchestrator → Per-file review: dispatches files
- Per-file review → Diff parser: parses patch
- Per-file review → AST analyzer: analyzes changes
- AST analyzer → Structural context: produces structure
- Per-file review → Context enrichment: gets related code
- Per-file review → Context chunking: fits context
- Per-file review → Prompt builder: builds prompt
- Per-file review → LLM failover router: requests review
- LLM failover router → Gemini client: tries primary
- LLM failover router → Groq client: fails over
- Gemini client → Provider interface: implements
- Groq client → Provider interface: implements
- Gemini client → LLM APIs: sends request
- Groq client → LLM APIs: sends request
- Per-file review → Response parser: parses response
- Response parser → Review findings: creates findings
- Review orchestrator → Aggregated results: aggregates findings
- Review orchestrator → Review publisher: publishes results
- Review publisher → GitHub API: posts review
- Review publisher → Actions job summary: writes fallback