How nikhil-keshri2213/ai-code-review-app works
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: kafka.yaml Kafka · CodeFetchServiceApplication.java PR Fetch · AiReviewServiceApplication.java AI Review · WebhookServiceApplication.java Webhook Ingest
Components 18
External systems
Outside services this repo integrates with.
- GitHub · Source of webhooks, PR data, and review comments.
- OpenAI · Generates AI review output for the review service.
- Slack · Receives outbound review notifications.
Platform infra
Shared runtime and data infrastructure.
- Kafka · Main asynchronous backbone for review workflow events.
k8s/infra/kafka.yaml - Zookeeper · Kafka coordination service in the platform stack.
k8s/infra/zookeeper.yaml - Postgres · Durable storage for review records and dashboard read models.
k8s/infra/postgres.yaml - Redis · Used by the gateway rate limiter and shared caching needs.
k8s/infra/redis.yaml - Weaviate · Embedding-backed retrieval layer for AI context.
k8s/infra/weaviate.yaml - Eureka · 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 · Front door for client traffic with JWT auth, logging, and rate limiting.
api-gateway/src/main/java/com/aicodereview/gateway/ApiGatewayApplication.java - Webhook Ingest · Validates GitHub signatures and publishes pull request events.
webhook-service/src/main/java/com/aicodereview/webhook/WebhookServiceApplication.java - PR Fetch · 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 · LLM-based review generation with prompt, embedding, RAG, and severity logic.
ai-review-service/src/main/java/com/aicodereview/review/AiReviewServiceApplication.java - Code Analysis · Automated non-LLM analysis consumer path for review requests.
code-analysis-service/src/main/java/com/aicodereview/analysis/CodeAnalysisServiceApplication.java - Review Storage · Persists review results in Postgres and serves dashboard/reporting APIs.
review-storage-service/src/main/java/com/aicodereview/storage/ReviewStorageServiceApplication.java - Notifications · Publishes GitHub comments and Slack alerts from review results.
notification-service/src/main/java/com/aicodereview/notification/NotificationServiceApplication.java - Common Contracts · 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 · Read-side React/Vite dashboard for review summaries and trends.
dashboard/src/App.jsx
Connections 23
- 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.