# nikhil-keshri2213/ai-code-review-app architecture

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

- Interactive diagram: https://gitdiagram.com/nikhil-keshri2213/ai-code-review-app
- Repository: https://github.com/nikhil-keshri2213/ai-code-review-app

## Overview

This repository is a Java/Spring microservice system for AI-assisted code review, with a React dashboard on the read side. The architecture is primarily event-driven: GitHub webhooks enter at the edge, Kafka carries review workflow events between services, and Postgres/Weaviate hold durable state and AI context.

1. **Edge and routing layer**
   - `api-gateway` is the front door for client traffic.
   - It handles JWT auth (`JwtAuthFilter`), request logging, and rate limiting (`RateLimiterConfig`), so security and traffic control are centralized.
   - `eureka-server` provides service discovery for the Spring services.

2. **Webhook ingress**
   - `webhook-service` receives GitHub webhook callbacks.
   - It validates request signatures (`GitHubSignatureValidator`) before accepting events.
   - Valid pull request events are published to Kafka as the system’s asynchronous entry point.

3. **PR fetch and normalization**
   - `code-fetch-service` consumes pull request events from Kafka.
   - It talks to GitHub through a `WebClient`/`GitHubApiClient`, parses diffs (`DiffParser`), chunks code (`CodeChunker`), and converts raw PR data into review-ready payloads.
   - This service is the bridge between external GitHub data and internal analysis events.

4. **Analysis pipeline**
   - `ai-review-service` consumes review requests and performs LLM-based review generation.
   - It contains the AI-specific subsystems: prompt templates, embedding generation, RAG context retrieval, severity scoring, and the OpenAI client.
   - `code-analysis-service` is a separate consumer path for automated non-LLM analysis, suggesting parallel analysis workflows off the same review event stream.

5. **Retrieval-augmented generation boundary**
   - `ai-review-service` is the only service wired to `Weaviate`.
   - It stores or queries embeddings via `WeaviateStorageService` and uses `RagContextService` to enrich prompts with similar code/review context.
   - This makes the AI service the main boundary between internal repository data and vector search infrastructure.

6. **Persistence and reporting**
   - `review-storage-service` is the persistence/read-model service.
   - It stores review entities in Postgres, managed by Flyway migrations in `src/main/resources/db/migration`.
   - It exposes review and dashboard-oriented endpoints and also consumes review results from Kafka to keep the database in sync with completed analyses.

7. **Notifications and external side effects**
   - `notification-service` consumes review results and sends notifications outward.
   - It integrates with GitHub comments (`GitHubCommentClient`) and Slack (`SlackNotificationService`), making it the side-effect boundary for user-facing alerts.

8. **Shared contracts**
   - The `common` module defines cross-service DTOs and enums such as `PullRequestEvent`, `ReviewRequest`, `ReviewResult`, `ReviewComment`, `ApiResponse`, `Severity`, and `ReviewCategory`.
   - This module is the schema contract for both Kafka payloads and HTTP APIs, reducing drift between services.

9. **Dashboard**
   - `dashboard` is a separate React/Vite app with Tailwind styling.
   - It reads review summaries, stats, and trends from backend APIs, likely through the storage service.
   - Components like `ReviewsList`, `StatsCards`, and `TrendsChart` indicate a reporting/observability UI rather than a write-heavy client.

10. **Infrastructure and deployment**
   - The repo includes Dockerfiles for each service, a root `docker-compose.yml`/`docker-compose.prod.yml`, and Kubernetes manifests under `k8s/`.
   - Infra services in Kubernetes include Kafka, Zookeeper, Postgres, Redis, and Weaviate.
   - Redis materially matters because the gateway’s rate limiter is configured to use it.
   - HPA manifests exist for some services, indicating the platform expects variable load.

11. **Primary end-to-end data flow**
   - GitHub PR event → `webhook-service` → Kafka → `code-fetch-service` → review-request event → `ai-review-service` and `code-analysis-service` → review-result event → `review-storage-service` and `notification-service` → dashboard/notifications.
   - The system is therefore split into ingress, transformation, analysis, persistence, and notification stages, with Kafka as the main integration backbone.

12. **What to draw as the main boundaries**
   - External systems: GitHub, OpenAI, Slack.
   - Platform infra: Kafka/Zookeeper, Postgres, Redis, Weaviate, Eureka.
   - Internal service tiers: gateway, webhook ingestion, fetch/preprocess, AI/analysis, storage/read model, notifications, dashboard.

Main entry points: [`k8s/infra/kafka.yaml`](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/kafka.yaml) (Kafka), [`code-fetch-service/src/main/java/com/aicodereview/fetch/CodeFetchServiceApplication.java`](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/code-fetch-service/src/main/java/com/aicodereview/fetch/CodeFetchServiceApplication.java) (PR Fetch), [`ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java`](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java) (AI Review), [`webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java`](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java) (Webhook Ingest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_github(("GitHub<br/>external API"))
  node_openai(("OpenAI<br/>llm API"))
  node_slack(("Slack<br/>notification API"))
end

subgraph group_platform["Platform infra"]
  node_kafka["Kafka<br/>event bus<br/>[kafka.yaml]"]
  node_zookeeper(("Zookeeper<br/>coordination<br/>[zookeeper.yaml]"))
  node_postgres[("Postgres<br/>relational store<br/>[postgres.yaml]")]
  node_redis[("Redis<br/>cache/rate-limit<br/>[redis.yaml]")]
  node_weaviate[("Weaviate<br/>vector store<br/>[weaviate.yaml]")]
  node_eureka(("Eureka<br/>service registry"))
end

subgraph group_services["Backend services"]
  node_gateway["API Gateway<br/>edge gateway"]
  node_webhook["Webhook Ingest<br/>ingress service"]
  node_fetch["PR Fetch<br/>transform service"]
  node_ai_review["AI Review<br/>analysis service"]
  node_analysis["Code Analysis<br/>rule analysis"]
  node_storage["Review Storage<br/>read model"]
  node_notify["Notifications<br/>side-effect service"]
  node_common["Common Contracts<br/>shared DTOs<br/>[ReviewRequest.java]"]
end

subgraph group_ui["Dashboard"]
  node_dashboard["Dashboard UI<br/>react app<br/>[App.jsx]"]
end

node_github -->|"webhook"| node_webhook
node_gateway -->|"routes"| node_webhook
node_gateway -->|"rate limit"| node_redis
node_gateway -->|"discovers"| node_eureka
node_webhook -->|"publish PR event"| node_kafka
node_webhook -.->|"uses schema"| node_common
node_kafka -->|"consume PR event"| node_fetch
node_fetch -->|"fetch diff"| node_github
node_fetch -->|"publish review request"| node_kafka
node_fetch -.->|"uses schema"| node_common
node_kafka -->|"consume request"| node_ai_review
node_kafka -->|"consume request"| node_analysis
node_ai_review -->|"llm call"| node_openai
node_ai_review -->|"rag search"| node_weaviate
node_ai_review -->|"publish result"| node_kafka
node_analysis -->|"publish result"| node_kafka
node_kafka -->|"consume result"| node_storage
node_kafka -->|"consume result"| node_notify
node_notify -->|"comment"| node_github
node_notify -->|"alert"| node_slack
node_storage -->|"persist"| node_postgres
node_storage -->|"serve data"| node_dashboard
node_dashboard -->|"read api"| node_storage

click node_kafka "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/kafka.yaml"
click node_zookeeper "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/zookeeper.yaml"
click node_postgres "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/postgres.yaml"
click node_redis "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/redis.yaml"
click node_weaviate "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/weaviate.yaml"
click node_eureka "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/eureka-server/src/main/java/com/aicodereview/eureka/EurekaServerApplication.java"
click node_gateway "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/api-gateway/src/main/java/com/aicodereview/gateway/ApiGatewayApplication.java"
click node_webhook "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java"
click node_fetch "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/code-fetch-service/src/main/java/com/aicodereview/fetch/CodeFetchServiceApplication.java"
click node_ai_review "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java"
click node_analysis "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/code-analysis-service/src/main/java/com/aicodereview/analysis/CodeAnalysisServiceApplication.java"
click node_storage "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/review-storage-service/src/main/java/com/aicodereview/storage/ReviewStorageServiceApplication.java"
click node_notify "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/notification-service/src/main/java/com/aicodereview/notification/NotificationServiceApplication.java"
click node_common "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/common/src/main/java/com/aicodereview/common/dto/ReviewRequest.java"
click node_dashboard "https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/dashboard/src/App.jsx"

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_github,node_openai,node_slack toneBlue
class node_kafka,node_zookeeper,node_postgres,node_redis,node_weaviate,node_eureka toneAmber
class node_gateway,node_webhook,node_fetch,node_ai_review,node_analysis,node_storage,node_notify,node_common toneMint
class node_dashboard toneRose
```

## Components

### External systems

Outside services this repo integrates with.

- **GitHub**: external API · Source of webhooks, PR data, and review comments.
- **OpenAI**: llm API · Generates AI review output for the review service.
- **Slack**: notification API · Receives outbound review notifications.

### Platform infra

Shared runtime and data infrastructure.

- [Kafka](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/kafka.yaml): event bus · Main asynchronous backbone for review workflow events. · `k8s/infra/kafka.yaml`
- [Zookeeper](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/zookeeper.yaml): coordination · Kafka coordination service in the platform stack. · `k8s/infra/zookeeper.yaml`
- [Postgres](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/postgres.yaml): relational store · Durable storage for review records and dashboard read models. · `k8s/infra/postgres.yaml`
- [Redis](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/redis.yaml): cache/rate-limit · Used by the gateway rate limiter and shared caching needs. · `k8s/infra/redis.yaml`
- [Weaviate](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/k8s/infra/weaviate.yaml): vector store · Embedding-backed retrieval layer for AI context. · `k8s/infra/weaviate.yaml`
- [Eureka](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/eureka-server/src/main/java/com/aicodereview/eureka/EurekaServerApplication.java): service registry · Service discovery for Spring services. · `eureka-server/src/main/java/com/aicodereview/eureka/EurekaServerApplication.java`

### Backend services

Spring services forming the review pipeline.

- [API Gateway](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/api-gateway/src/main/java/com/aicodereview/gateway/ApiGatewayApplication.java): edge gateway · Front door for client traffic with JWT auth, logging, and rate limiting. · `api-gateway/src/main/java/com/aicodereview/gateway/ApiGatewayApplication.java`
- [Webhook Ingest](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java): ingress service · Validates GitHub signatures and publishes pull request events. · `webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java`
- [PR Fetch](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/code-fetch-service/src/main/java/com/aicodereview/fetch/CodeFetchServiceApplication.java): transform service · Fetches PR data from GitHub, parses diffs, chunks code, and emits review requests. · `code-fetch-service/src/main/java/com/aicodereview/fetch/CodeFetchServiceApplication.java`
- [AI Review](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java): analysis service · LLM-based review generation with prompt, embedding, RAG, and severity logic. · `ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java`
- [Code Analysis](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/code-analysis-service/src/main/java/com/aicodereview/analysis/CodeAnalysisServiceApplication.java): rule analysis · Automated non-LLM analysis consumer path for review requests. · `code-analysis-service/src/main/java/com/aicodereview/analysis/CodeAnalysisServiceApplication.java`
- [Review Storage](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/review-storage-service/src/main/java/com/aicodereview/storage/ReviewStorageServiceApplication.java): read model · Persists review results in Postgres and serves dashboard/reporting APIs. · `review-storage-service/src/main/java/com/aicodereview/storage/ReviewStorageServiceApplication.java`
- [Notifications](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/notification-service/src/main/java/com/aicodereview/notification/NotificationServiceApplication.java): side-effect service · Publishes GitHub comments and Slack alerts from review results. · `notification-service/src/main/java/com/aicodereview/notification/NotificationServiceApplication.java`
- [Common Contracts](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/common/src/main/java/com/aicodereview/common/dto/ReviewRequest.java): shared DTOs · Cross-service event and API schemas shared by all backend services. · `common/src/main/java/com/aicodereview/common/dto/ReviewRequest.java`

### Dashboard

Read-side React application.

- [Dashboard UI](https://github.com/nikhil-keshri2213/ai-code-review-app/blob/main/dashboard/src/App.jsx): react app · Read-side React/Vite dashboard for review summaries and trends. · `dashboard/src/App.jsx`

## Connections

- GitHub → Webhook Ingest: webhook · GitHub sends pull request callbacks to the ingestion edge.
- API Gateway → Webhook Ingest: routes · Client traffic can be routed through the gateway to backend services.
- API Gateway → Redis: rate limit · Gateway rate limiting relies on Redis.
- API Gateway → Eureka: discovers · Gateway uses service discovery for routing backend calls.
- Webhook Ingest → Kafka: publish PR event · Validated webhook payloads become asynchronous pull request events.
- Webhook Ingest → Common Contracts: uses schema · Webhook payloads are shaped by shared contracts.
- Kafka → PR Fetch: consume PR event · PR events trigger fetch and normalization.
- PR Fetch → GitHub: fetch diff · Fetch service calls GitHub for PR content and file diffs.
- PR Fetch → Kafka: publish review request · Normalized PR data is emitted as review requests.
- PR Fetch → Common Contracts: uses schema · Fetch service shares event DTOs with the rest of the pipeline.
- Kafka → AI Review: consume request · AI review service consumes review requests from the event bus.
- Kafka → Code Analysis: consume request · Code analysis service consumes the same review request stream.
- AI Review → OpenAI: llm call · AI review generation depends on OpenAI.
- AI Review → Weaviate: rag search · AI review service queries and stores vector context in Weaviate.
- AI Review → Kafka: publish result · Completed AI reviews are emitted back into the workflow.
- Code Analysis → Kafka: publish result · Automated analysis results are emitted for downstream consumers.
- Kafka → Review Storage: consume result · Storage service ingests review results to keep its read model current.
- Kafka → Notifications: consume result · Notification service reacts to completed reviews.
- Notifications → GitHub: comment · Notification service can post review comments back to GitHub.
- Notifications → Slack: alert · Notification service pushes alerts to Slack.
- Review Storage → Postgres: persist · Review data is stored in Postgres.
- Review Storage → Dashboard UI: serve data · Dashboard reads summaries and trends from storage APIs.
- Dashboard UI → Review Storage: read api · React dashboard consumes backend reporting endpoints.
