# gotingalawrence-sys/vuln-triage-assistant architecture

> Architecture diagram of the GitHub repository gotingalawrence-sys/vuln-triage-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gotingalawrence-sys/vuln-triage-assistant
- Repository: https://github.com/gotingalawrence-sys/vuln-triage-assistant

## Overview

The Vulnerability Triage Assistant accepts a vulnerability title or CVE ID and optional scanner notes, then returns a structured analysis with remediation guidance and ticket-ready text. The main flow runs from the browser through the triage API, validation, optional NVD grounding, AI generation and schema validation, then returns a result with an application-built advisory link. The README documents these capabilities; the sampled source confirms key calls, but some UI rendering and deployment details are only partially shown.

Main entry points: [`app/api/triage/route.ts`](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/api/triage/route.ts) (Triage API), [`lib/triage.ts`](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/triage.ts) (AI triage), [`app/page.tsx`](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/page.tsx) (Triage UI), [`lib/nvd.ts`](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/nvd.ts) (NVD lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_browser["Triage UI<br/>[page.tsx]"]
end

subgraph group_api["Request handling"]
  node_endpoint["Triage API<br/>[route.ts]"]
  node_limiter["Rate limiter<br/>[rateLimit.ts]"]
  node_validation["Input validation<br/>[validation.ts]"]
end

subgraph group_analysis["Triage analysis"]
  node_prompt["Prompt builder<br/>[prompt.ts]"]
  node_generator["AI triage<br/>[triage.ts]"]
  node_schema["Result schema<br/>[schema.ts]"]
  node_advisory["Advisory link builder<br/>[advisory.ts]"]
end

subgraph group_sources["External data and AI"]
  node_lookup["NVD lookup<br/>[nvd.ts]"]
  node_nvd[("NVD service")]
  node_gemini["Gemini API"]
end

node_specialist(("Security specialist"))

node_specialist -->|"submits input"| node_browser
node_browser -->|"posts request"| node_endpoint
node_endpoint -->|"checks rate"| node_limiter
node_endpoint -->|"validates input"| node_validation
node_endpoint -->|"looks up CVE"| node_lookup
node_lookup -->|"fetches CVE data"| node_nvd
node_endpoint -->|"runs triage"| node_generator
node_generator -->|"builds prompt"| node_prompt
node_prompt -->|"formats NVD facts"| node_lookup
node_generator -->|"generates analysis"| node_gemini
node_generator -->|"validates output"| node_schema
node_endpoint -->|"applies CVSS severity"| node_lookup
node_endpoint -->|"builds advisory link"| node_advisory
node_endpoint -->|"returns result"| node_browser
node_browser -->|"shows guidance"| node_specialist

click node_browser "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/page.tsx"
click node_endpoint "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/api/triage/route.ts"
click node_limiter "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/rateLimit.ts"
click node_validation "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/validation.ts"
click node_lookup "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/nvd.ts"
click node_prompt "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/prompt.ts"
click node_generator "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/triage.ts"
click node_schema "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/schema.ts"
click node_advisory "https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/advisory.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_browser toneBlue
class node_endpoint,node_limiter,node_validation toneAmber
class node_prompt,node_generator,node_schema,node_advisory toneMint
class node_lookup,node_nvd,node_gemini toneRose
class node_specialist toneIndigo
```

## Components

### User interaction

- [Triage UI](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/page.tsx): `app/page.tsx`

### Request handling

- [Triage API](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/app/api/triage/route.ts): `app/api/triage/route.ts`
- [Rate limiter](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/rateLimit.ts): `lib/rateLimit.ts`
- [Input validation](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/validation.ts): `lib/validation.ts`

### Triage analysis

- [Prompt builder](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/prompt.ts): `lib/prompt.ts`
- [AI triage](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/triage.ts): `lib/triage.ts`
- [Result schema](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/schema.ts): `lib/schema.ts`
- [Advisory link builder](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/advisory.ts): `lib/advisory.ts`

### External data and AI

- [NVD lookup](https://github.com/gotingalawrence-sys/vuln-triage-assistant/blob/main/lib/nvd.ts): `lib/nvd.ts`
- **NVD service**
- **Gemini API**

### Other components

- **Security specialist**

## Connections

- Security specialist → Triage UI: submits input (evidence: `README.md`)
- Triage UI → Triage API: posts request (evidence: `app/page.tsx`)
- Triage API → Rate limiter: checks rate (evidence: `app/api/triage/route.ts`)
- Triage API → Input validation: validates input (evidence: `app/api/triage/route.ts`)
- Triage API → NVD lookup: looks up CVE (evidence: `app/api/triage/route.ts`)
- NVD lookup → NVD service: fetches CVE data (evidence: `lib/nvd.ts`)
- Triage API → AI triage: runs triage (evidence: `app/api/triage/route.ts`)
- AI triage → Prompt builder: builds prompt (evidence: `lib/triage.ts`)
- Prompt builder → NVD lookup: formats NVD facts (evidence: `lib/prompt.ts`)
- AI triage → Gemini API: generates analysis (evidence: `lib/triage.ts`)
- AI triage → Result schema: validates output (evidence: `lib/triage.ts`)
- Triage API → NVD lookup: applies CVSS severity (evidence: `app/api/triage/route.ts`)
- Triage API → Advisory link builder: builds advisory link (evidence: `app/api/triage/route.ts`)
- Triage API → Triage UI: returns result (evidence: `README.md`)
- Triage UI → Security specialist: shows guidance (evidence: `README.md`)
