# srikanthreddyvvs/diffhawk architecture

> Architecture diagram of the GitHub repository srikanthreddyvvs/diffhawk, 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/srikanthreddyvvs/diffhawk
- Repository: https://github.com/srikanthreddyvvs/diffhawk

## Overview

DiffHawk is a GitHub pull-request review service: users connect and register repositories, GitHub webhooks trigger review work, and review findings and comments are produced. Sampled code confirms authentication persistence, repository management, webhook validation and outbox enqueueing, and review-result persistence and GitHub comments. The README offers no further architecture detail; outbox publishing, Kafka consumption, and AI request orchestration are represented as subsystems from the source tree, but their wiring is not confirmed by sampled source.

Main entry points: [`src/main/java/com/DiffHawk/repository/UserRepository.java`](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/UserRepository.java) (Users), [`src/main/java/com/DiffHawk/service/ReviewService.java`](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/ReviewService.java) (Review Results), [`src/main/java/com/DiffHawk/service/RepoService.java`](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/RepoService.java) (Repository Management), [`src/main/java/com/DiffHawk/service/WebhookService.java`](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/WebhookService.java) (Webhook Validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity"]
  node_oauth_service["OAuth User Sync"]
  node_oauth_handler["OAuth Success"]
  node_jwt["JWT Service<br/>[JwtService.java]"]
  node_auth_controller["Auth API"]
  node_user_store[("Users")]
end

subgraph group_repos["Repository Setup"]
  node_repo_controller["Repository API"]
  node_repo_service["Repository Management<br/>[RepoService.java]"]
  node_repo_store[("Repositories")]
end

subgraph group_events["Review Events"]
  node_webhook_controller["Webhook API"]
  node_webhook_service["Webhook Validation"]
  node_outbox_store[("Outbox Events")]
  node_outbox_publisher["Outbox Publisher"]
end

subgraph group_review["Review Processing"]
  node_review_consumer["Review Consumer"]
  node_ai_client["AI Service Client"]
  node_review_service["Review Results<br/>[ReviewService.java]"]
  node_review_store[("Reviews")]
  node_finding_store[("Review Findings")]
  node_github_client["GitHub Client<br/>[GitHubClient.java]"]
end

node_user(("User"))
node_github(("GitHub"))
node_kafka["Kafka"]

node_user -->|"manages repos"| node_repo_controller
node_github -->|"OAuth profile"| node_oauth_service
node_oauth_service -->|"reads/writes users"| node_user_store
node_oauth_handler -->|"loads user"| node_user_store
node_oauth_handler -->|"generates token"| node_jwt
node_user -->|"requests profile"| node_auth_controller
node_auth_controller -->|"loads user"| node_user_store
node_repo_controller -->|"delegates"| node_repo_service
node_repo_service -->|"loads user"| node_user_store
node_repo_service -->|"manages repos"| node_repo_store
node_github -->|"sends webhook"| node_webhook_controller
node_webhook_controller -->|"validates event"| node_webhook_service
node_webhook_service -->|"looks up repo"| node_repo_store
node_webhook_service -->|"stores event"| node_outbox_store
node_review_service -->|"saves findings"| node_finding_store
node_review_service -->|"saves review"| node_review_store
node_review_service -->|"posts comments"| node_github_client
node_github_client -->|"comments on PR"| node_github

click node_oauth_service "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/CustomOAuth2UserService.java"
click node_oauth_handler "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/config/OAuth2SuccessHandler.java"
click node_jwt "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/JwtService.java"
click node_auth_controller "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/AuthController.java"
click node_user_store "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/UserRepository.java"
click node_repo_controller "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/RepoController.java"
click node_repo_service "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/RepoService.java"
click node_repo_store "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/RepoRepository.java"
click node_webhook_controller "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/WebhookController.java"
click node_webhook_service "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/WebhookService.java"
click node_outbox_store "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/OutboxRepository.java"
click node_outbox_publisher "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/OutboxPublisher.java"
click node_review_consumer "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/consumer/ReviewConsumer.java"
click node_ai_client "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/client/AiServiceClient.java"
click node_review_service "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/ReviewService.java"
click node_review_store "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/ReviewRepository.java"
click node_finding_store "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/ReviewFindingRepository.java"
click node_github_client "https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/client/GitHubClient.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_oauth_service,node_oauth_handler,node_jwt,node_auth_controller,node_user_store,node_user toneBlue
class node_repo_controller,node_repo_service,node_repo_store toneAmber
class node_webhook_controller,node_webhook_service,node_outbox_store,node_outbox_publisher toneMint
class node_review_consumer,node_ai_client,node_review_service,node_review_store,node_finding_store,node_github_client toneRose
class node_github,node_kafka toneIndigo
```

## Components

### Identity

- [OAuth User Sync](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/CustomOAuth2UserService.java): `src/main/java/com/DiffHawk/service/CustomOAuth2UserService.java`
- [OAuth Success](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/config/OAuth2SuccessHandler.java): `src/main/java/com/DiffHawk/config/OAuth2SuccessHandler.java`
- [JWT Service](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/JwtService.java): `src/main/java/com/DiffHawk/service/JwtService.java`
- [Auth API](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/AuthController.java): `src/main/java/com/DiffHawk/controller/AuthController.java`
- [Users](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/UserRepository.java): `src/main/java/com/DiffHawk/repository/UserRepository.java`

### Repository Setup

- [Repository API](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/RepoController.java): `src/main/java/com/DiffHawk/controller/RepoController.java`
- [Repository Management](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/RepoService.java): `src/main/java/com/DiffHawk/service/RepoService.java`
- [Repositories](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/RepoRepository.java): `src/main/java/com/DiffHawk/repository/RepoRepository.java`

### Review Events

- [Webhook API](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/controller/WebhookController.java): `src/main/java/com/DiffHawk/controller/WebhookController.java`
- [Webhook Validation](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/WebhookService.java): `src/main/java/com/DiffHawk/service/WebhookService.java`
- [Outbox Events](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/OutboxRepository.java): `src/main/java/com/DiffHawk/repository/OutboxRepository.java`
- [Outbox Publisher](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/OutboxPublisher.java): `src/main/java/com/DiffHawk/service/OutboxPublisher.java`

### Review Processing

- [Review Consumer](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/consumer/ReviewConsumer.java): `src/main/java/com/DiffHawk/consumer/ReviewConsumer.java`
- [AI Service Client](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/client/AiServiceClient.java): `src/main/java/com/DiffHawk/client/AiServiceClient.java`
- [Review Results](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/service/ReviewService.java): `src/main/java/com/DiffHawk/service/ReviewService.java`
- [Reviews](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/ReviewRepository.java): `src/main/java/com/DiffHawk/repository/ReviewRepository.java`
- [Review Findings](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/repository/ReviewFindingRepository.java): `src/main/java/com/DiffHawk/repository/ReviewFindingRepository.java`
- [GitHub Client](https://github.com/srikanthreddyvvs/diffhawk/blob/main/src/main/java/com/DiffHawk/client/GitHubClient.java): `src/main/java/com/DiffHawk/client/GitHubClient.java`

### Other components

- **User**
- **GitHub**
- **Kafka**

## Connections

- User → Repository API: manages repos
- GitHub → OAuth User Sync: OAuth profile
- OAuth User Sync → Users: reads/writes users
- OAuth Success → Users: loads user
- OAuth Success → JWT Service: generates token
- User → Auth API: requests profile
- Auth API → Users: loads user
- Repository API → Repository Management: delegates
- Repository Management → Users: loads user
- Repository Management → Repositories: manages repos
- GitHub → Webhook API: sends webhook
- Webhook API → Webhook Validation: validates event
- Webhook Validation → Repositories: looks up repo
- Webhook Validation → Outbox Events: stores event
- Review Results → Review Findings: saves findings
- Review Results → Reviews: saves review
- Review Results → GitHub Client: posts comments
- GitHub Client → GitHub: comments on PR