CodeGuardian AI

AI-powered Pull Request intelligence for GitHub — built on Anthropic Claude

---

🧠 Concept

CodeGuardian AI is a GitHub App that eliminates the most painful bottlenecks in the Pull Request lifecycle. By embedding a Claude-powered agent directly into GitHub's review workflow, it frees senior engineers from repetitive review tasks while raising the quality bar for every PR — automatically.

Target customer: CTOs and VPs of Engineering at tech companies with 10–200 engineers who use GitHub and want faster PR cycles, more consistent code quality, and less reviewer burnout.

---

🏗️ Architecture

GitHub ─── webhook (POST /api/webhooks/github) ──► WebhookController
                                                         │  HMAC-SHA256 validation
                                                         ▼
                                                  GitHubWebhookService
                                                  (Virtual Thread dispatch)
                                                         │
                                          ┌──────────────┼──────────────┐
                                          ▼              ▼              ▼
                                    PR Summary         Q&A        Refactoring
                                          └──────────────┼──────────────┘
                                                         ▼
                                              PullRequestAnalysisService
                                                    │           │
                                             GitHubApiClient  AnthropicApiClient
                                             (WebClient)      (WebClient)
                                                    │           │
                                              GitHub API    Claude API
                                                         │
                                              RepositoryConfigRepository
                                                         │
                                                    PostgreSQL
                                                (per-repo config)

Admin API ── REST (/api/config/repositories) ──► RepositoryConfigController

Key design decisions

Decision	Rationale
Virtual Threads	Webhook handler returns 200 OK in < 5 ms; all AI processing runs off-thread without blocking Tomcat workers.
Reactive WebClient	Non-blocking calls to GitHub and Anthropic APIs; both clients compose as Mono chains.
Per-repo API keys	Customers supply their own Anthropic key. CodeGuardian never pools keys across tenants.
HMAC-SHA256 validation	Every webhook is verified before deserialization, preventing spoofed payloads.
Records for DTOs	Immutable, compact, zero-boilerplate. All GitHub/Anthropic payloads are modelled as Java Records.

---

📡 API Endpoints

Webhook Receiver

Method	Path	Description
%%INLINE2%%	%%INLINE3%%	Receives all GitHub webhook events

Required headers:

• %%INLINE4%% — event type (%%INLINE5%%, %%INLINE6%%, %%INLINE7%%)
• %%INLINE8%% — HMAC-SHA256 signature (%%INLINE9%%)
• X-GitHub-Delivery — unique delivery UUID (used for logging)

Processed events:

Event	Action	Behaviour
%%INLINE11%%	%%INLINE12%%	Posts PR summary + refactoring suggestions
%%INLINE13%%	%%INLINE14%% on PR with @codeguardian	Answers the question in context
%%INLINE16%%	any	Returns %%INLINE17%%

---

Repository Configuration API

Method	Path	Description
%%INLINE18%%	%%INLINE19%%	List all configured repositories
%%INLINE20%%	%%INLINE21%%	Get config for one repository
%%INLINE22%%	%%INLINE23%%	Create or update config (upsert)
%%INLINE24%%	%%INLINE25%%	Remove configuration

POST body example:

{
  "repositoryFullName": "acme-corp/backend-api",
  "anthropicApiKey": "sk-ant-...",
  "enablePrSummary": true,
  "enableQna": true,
  "enableRefactoring": true
}

GET response example:

{
  "id": 1,
  "repositoryFullName": "acme-corp/backend-api",
  "enablePrSummary": true,
  "enableQna": true,
  "enableRefactoring": true,
  "createdAt": "2026-04-02T10:00:00",
  "updatedAt": "2026-04-02T10:00:00"
}

⚠️ The Anthropic API key is never returned in responses.

---

Health & Observability

Method	Path	Description
%%INLINE26%%	%%INLINE27%%	Liveness/readiness probe
%%INLINE28%%	%%INLINE29%%	Application metadata
%%INLINE30%%	%%INLINE31%%	Micrometer metrics

---

✨ MVP Features

1. Automatic PR Summary (enablePrSummary)

When a PR is opened, CodeGuardian fetches its unified diff and asks Claude to produce:

• 📋 Summary — what changed and why
• 🔥 High-Risk Files — files most likely to introduce bugs
• ⏱️ Review Effort — Low / Medium / High estimate
• ✅ Key Points — most important things to verify

2. Contextual Q&A (enableQna)

Developers mention @codeguardian <question> in any PR comment. The agent:

1. Detects the mention via isBotMentioned()
2. Fetches the PR diff as context
3. Sends the question + diff to Claude
4. Posts the answer as a reply comment

Example: @codeguardian what's the performance impact of switching to ArrayList here?

3. Proactive Refactoring Suggestions (enableRefactoring)

On every new PR, CodeGuardian scans the diff for:

• Poor variable/method naming
• Logic that can be simplified (nested ifs → guard clauses)
• Duplicated code
• O(n²) patterns with trivial O(n) alternatives
• SOLID principle violations

Each suggestion includes the file path, problem description, and an improved code snippet.

4. Per-Repository Configuration (/api/config/repositories)

Repository admins connect their own Anthropic API key and enable/disable each feature independently. Configuration is persisted in PostgreSQL.

---

🛠️ How to Run

Prerequisites

• Java 25
• Maven 3.9+
• PostgreSQL 16+ (or Docker)

1. Start PostgreSQL

docker run -d \
  --name codeguardian-db \
  -e POSTGRES_DB=codeguardian \
  -e POSTGRES_USER=cg \
  -e POSTGRES_PASSWORD=cg_secret \
  -p 5432:5432 \
  postgres:16

2. Configure application.yml (or environment variables)

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/codeguardian
    username: cg
    password: cg_secret
  jpa:
    hibernate:
      ddl-auto: update

codeguardian:
  github-webhook-secret: your-github-webhook-secret
  anthropic-api-key: sk-ant-your-global-fallback-key   # optional, per-repo keys take precedence
  anthropic-model: claude-opus-4-5

Or via environment variables:

export CODEGUARDIAN_GITHUBWEBHOOKSECRET=your-secret
export CODEGUARDIAN_ANTHROPICAPIKEY=sk-ant-...
export GITHUB_TOKEN=ghp_your_installation_token

3. Build and run

mvn clean package -DskipTests
java -jar target/code-guardian-ai-0.0.1-SNAPSHOT.jar

4. Register the GitHub webhook

In your GitHub repository: Settings → Webhooks → Add webhook

• Payload URL: https://your-domain.com/api/webhooks/github
• Content type: application/json
• Secret: same value as CODEGUARDIAN_GITHUBWEBHOOKSECRET
• Events: %%INLINE43%%, %%INLINE44%%

5. Configure a repository

curl -X POST http://localhost:8080/api/config/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "repositoryFullName": "your-org/your-repo",
    "anthropicApiKey": "sk-ant-...",
    "enablePrSummary": true,
    "enableQna": true,
    "enableRefactoring": true
  }'

---

📦 Package Structure

com.forge.solutions.codeguardianai/
├── config/
│   ├── AppProperties.java          # @ConfigurationProperties record
│   ├── JacksonConfig.java          # Jackson 3 / JsonMapper bean (pre-written)
│   └── WebClientConfig.java        # GitHub & Anthropic WebClient beans
├── controller/
│   ├── RepositoryConfigController.java  # Admin REST API
│   └── WebhookController.java           # GitHub webhook receiver
├── dto/
│   ├── RepositoryConfigRequest.java
│   └── RepositoryConfigResponse.java
├── model/
│   ├── RepositoryConfig.java       # JPA entity
│   ├── anthropic/
│   │   ├── ClaudeRequest.java
│   │   ├── ClaudeResponse.java
│   │   ├── ContentBlock.java
│   │   ├── Message.java
│   │   └── Usage.java
│   └── github/
│       ├── GitHubRepository.java
│       ├── GitHubUser.java
│       ├── Installation.java
│       ├── IssueCommentData.java
│       ├── IssueCommentEventPayload.java
│       ├── IssueData.java
│       ├── PullRequestData.java
│       ├── PullRequestEventPayload.java
│       ├── PullRequestLink.java
│       └── PullRequestRef.java
├── repository/
│   └── RepositoryConfigRepository.java  # Spring Data JPA
└── service/
    ├── AnthropicApiClient.java          # Reactive Anthropic API client
    ├── GitHubApiClient.java             # Reactive GitHub API client
    ├── GitHubWebhookService.java        # Webhook orchestration + Virtual Threads
    ├── PullRequestAnalysisService.java  # Core AI analysis logic
    └── WebhookSignatureValidator.java   # HMAC-SHA256 verification

---

💰 Business Analysis

Problem & Market Size

PR review bottlenecks cost engineering teams an estimated 4–6 hours/engineer/week in waiting time and context-switching. At $150K average eng salary, a 50-person team loses ~$1.5M/year in productivity to review friction. The GitHub Marketplace already has >50M developers as a distribution channel with zero CAC for initial discovery.

Revenue Model (SaaS API-first)

Tier	Price	Limits
Free	$0/month	Public repos, 50 PR analyses/month
Team	$29/month	Up to 10 private repos, unlimited analyses
Business	$99/month	Unlimited repos, priority support, SSO
Enterprise	Custom	Self-hosted, Vault integration, SLA

Competitive Advantages

1. Per-repo API keys — enterprises keep their code out of shared model contexts
2. Feature granularity — admins enable only what they want, reducing noise
3. Virtual Thread architecture — handles GitHub's bursty webhook traffic at minimal infrastructure cost
4. Open-source friendly — generous free tier drives bottom-up adoption

Go-to-Market

1. List on GitHub Marketplace (zero-friction install, OAuth app permissions)
2. Target open-source maintainers first (free tier → word-of-mouth)
3. Upsell to company accounts through GitHub organisation detection
4. Content marketing via GitHub trending repos and developer newsletters

---

🔗 References

• Claude Code Action Repository
• Anthropic Claude Messages API
• GitHub Webhooks Documentation
• GitHub App Authentication
• Spring Boot 4.0 Reference
• Virtual Threads (JEP 444)

---

FinOps Analysis

Estimación de Costos Operativos Mensuales

Para la fase de micro-startup de CodeGuardian AI, hemos proyectado los siguientes costos operativos mensuales:

• Tokens LLM (Anthropic Claude 3): ~$100/mes

* Basado en un uso estimado de ~2 millones de tokens al mes, considerando una mezcla de modelos Claude 3 Haiku y Sonnet para diferentes complejidades de tarea (análisis de PR, Q&A contextual).

• Infraestructura Cloud (AWS): ~$40/mes

* Incluye una instancia EC2 t3.small para la aplicación Spring Boot y una instancia RDS PostgreSQL t3.micro para la base de datos.

• Monitoring y Logging: ~$10/mes

* Cubre servicios básicos de monitoreo en la nube (ej. CloudWatch) y una capa inicial de logging y gestión de errores (ej. Sentry free/developer tier).

• Total de Costos Operativos Mensuales: ~$150

Estimación de Ingresos Mensuales

Considerando un modelo de monetización SaaS basado en GitHub App, con un pricing por niveles, proyectamos un ingreso inicial con una base de clientes modesta:

• Precio por Cliente/Repositorio: Asumimos un precio promedio de $50/mes por cliente (podría ser por un número limitado de desarrolladores o repositorios).
• Número de Clientes (MVP): 10 clientes de pago.
• Ingresos Mensuales Totales: ~$500

Margen de Beneficio

Calculando el margen de beneficio operativo para esta fase inicial:

Margen de Beneficio: ((Ingresos - Costos) / Ingresos) 100 (($500 - $150) / $500) 100 = (350 / 500) * 100 = 70%

Este margen del 70% es saludable para una startup SaaS en etapa temprana, demostrando una fuerte economía unitaria, aunque no incluye los costos de adquisición de clientes ni de desarrollo.

Optimizaciones FinOps Clave

Para mantener y mejorar este margen a medida que la startup escala, las siguientes optimizaciones FinOps son cruciales:

1. Optimización del Modelo LLM: Utilizar estratégicamente el modelo Claude 3 Haiku, de menor costo y alta velocidad, para tareas menos complejas como resúmenes iniciales o sugerencias de refactorización simples. Reservar modelos más potentes (Sonnet, Opus) solo para Q&A complejos o análisis de alto riesgo donde la precisión es crítica.
2. Estrategias de Caching: Implementar un sistema de caché para las respuestas de la API de LLM. Esto es especialmente útil para fragmentos de código, patrones comunes o preguntas frecuentes que puedan repetirse en diferentes Pull Requests o repositorios, reduciendo las llamadas redundantes a la API de Anthropic.
3. Prompt Engineering Eficiente: Invertir en la mejora continua de los prompts para que sean concisos y efectivos. Reducir el número de tokens de entrada sin sacrificar la calidad de la respuesta es una de las formas más directas de disminuir los costos de LLM.
4. Procesamiento Asíncrono y por Lotes: Para funcionalidades que no requieren retroalimentación inmediata (ej. sugerencias proactivas de refactorización), considerar el procesamiento por lotes durante las horas de menor actividad. Esto podría permitir el uso de tarifas de LLM más bajas o una mejor utilización de los recursos de infraestructura.
5. Adopción de Arquitectura Serverless: Migrar la aplicación a una arquitectura serverless (ej. AWS Lambda + API Gateway para los webhooks, o ECS Fargate con auto-escalado) para pagar solo por los recursos consumidos. Esto elimina los costos fijos de instancias inactivas y escala automáticamente con la demanda.
6. Base de Datos Elástica: Utilizar opciones de bases de datos serverless como Amazon Aurora Serverless v2 para PostgreSQL. Esto permite que la base de datos escale la capacidad de manera instantánea y se pause cuando no está en uso, optimizando drásticamente los costos basados en patrones de uso reales.
7. Filtrado Inteligente de Webhooks: Implementar lógica para filtrar y procesar solo los eventos de webhook de GitHub que sean directamente relevantes para las funcionalidades activas de CodeGuardian AI, evitando el procesamiento y las llamadas a LLM innecesarias.