# senapati484/gitguard architecture

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

## Overview

GitGuard is a GitHub App that reviews pull requests and pushes for leaked secrets, correctness defects, and exploitable security issues, then reports a PASS/WARN/BLOCK verdict through GitHub checks and review feedback. Its main workflow is webhook verification, queued background processing, parallel agent analysis, and verdict publication; users can also trigger scans and remediation. The dashboard exposes run health, policy, and alert controls. The README documents agent behavior and worker flow, but some cited agent files are absent from the tree, so their internals are represented only at the documented subsystem level.

Main entry points: [`agents/orchestrator.ts`](https://github.com/senapati484/gitguard/blob/main/agents/orchestrator.ts) (Agent Orchestrator), [`lib/firebase-admin.ts`](https://github.com/senapati484/gitguard/blob/main/lib/firebase-admin.ts) (Firebase Services), [`app/api/webhooks/github/route.ts`](https://github.com/senapati484/gitguard/blob/main/app/api/webhooks/github/route.ts) (Webhook Handler), [`app/(dashboard)/dashboard/page.tsx`](https://github.com/senapati484/gitguard/blob/main/app/(dashboard)/dashboard/page.tsx) (Dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_intake["GitHub Intake"]
  node_webhook["Webhook Handler<br/>[route.ts]"]
  node_verification["Signature Verification<br/>[verify-webhook.ts]"]
  node_event_queue["GitHub Event Queue<br/>[github-events.ts]"]
  node_worker["Background Worker<br/>[worker.ts]"]
end

subgraph group_review["Review Pipeline"]
  node_github_app["GitHub App Client<br/>[github-app.ts]"]
  node_orchestrator["Agent Orchestrator<br/>[orchestrator.ts]"]
  node_secret_agent["Secret Scanner"]
  node_bug_agent["Bug Agent<br/>[bug-agent.ts]"]
  node_security_agent["Security Agent<br/>[security-agent.ts]"]
end

subgraph group_product["Dashboard and Controls"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_scan_api["Manual Scan API<br/>[route.ts]"]
  node_solve_api["Auto-Solve API<br/>[route.ts]"]
  node_auto_solve["GitHub Remediation<br/>[auto-solve-git.ts]"]
  node_policy_api["Team Policy API<br/>[route.ts]"]
end

subgraph group_state["Identity and State"]
  node_auth["Session Authentication<br/>[auth-session.ts]"]
  node_firebase[("Firebase Services<br/>[firebase-admin.ts]")]
  node_marketplace["Marketplace Plans<br/>[plan-limits.ts]"]
end

subgraph group_insights["Health and Alerts"]
  node_health["Health Reporting<br/>[health-agent.ts]"]
  node_badge["Health Badge API<br/>[route.ts]"]
  node_alert_settings["Alert Settings API<br/>[route.ts]"]
  node_email_agent["Email Alerts<br/>[email-agent.ts]"]
end

node_developer(("Repository Admin"))
node_github(("GitHub"))
node_github_results["Checks and Reviews"]

node_github -->|"sends events"| node_webhook
node_webhook -->|"verifies signature"| node_verification
node_webhook -->|"enqueues events"| node_event_queue
node_event_queue -->|"dispatches jobs"| node_worker
node_worker -->|"fetches repository data"| node_github_app
node_worker -->|"runs review"| node_orchestrator
node_orchestrator -->|"runs parallel scan"| node_secret_agent
node_orchestrator -->|"runs parallel scan"| node_bug_agent
node_orchestrator -->|"runs parallel scan"| node_security_agent
node_orchestrator -->|"publishes verdict"| node_github_results
node_github_results -->|"reports checks"| node_github
node_developer -->|"views results"| node_dashboard
node_dashboard -->|"requests scan"| node_scan_api
node_scan_api -->|"enqueues scan"| node_event_queue
node_dashboard -->|"requests remediation"| node_solve_api
node_solve_api -->|"applies fixes"| node_auto_solve
node_auto_solve -->|"commits remediation"| node_github_app
node_solve_api -->|"updates run state"| node_firebase
node_solve_api -->|"recalculates score"| node_health
node_dashboard -->|"manages policy"| node_policy_api
node_policy_api -->|"reads and writes policy"| node_firebase
node_developer -->|"signs in"| node_auth
node_auth -->|"verifies session"| node_firebase
node_badge -->|"requests report"| node_health
node_health -->|"reads run history"| node_firebase
node_developer -->|"configures alerts"| node_alert_settings
node_alert_settings -->|"saves settings"| node_email_agent
node_webhook -->|"handles purchase events"| node_marketplace
node_marketplace -->|"updates plan state"| node_firebase

click node_webhook "https://github.com/senapati484/gitguard/blob/main/app/api/webhooks/github/route.ts"
click node_verification "https://github.com/senapati484/gitguard/blob/main/lib/verify-webhook.ts"
click node_event_queue "https://github.com/senapati484/gitguard/blob/main/lib/queues/github-events.ts"
click node_worker "https://github.com/senapati484/gitguard/blob/main/worker.ts"
click node_github_app "https://github.com/senapati484/gitguard/blob/main/lib/github-app.ts"
click node_orchestrator "https://github.com/senapati484/gitguard/blob/main/agents/orchestrator.ts"
click node_secret_agent "https://github.com/senapati484/gitguard/tree/main/agents"
click node_bug_agent "https://github.com/senapati484/gitguard/blob/main/agents/bug-agent.ts"
click node_security_agent "https://github.com/senapati484/gitguard/blob/main/agents/security-agent.ts"
click node_dashboard "https://github.com/senapati484/gitguard/blob/main/app/(dashboard)/dashboard/page.tsx"
click node_scan_api "https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/scan/route.ts"
click node_solve_api "https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/auto-solve/route.ts"
click node_auto_solve "https://github.com/senapati484/gitguard/blob/main/lib/auto-solve-git.ts"
click node_policy_api "https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/policy/route.ts"
click node_auth "https://github.com/senapati484/gitguard/blob/main/lib/auth-session.ts"
click node_firebase "https://github.com/senapati484/gitguard/blob/main/lib/firebase-admin.ts"
click node_health "https://github.com/senapati484/gitguard/blob/main/agents/health-agent.ts"
click node_badge "https://github.com/senapati484/gitguard/blob/main/app/api/badge/%5BinstallationId%5D/%5Brepo%5D/route.ts"
click node_alert_settings "https://github.com/senapati484/gitguard/blob/main/app/api/settings/%5BinstallationId%5D/route.ts"
click node_email_agent "https://github.com/senapati484/gitguard/blob/main/agents/email-agent.ts"
click node_marketplace "https://github.com/senapati484/gitguard/blob/main/lib/plan-limits.ts"

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_webhook,node_verification,node_event_queue,node_worker,node_github_results toneBlue
class node_github_app,node_orchestrator,node_secret_agent,node_bug_agent,node_security_agent toneAmber
class node_dashboard,node_scan_api,node_solve_api,node_auto_solve,node_policy_api toneMint
class node_auth,node_firebase,node_marketplace toneRose
class node_health,node_badge,node_alert_settings,node_email_agent,node_developer,node_github toneIndigo
```

## Components

### GitHub Intake

- [Webhook Handler](https://github.com/senapati484/gitguard/blob/main/app/api/webhooks/github/route.ts): `app/api/webhooks/github/route.ts`
- [Signature Verification](https://github.com/senapati484/gitguard/blob/main/lib/verify-webhook.ts): `lib/verify-webhook.ts`
- [GitHub Event Queue](https://github.com/senapati484/gitguard/blob/main/lib/queues/github-events.ts): `lib/queues/github-events.ts`
- [Background Worker](https://github.com/senapati484/gitguard/blob/main/worker.ts): `worker.ts`

### Review Pipeline

- [GitHub App Client](https://github.com/senapati484/gitguard/blob/main/lib/github-app.ts): `lib/github-app.ts`
- [Agent Orchestrator](https://github.com/senapati484/gitguard/blob/main/agents/orchestrator.ts): `agents/orchestrator.ts`
- [Secret Scanner](https://github.com/senapati484/gitguard/tree/main/agents): `agents`
- [Bug Agent](https://github.com/senapati484/gitguard/blob/main/agents/bug-agent.ts): `agents/bug-agent.ts`
- [Security Agent](https://github.com/senapati484/gitguard/blob/main/agents/security-agent.ts): `agents/security-agent.ts`

### Dashboard and Controls

- [Dashboard](https://github.com/senapati484/gitguard/blob/main/app/(dashboard)/dashboard/page.tsx): `app/(dashboard)/dashboard/page.tsx`
- [Manual Scan API](https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/scan/route.ts): `app/api/installations/[id]/scan/route.ts`
- [Auto-Solve API](https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/auto-solve/route.ts): `app/api/installations/[id]/auto-solve/route.ts`
- [GitHub Remediation](https://github.com/senapati484/gitguard/blob/main/lib/auto-solve-git.ts): `lib/auto-solve-git.ts`
- [Team Policy API](https://github.com/senapati484/gitguard/blob/main/app/api/installations/%5Bid%5D/policy/route.ts): `app/api/installations/[id]/policy/route.ts`

### Identity and State

- [Session Authentication](https://github.com/senapati484/gitguard/blob/main/lib/auth-session.ts): `lib/auth-session.ts`
- [Firebase Services](https://github.com/senapati484/gitguard/blob/main/lib/firebase-admin.ts): `lib/firebase-admin.ts`
- [Marketplace Plans](https://github.com/senapati484/gitguard/blob/main/lib/plan-limits.ts): `lib/plan-limits.ts`

### Health and Alerts

- [Health Reporting](https://github.com/senapati484/gitguard/blob/main/agents/health-agent.ts): `agents/health-agent.ts`
- [Health Badge API](https://github.com/senapati484/gitguard/blob/main/app/api/badge/%5BinstallationId%5D/%5Brepo%5D/route.ts): `app/api/badge/[installationId]/[repo]/route.ts`
- [Alert Settings API](https://github.com/senapati484/gitguard/blob/main/app/api/settings/%5BinstallationId%5D/route.ts): `app/api/settings/[installationId]/route.ts`
- [Email Alerts](https://github.com/senapati484/gitguard/blob/main/agents/email-agent.ts): `agents/email-agent.ts`

### Other components

- **Repository Admin**
- **GitHub**
- **Checks and Reviews**

## Connections

- GitHub → Webhook Handler: sends events
- Webhook Handler → Signature Verification: verifies signature
- Webhook Handler → GitHub Event Queue: enqueues events
- GitHub Event Queue → Background Worker: dispatches jobs
- Background Worker → GitHub App Client: fetches repository data
- Background Worker → Agent Orchestrator: runs review
- Agent Orchestrator → Secret Scanner: runs parallel scan
- Agent Orchestrator → Bug Agent: runs parallel scan
- Agent Orchestrator → Security Agent: runs parallel scan
- Agent Orchestrator → Checks and Reviews: publishes verdict
- Checks and Reviews → GitHub: reports checks
- Repository Admin → Dashboard: views results
- Dashboard → Manual Scan API: requests scan
- Manual Scan API → GitHub Event Queue: enqueues scan
- Dashboard → Auto-Solve API: requests remediation
- Auto-Solve API → GitHub Remediation: applies fixes
- GitHub Remediation → GitHub App Client: commits remediation
- Auto-Solve API → Firebase Services: updates run state
- Auto-Solve API → Health Reporting: recalculates score
- Dashboard → Team Policy API: manages policy
- Team Policy API → Firebase Services: reads and writes policy
- Repository Admin → Session Authentication: signs in
- Session Authentication → Firebase Services: verifies session
- Health Badge API → Health Reporting: requests report
- Health Reporting → Firebase Services: reads run history
- Repository Admin → Alert Settings API: configures alerts
- Alert Settings API → Email Alerts: saves settings
- Webhook Handler → Marketplace Plans: handles purchase events
- Marketplace Plans → Firebase Services: updates plan state