How venugopalreddy787/aishield works
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: scan-worker.ts Scan Worker · api.ts Dashboard API Client · scan.routes.ts Scan Routes · app.ts REST API
Components 21
API and Persistence
- REST API
apps/api/src/app.ts - Scan Routes
apps/api/src/routes/scan.routes.ts - Repository Routes
apps/api/src/routes/repository.routes.ts - Scan Queue
apps/api/src/queue/scan-queue.ts - MongoDB
apps/api/src/db/mongo.ts - Scan and Debt Models
apps/api/src/models
Scan and Analysis
- Scan Worker
apps/worker/src/queue/scan-worker.ts - Scanner Orchestrator
apps/worker/src/scanners/scanner-orchestrator.ts - Deterministic Scanners
apps/worker/src/scanners - AI Context Runner
apps/worker/src/runners/ai-runner.ts - AI Analyzer
services/ai-analyzer/src/analyzer.ts
Debt and Review
- Finding Normalizer
apps/worker/src/engine/finding-normalizer-engine.ts - Debt Scoring Engine
apps/worker/src/engine/debt-scoring-engine.ts - PR Policy Engine
apps/worker/src/github/policy-engine.ts - PR Reporter
apps/worker/src/github/pr-reporter.ts
Developer Dashboard
- Dashboard Pages
apps/web/src/pages - Dashboard API Client
apps/web/src/services/api.ts - Debt History View
apps/web/src/pages/DebtHistoryPage.tsx
Other components
- GitHub PR
- GitHub
- Developer
Connections 24
- GitHub PR → REST API: requests scans
README.md - REST API → Scan Routes: mounts routes
apps/api/src/app.ts - Scan Routes → Scan Queue: enqueues scans
apps/api/src/routes/scan.routes.ts - Scan Routes → Scan and Debt Models: reads scan data
apps/api/src/routes/scan.routes.ts - Repository Routes → Scan and Debt Models: reads repository data
apps/api/src/routes/repository.routes.ts - Scan Worker → Scan Queue: dequeues jobs
README.md - Scan Worker → Scanner Orchestrator: creates orchestrator
apps/worker/src/queue/scan-worker.ts - Scanner Orchestrator → Deterministic Scanners: dispatches scans
apps/worker/src/scanners/scanner-orchestrator.ts - Scan Worker → AI Context Runner: executes analysis
apps/worker/src/queue/scan-worker.ts - AI Context Runner → AI Analyzer: requests context analysis
- Deterministic Scanners → AI Analyzer: provides findings
README.md - Scan Worker → Finding Normalizer: normalizes findings
apps/worker/src/queue/scan-worker.ts - Scan Worker → Debt Scoring Engine: calculates debt
apps/worker/src/queue/scan-worker.ts - Debt Scoring Engine → Finding Normalizer: deduplicates findings
apps/worker/src/engine/debt-scoring-engine.ts - Scan Worker → MongoDB: persists results
apps/worker/src/queue/scan-worker.ts - Scan Worker → PR Policy Engine: evaluates policy
apps/worker/src/queue/scan-worker.ts - Scan Worker → PR Reporter: reports review
apps/worker/src/queue/scan-worker.ts - PR Reporter → GitHub: posts comments and checks
README.md - Dashboard Pages → Dashboard API Client: requests data
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
README.md - Scan and Debt Models → MongoDB: stores domain records