# venugopalreddy787/aishield architecture

> Architecture diagram of the GitHub repository venugopalreddy787/aishield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venugopalreddy787/aishield
- Repository: https://github.com/venugopalreddy787/aishield

## Overview

AIShield Debt is a security-debt analysis platform for repositories and GitHub pull requests. The principal workflow accepts a scan request through the API, queues it for background scanning, combines deterministic scanner results with optional AI contextual analysis, normalizes and scores findings, persists scan/debt history, and reports policy results to GitHub and the dashboard. The README documents the high-level phases; source excerpts and the SOURCE INDEX support the specific API, worker, and analysis links shown. Several subsystems are represented by their existing source directories because their detailed implementations were not sampled.

Main entry points: [`apps/worker/src/queue/scan-worker.ts`](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/queue/scan-worker.ts) (Scan Worker), [`apps/web/src/services/api.ts`](https://github.com/venugopalreddy787/aishield/blob/main/apps/web/src/services/api.ts) (Dashboard API Client), [`apps/api/src/routes/scan.routes.ts`](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/routes/scan.routes.ts) (Scan Routes), [`apps/api/src/app.ts`](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/app.ts) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Persistence"]
  node_api_app["REST API<br/>[app.ts]"]
  node_scan_routes["Scan Routes<br/>[scan.routes.ts]"]
  node_repo_routes["Repository Routes"]
  node_scan_queue["Scan Queue<br/>[scan-queue.ts]"]
  node_mongo[("MongoDB<br/>[mongo.ts]")]
  node_domain_models["Scan and Debt Models"]
end

subgraph group_analysis["Scan and Analysis"]
  node_worker["Scan Worker<br/>[scan-worker.ts]"]
  node_scanner_orchestrator["Scanner Orchestrator"]
  node_deterministic_scanners["Deterministic Scanners"]
  node_ai_runner["AI Context Runner<br/>[ai-runner.ts]"]
  node_ai_analyzer["AI Analyzer<br/>[analyzer.ts]"]
end

subgraph group_review["Debt and Review"]
  node_normalizer["Finding Normalizer"]
  node_debt_engine["Debt Scoring Engine"]
  node_policy_engine["PR Policy Engine<br/>[policy-engine.ts]"]
  node_pr_reporter["PR Reporter<br/>[pr-reporter.ts]"]
end

subgraph group_dashboard["Developer Dashboard"]
  node_web_pages["Dashboard Pages"]
  node_web_api["Dashboard API Client<br/>[api.ts]"]
  node_debt_history["Debt History View"]
end

node_github_pr(("GitHub PR"))
node_github_service["GitHub"]
node_developer(("Developer"))

node_github_pr -->|"requests scans"| node_api_app
node_api_app -->|"mounts routes"| node_scan_routes
node_scan_routes -->|"enqueues scans"| node_scan_queue
node_scan_routes -->|"reads scan data"| node_domain_models
node_repo_routes -->|"reads repository data"| node_domain_models
node_worker -->|"dequeues jobs"| node_scan_queue
node_worker -->|"creates orchestrator"| node_scanner_orchestrator
node_scanner_orchestrator -.->|"dispatches scans"| node_deterministic_scanners
node_worker -->|"executes analysis"| node_ai_runner
node_ai_runner -.->|"requests context analysis"| node_ai_analyzer
node_deterministic_scanners -->|"provides findings"| node_ai_analyzer
node_worker -->|"normalizes findings"| node_normalizer
node_worker -->|"calculates debt"| node_debt_engine
node_debt_engine -->|"deduplicates findings"| node_normalizer
node_worker -->|"persists results"| node_mongo
node_worker -->|"evaluates policy"| node_policy_engine
node_worker -->|"reports review"| node_pr_reporter
node_pr_reporter -->|"posts comments and checks"| node_github_service
node_web_pages -->|"requests data"| node_web_api
node_web_api -.->|"calls API"| node_api_app
node_web_api -.->|"loads repositories"| node_repo_routes
node_debt_history -.->|"loads debt history"| node_web_api
node_developer -->|"reviews results"| node_web_pages
node_domain_models -.->|"stores domain records"| node_mongo

click node_api_app "https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/app.ts"
click node_scan_routes "https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/routes/scan.routes.ts"
click node_repo_routes "https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/routes/repository.routes.ts"
click node_scan_queue "https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/queue/scan-queue.ts"
click node_mongo "https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/db/mongo.ts"
click node_domain_models "https://github.com/venugopalreddy787/aishield/tree/main/apps/api/src/models"
click node_worker "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/queue/scan-worker.ts"
click node_scanner_orchestrator "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/scanners/scanner-orchestrator.ts"
click node_deterministic_scanners "https://github.com/venugopalreddy787/aishield/tree/main/apps/worker/src/scanners"
click node_ai_runner "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/runners/ai-runner.ts"
click node_ai_analyzer "https://github.com/venugopalreddy787/aishield/blob/main/services/ai-analyzer/src/analyzer.ts"
click node_normalizer "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/engine/finding-normalizer-engine.ts"
click node_debt_engine "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/engine/debt-scoring-engine.ts"
click node_policy_engine "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/github/policy-engine.ts"
click node_pr_reporter "https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/github/pr-reporter.ts"
click node_web_pages "https://github.com/venugopalreddy787/aishield/tree/main/apps/web/src/pages"
click node_web_api "https://github.com/venugopalreddy787/aishield/blob/main/apps/web/src/services/api.ts"
click node_debt_history "https://github.com/venugopalreddy787/aishield/blob/main/apps/web/src/pages/DebtHistoryPage.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_api_app,node_scan_routes,node_repo_routes,node_scan_queue,node_mongo,node_domain_models toneBlue
class node_worker,node_scanner_orchestrator,node_deterministic_scanners,node_ai_runner,node_ai_analyzer toneAmber
class node_normalizer,node_debt_engine,node_policy_engine,node_pr_reporter toneMint
class node_web_pages,node_web_api,node_debt_history toneRose
class node_github_pr,node_github_service,node_developer toneIndigo
```

## Components

### API and Persistence

- [REST API](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/app.ts): `apps/api/src/app.ts`
- [Scan Routes](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/routes/scan.routes.ts): `apps/api/src/routes/scan.routes.ts`
- [Repository Routes](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/routes/repository.routes.ts): `apps/api/src/routes/repository.routes.ts`
- [Scan Queue](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/queue/scan-queue.ts): `apps/api/src/queue/scan-queue.ts`
- [MongoDB](https://github.com/venugopalreddy787/aishield/blob/main/apps/api/src/db/mongo.ts): `apps/api/src/db/mongo.ts`
- [Scan and Debt Models](https://github.com/venugopalreddy787/aishield/tree/main/apps/api/src/models): `apps/api/src/models`

### Scan and Analysis

- [Scan Worker](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/queue/scan-worker.ts): `apps/worker/src/queue/scan-worker.ts`
- [Scanner Orchestrator](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/scanners/scanner-orchestrator.ts): `apps/worker/src/scanners/scanner-orchestrator.ts`
- [Deterministic Scanners](https://github.com/venugopalreddy787/aishield/tree/main/apps/worker/src/scanners): `apps/worker/src/scanners`
- [AI Context Runner](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/runners/ai-runner.ts): `apps/worker/src/runners/ai-runner.ts`
- [AI Analyzer](https://github.com/venugopalreddy787/aishield/blob/main/services/ai-analyzer/src/analyzer.ts): `services/ai-analyzer/src/analyzer.ts`

### Debt and Review

- [Finding Normalizer](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/engine/finding-normalizer-engine.ts): `apps/worker/src/engine/finding-normalizer-engine.ts`
- [Debt Scoring Engine](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/engine/debt-scoring-engine.ts): `apps/worker/src/engine/debt-scoring-engine.ts`
- [PR Policy Engine](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/github/policy-engine.ts): `apps/worker/src/github/policy-engine.ts`
- [PR Reporter](https://github.com/venugopalreddy787/aishield/blob/main/apps/worker/src/github/pr-reporter.ts): `apps/worker/src/github/pr-reporter.ts`

### Developer Dashboard

- [Dashboard Pages](https://github.com/venugopalreddy787/aishield/tree/main/apps/web/src/pages): `apps/web/src/pages`
- [Dashboard API Client](https://github.com/venugopalreddy787/aishield/blob/main/apps/web/src/services/api.ts): `apps/web/src/services/api.ts`
- [Debt History View](https://github.com/venugopalreddy787/aishield/blob/main/apps/web/src/pages/DebtHistoryPage.tsx): `apps/web/src/pages/DebtHistoryPage.tsx`

### Other components

- **GitHub PR**
- **GitHub**
- **Developer**

## Connections

- GitHub PR → REST API: requests scans (evidence: `README.md`)
- REST API → Scan Routes: mounts routes (evidence: `apps/api/src/app.ts`)
- Scan Routes → Scan Queue: enqueues scans (evidence: `apps/api/src/routes/scan.routes.ts`)
- Scan Routes → Scan and Debt Models: reads scan data (evidence: `apps/api/src/routes/scan.routes.ts`)
- Repository Routes → Scan and Debt Models: reads repository data (evidence: `apps/api/src/routes/repository.routes.ts`)
- Scan Worker → Scan Queue: dequeues jobs (evidence: `README.md`)
- Scan Worker → Scanner Orchestrator: creates orchestrator (evidence: `apps/worker/src/queue/scan-worker.ts`)
- Scanner Orchestrator → Deterministic Scanners: dispatches scans (evidence: `apps/worker/src/scanners/scanner-orchestrator.ts`)
- Scan Worker → AI Context Runner: executes analysis (evidence: `apps/worker/src/queue/scan-worker.ts`)
- AI Context Runner → AI Analyzer: requests context analysis
- Deterministic Scanners → AI Analyzer: provides findings (evidence: `README.md`)
- Scan Worker → Finding Normalizer: normalizes findings (evidence: `apps/worker/src/queue/scan-worker.ts`)
- Scan Worker → Debt Scoring Engine: calculates debt (evidence: `apps/worker/src/queue/scan-worker.ts`)
- Debt Scoring Engine → Finding Normalizer: deduplicates findings (evidence: `apps/worker/src/engine/debt-scoring-engine.ts`)
- Scan Worker → MongoDB: persists results (evidence: `apps/worker/src/queue/scan-worker.ts`)
- Scan Worker → PR Policy Engine: evaluates policy (evidence: `apps/worker/src/queue/scan-worker.ts`)
- Scan Worker → PR Reporter: reports review (evidence: `apps/worker/src/queue/scan-worker.ts`)
- PR Reporter → GitHub: posts comments and checks (evidence: `README.md`)
- Dashboard Pages → Dashboard API Client: requests data (evidence: `apps/web/src/pages/RepositoryPage.tsx`)
- Dashboard API Client → REST API: calls API
- Dashboard API Client → Repository Routes: loads repositories
- Debt History View → Dashboard API Client: loads debt history
- Developer → Dashboard Pages: reviews results (evidence: `README.md`)
- Scan and Debt Models → MongoDB: stores domain records