# pranavikameshwari33-star/deployguard architecture

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

## Overview

DeployGuard is a multi-user GitHub deployment observer: users sign in and connect repositories; signed GitHub events become deployment records, which are analyzed, compared with history, and assessed for risk. GitHub Actions results update pipeline state and failed runs create incident memory; a read-only dashboard presents the evidence. The graph preserves documented recovery and recall capabilities. Several subsystem links reflect README-described behavior because their implementation was not included in the sampled source.

Main entry points: [`app/api/webhook/github/route.ts`](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/webhook/github/route.ts) (Webhook receiver), [`lib/risk/analyze-risk.ts`](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/risk/analyze-risk.ts) (Risk assessment), [`lib/pipeline/ingest-push.ts`](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/ingest-push.ts) (Deployment ingestion), [`lib/pipeline/apply-status.ts`](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/apply-status.ts) (Apply pipeline status)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and GitHub"]
  node_auth_start["OAuth start<br/>[route.ts]"]
  node_auth_callback["OAuth callback<br/>[route.ts]"]
  node_github_app["GitHub App<br/>[app.ts]"]
  node_installations["Installation links<br/>[installations.ts]"]
end

subgraph group_ingestion["Event ingestion"]
  node_webhook["Webhook receiver<br/>[route.ts]"]
  node_signature["Signature verification"]
  node_event_parser["Push parser"]
  node_app_events["GitHub event handling<br/>[app-events.ts]"]
  node_ingest["Deployment ingestion<br/>[ingest-push.ts]"]
  node_event_store[("Receipt log<br/>[event-store.ts]")]
end

subgraph group_analysis["Deployment analysis"]
  node_change_analysis["Change analysis<br/>[change-analysis.ts]"]
  node_similarity["Historical matching<br/>[find-similar.ts]"]
  node_risk["Risk assessment<br/>[analyze-risk.ts]"]
  node_risk_validation["Assessment validation<br/>[validate.ts]"]
  node_memory["Deployment memory"]
end

subgraph group_pipeline["Pipeline and recovery"]
  node_status_route["Status endpoint<br/>[route.ts]"]
  node_apply_status["Apply pipeline status<br/>[apply-status.ts]"]
  node_incident_memory["Incident memory<br/>[incident-memory.ts]"]
  node_maintenance["Maintenance recovery<br/>[run.ts]"]
end

subgraph group_experience["Queries and dashboard"]
  node_dashboard_route["Dashboard endpoint<br/>[route.ts]"]
  node_dashboard_data["Dashboard data<br/>[dashboard-data.ts]"]
  node_deployment_api["Deployment listing<br/>[route.ts]"]
  node_recall_api["Memory recall<br/>[route.ts]"]
  node_dashboard_ui["Dashboard UI<br/>[page.tsx]"]
end

node_user(("Repository owner"))
node_github(("GitHub"))
node_actions(("GitHub Actions"))
node_postgres[("PostgreSQL")]
node_hindsight[("Hindsight")]
node_gemini(("Gemini"))

node_user -->|"starts sign-in"| node_auth_start
node_auth_start -->|"redirects to"| node_github
node_github -->|"returns authorization"| node_auth_callback
node_auth_callback -->|"exchanges code"| node_github_app
node_auth_callback -->|"claims installations"| node_installations
node_github -->|"delivers events"| node_webhook
node_webhook -->|"verifies signature"| node_signature
node_webhook -->|"dispatches app events"| node_app_events
node_webhook -->|"parses push"| node_event_parser
node_webhook -->|"records receipt"| node_event_store
node_webhook -->|"ingests deployment"| node_ingest
node_ingest -->|"classifies changes"| node_change_analysis
node_ingest -->|"stores deployment"| node_postgres
node_ingest -->|"stores memory"| node_memory
node_memory -->|"writes memory"| node_hindsight
node_ingest -->|"schedules assessment"| node_risk
node_risk -->|"finds matches"| node_similarity
node_similarity -->|"recalls supporting history"| node_hindsight
node_risk -->|"requests assessment"| node_gemini
node_risk -->|"validates answer"| node_risk_validation
node_risk -->|"stores assessment"| node_postgres
node_actions -->|"reports workflow runs"| node_webhook
node_webhook -->|"dispatches workflow run"| node_app_events
node_app_events -->|"applies run result"| node_apply_status
node_actions -.->|"submits status"| node_status_route
node_status_route -->|"applies status"| node_apply_status
node_apply_status -->|"updates deployment"| node_postgres
node_apply_status -->|"records failure memory"| node_incident_memory
node_apply_status -->|"refreshes risk"| node_risk
node_incident_memory -->|"stores incident"| node_hindsight
node_maintenance -->|"repairs records"| node_postgres
node_maintenance -->|"recovers pushes"| node_ingest
node_maintenance -->|"recovers results"| node_apply_status
node_maintenance -->|"resumes analyses"| node_risk
node_user -->|"views dashboard"| node_dashboard_ui
node_dashboard_ui -->|"requests data"| node_dashboard_route
node_dashboard_route -->|"loads dashboard"| node_dashboard_data
node_dashboard_data -->|"reads history"| node_postgres
node_user -->|"lists deployments"| node_deployment_api
node_deployment_api -->|"reads deployments"| node_postgres
node_user -->|"queries memory"| node_recall_api
node_recall_api -->|"recalls memories"| node_hindsight

click node_auth_start "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/auth/github/route.ts"
click node_auth_callback "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/auth/github/callback/route.ts"
click node_github_app "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/app.ts"
click node_installations "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/installations.ts"
click node_webhook "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/webhook/github/route.ts"
click node_signature "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/verify-signature.ts"
click node_event_parser "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/parse-push-event.ts"
click node_app_events "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/app-events.ts"
click node_ingest "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/ingest-push.ts"
click node_event_store "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/store/event-store.ts"
click node_change_analysis "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/analysis/change-analysis.ts"
click node_similarity "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/similarity/find-similar.ts"
click node_risk "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/risk/analyze-risk.ts"
click node_risk_validation "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/risk/validate.ts"
click node_memory "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/hindsight/deployment-memory.ts"
click node_status_route "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/deployments/status/route.ts"
click node_apply_status "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/apply-status.ts"
click node_incident_memory "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/hindsight/incident-memory.ts"
click node_maintenance "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/maintenance/run.ts"
click node_dashboard_route "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/dashboard/route.ts"
click node_dashboard_data "https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/dashboard/dashboard-data.ts"
click node_deployment_api "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/deployments/route.ts"
click node_recall_api "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/memory/recall/route.ts"
click node_dashboard_ui "https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/page.tsx"

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_auth_start,node_auth_callback,node_github_app,node_installations toneBlue
class node_webhook,node_signature,node_event_parser,node_app_events,node_ingest,node_event_store,node_postgres,node_hindsight toneAmber
class node_change_analysis,node_similarity,node_risk,node_risk_validation,node_memory toneMint
class node_status_route,node_apply_status,node_incident_memory,node_maintenance toneRose
class node_dashboard_route,node_dashboard_data,node_deployment_api,node_recall_api,node_dashboard_ui,node_user,node_github,node_actions,node_gemini toneIndigo
```

## Components

### Access and GitHub

- [OAuth start](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/auth/github/route.ts): `app/auth/github/route.ts`
- [OAuth callback](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/auth/github/callback/route.ts): `app/auth/github/callback/route.ts`
- [GitHub App](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/app.ts): `lib/github/app.ts`
- [Installation links](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/installations.ts): `lib/github/installations.ts`

### Event ingestion

- [Webhook receiver](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/webhook/github/route.ts): `app/api/webhook/github/route.ts`
- [Signature verification](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/verify-signature.ts): `lib/github/verify-signature.ts`
- [Push parser](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/parse-push-event.ts): `lib/github/parse-push-event.ts`
- [GitHub event handling](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/github/app-events.ts): `lib/github/app-events.ts`
- [Deployment ingestion](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/ingest-push.ts): `lib/pipeline/ingest-push.ts`
- [Receipt log](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/store/event-store.ts): `lib/store/event-store.ts`

### Deployment analysis

- [Change analysis](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/analysis/change-analysis.ts): `lib/analysis/change-analysis.ts`
- [Historical matching](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/similarity/find-similar.ts): `lib/similarity/find-similar.ts`
- [Risk assessment](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/risk/analyze-risk.ts): `lib/risk/analyze-risk.ts`
- [Assessment validation](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/risk/validate.ts): `lib/risk/validate.ts`
- [Deployment memory](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/hindsight/deployment-memory.ts): `lib/hindsight/deployment-memory.ts`

### Pipeline and recovery

- [Status endpoint](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/deployments/status/route.ts): `app/api/deployments/status/route.ts`
- [Apply pipeline status](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/pipeline/apply-status.ts): `lib/pipeline/apply-status.ts`
- [Incident memory](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/hindsight/incident-memory.ts): `lib/hindsight/incident-memory.ts`
- [Maintenance recovery](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/maintenance/run.ts): `lib/maintenance/run.ts`

### Queries and dashboard

- [Dashboard endpoint](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/dashboard/route.ts): `app/api/dashboard/route.ts`
- [Dashboard data](https://github.com/pranavikameshwari33-star/deployguard/blob/main/lib/dashboard/dashboard-data.ts): `lib/dashboard/dashboard-data.ts`
- [Deployment listing](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/deployments/route.ts): `app/api/deployments/route.ts`
- [Memory recall](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/api/memory/recall/route.ts): `app/api/memory/recall/route.ts`
- [Dashboard UI](https://github.com/pranavikameshwari33-star/deployguard/blob/main/app/page.tsx): `app/page.tsx`

### Other components

- **Repository owner**
- **GitHub**
- **GitHub Actions**
- **PostgreSQL**
- **Hindsight**
- **Gemini**

## Connections

- Repository owner → OAuth start: starts sign-in
- OAuth start → GitHub: redirects to
- GitHub → OAuth callback: returns authorization
- OAuth callback → GitHub App: exchanges code
- OAuth callback → Installation links: claims installations
- GitHub → Webhook receiver: delivers events
- Webhook receiver → Signature verification: verifies signature
- Webhook receiver → GitHub event handling: dispatches app events
- Webhook receiver → Push parser: parses push
- Webhook receiver → Receipt log: records receipt
- Webhook receiver → Deployment ingestion: ingests deployment
- Deployment ingestion → Change analysis: classifies changes
- Deployment ingestion → PostgreSQL: stores deployment
- Deployment ingestion → Deployment memory: stores memory
- Deployment memory → Hindsight: writes memory
- Deployment ingestion → Risk assessment: schedules assessment
- Risk assessment → Historical matching: finds matches
- Historical matching → Hindsight: recalls supporting history
- Risk assessment → Gemini: requests assessment
- Risk assessment → Assessment validation: validates answer
- Risk assessment → PostgreSQL: stores assessment
- GitHub Actions → Webhook receiver: reports workflow runs
- Webhook receiver → GitHub event handling: dispatches workflow run
- GitHub event handling → Apply pipeline status: applies run result
- GitHub Actions → Status endpoint: submits status
- Status endpoint → Apply pipeline status: applies status
- Apply pipeline status → PostgreSQL: updates deployment
- Apply pipeline status → Incident memory: records failure memory
- Apply pipeline status → Risk assessment: refreshes risk
- Incident memory → Hindsight: stores incident
- Maintenance recovery → PostgreSQL: repairs records
- Maintenance recovery → Deployment ingestion: recovers pushes
- Maintenance recovery → Apply pipeline status: recovers results
- Maintenance recovery → Risk assessment: resumes analyses
- Repository owner → Dashboard UI: views dashboard
- Dashboard UI → Dashboard endpoint: requests data
- Dashboard endpoint → Dashboard data: loads dashboard
- Dashboard data → PostgreSQL: reads history
- Repository owner → Deployment listing: lists deployments
- Deployment listing → PostgreSQL: reads deployments
- Repository owner → Memory recall: queries memory
- Memory recall → Hindsight: recalls memories