# shahebaz2210/codesentinel architecture

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

- Interactive diagram: https://gitdiagram.com/shahebaz2210/codesentinel
- Repository: https://github.com/shahebaz2210/codesentinel

## Overview

CodeSentinel is a DevSecOps security platform: teams connect GitHub repositories, trigger scans from the UI or pull-request events, then review prioritized findings and remediation. Its scan pipeline runs static and secret analysis, enriches findings with repository context and security knowledge, applies AI assessment and policy gates, and reports results to GitHub and the dashboard. The README documents dashboard, audit, RBAC, RAG, and PR feedback capabilities; their detailed wiring is not fully visible in sampled source, so only documented relationships are shown.

Main entry points: [`backend/app/workers/scan_pipeline.py`](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/workers/scan_pipeline.py) (Scan pipeline), [`backend/app/api/v1`](https://github.com/shahebaz2210/codesentinel/tree/main/backend/app/api/v1) (API routes), [`backend/app/services/github.py`](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/github.py) (GitHub integration), [`backend/app/api/v1/webhooks.py`](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/api/v1/webhooks.py) (Webhook endpoint)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web application"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["API and integrations"]
  node_api_server["FastAPI application<br/>[main.py]"]
  node_api_routes["API routes"]
  node_repo_service["Repository management<br/>[repository.py]"]
  node_webhook_route["Webhook endpoint<br/>[webhooks.py]"]
  node_webhook_service["Webhook processing<br/>[webhook.py]"]
  node_scan_service["Scan requests<br/>[scan.py]"]
  node_github_service["GitHub integration<br/>[github.py]"]
  node_audit_service["Audit logging<br/>[audit.py]"]
  node_dashboard_service["Dashboard metrics<br/>[dashboard.py]"]
end

subgraph group_scan["Scanning workflow"]
  node_worker["Scan worker<br/>[scan_worker.py]"]
  node_pipeline["Scan pipeline<br/>[scan_pipeline.py]"]
  node_scanners["SAST and secret scanners"]
  node_context["Code context<br/>[context_builder.py]"]
  node_finding_service["Finding management<br/>[finding.py]"]
  node_risk_service["Risk scoring<br/>[risk.py]"]
  node_policy_service["Policy gates<br/>[policy.py]"]
end

subgraph group_intelligence["Security intelligence"]
  node_intelligence_service["Knowledge retrieval<br/>[intelligence.py]"]
  node_embeddings["Knowledge embeddings<br/>[embeddings.py]"]
  node_ai_assessment["AI assessment<br/>[ai_assessment.py]"]
end

subgraph group_state["Platform state"]
  node_queue["Redis job queue<br/>[redis.py]"]
  node_database[("PostgreSQL and pgvector<br/>[database.py]")]
end

node_engineer(("Engineering team"))
node_gemini{{"Google Gemini"}}
node_github{{"GitHub"}}

node_engineer -->|"uses"| node_web
node_web -->|"requests data"| node_api_client
node_api_client -->|"REST calls"| node_api_server
node_api_server -->|"dispatches"| node_api_routes
node_api_routes -->|"manages repositories"| node_repo_service
node_api_routes -->|"triggers scans"| node_scan_service
node_api_routes -->|"routes webhooks"| node_webhook_route
node_webhook_route -->|"passes event"| node_webhook_service
node_github -->|"sends events"| node_webhook_route
node_webhook_service -->|"triggers PR scan"| node_scan_service
node_repo_service -->|"fetches repositories"| node_github_service
node_github_service -->|"GitHub API"| node_github
node_scan_service -->|"enqueues job"| node_queue
node_queue -->|"dispatches job"| node_worker
node_worker -->|"runs scan"| node_pipeline
node_pipeline -->|"runs analysis"| node_scanners
node_pipeline -->|"extracts context"| node_context
node_pipeline -->|"retrieves knowledge"| node_intelligence_service
node_pipeline -->|"assesses findings"| node_ai_assessment
node_ai_assessment -->|"requests assessment"| node_gemini
node_pipeline -->|"evaluates gates"| node_policy_service
node_pipeline -->|"scores risk"| node_risk_service
node_pipeline -->|"records findings"| node_finding_service
node_intelligence_service -->|"queries vectors"| node_database
node_embeddings -->|"stores vectors"| node_database
node_pipeline -->|"persists scan results"| node_database
node_api_routes -->|"requests metrics"| node_dashboard_service
node_api_routes -->|"requests audit data"| node_audit_service
node_pipeline -->|"posts PR feedback"| node_github_service
node_github_service -->|"posts checks and comments"| node_github

click node_web "https://github.com/shahebaz2210/codesentinel/tree/main/frontend/app"
click node_api_client "https://github.com/shahebaz2210/codesentinel/blob/main/frontend/lib/api.ts"
click node_api_server "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/main.py"
click node_api_routes "https://github.com/shahebaz2210/codesentinel/tree/main/backend/app/api/v1"
click node_repo_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/repository.py"
click node_webhook_route "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/api/v1/webhooks.py"
click node_webhook_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/webhook.py"
click node_scan_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/scan.py"
click node_queue "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/core/redis.py"
click node_worker "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/workers/scan_worker.py"
click node_pipeline "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/workers/scan_pipeline.py"
click node_scanners "https://github.com/shahebaz2210/codesentinel/tree/main/backend/app/scanners"
click node_context "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/ai/context_builder.py"
click node_finding_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/finding.py"
click node_risk_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/risk.py"
click node_intelligence_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/intelligence.py"
click node_embeddings "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/embeddings.py"
click node_ai_assessment "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/ai_assessment.py"
click node_policy_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/policy.py"
click node_github_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/github.py"
click node_database "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/core/database.py"
click node_audit_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/audit.py"
click node_dashboard_service "https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/dashboard.py"

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_web,node_api_client toneBlue
class node_api_server,node_api_routes,node_repo_service,node_webhook_route,node_webhook_service,node_scan_service,node_github_service,node_audit_service,node_dashboard_service toneAmber
class node_worker,node_pipeline,node_scanners,node_context,node_finding_service,node_risk_service,node_policy_service toneMint
class node_intelligence_service,node_embeddings,node_ai_assessment toneRose
class node_queue,node_database,node_engineer,node_gemini,node_github toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/shahebaz2210/codesentinel/tree/main/frontend/app): `frontend/app`
- [API client](https://github.com/shahebaz2210/codesentinel/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### API and integrations

- [FastAPI application](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/main.py): `backend/app/main.py`
- [API routes](https://github.com/shahebaz2210/codesentinel/tree/main/backend/app/api/v1): `backend/app/api/v1`
- [Repository management](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/repository.py): `backend/app/services/repository.py`
- [Webhook endpoint](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/api/v1/webhooks.py): `backend/app/api/v1/webhooks.py`
- [Webhook processing](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/webhook.py): `backend/app/services/webhook.py`
- [Scan requests](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/scan.py): `backend/app/services/scan.py`
- [GitHub integration](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/github.py): `backend/app/services/github.py`
- [Audit logging](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/audit.py): `backend/app/services/audit.py`
- [Dashboard metrics](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/dashboard.py): `backend/app/services/dashboard.py`

### Scanning workflow

- [Scan worker](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/workers/scan_worker.py): `backend/app/workers/scan_worker.py`
- [Scan pipeline](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/workers/scan_pipeline.py): `backend/app/workers/scan_pipeline.py`
- [SAST and secret scanners](https://github.com/shahebaz2210/codesentinel/tree/main/backend/app/scanners): `backend/app/scanners`
- [Code context](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/ai/context_builder.py): `backend/app/ai/context_builder.py`
- [Finding management](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/finding.py): `backend/app/services/finding.py`
- [Risk scoring](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/risk.py): `backend/app/services/risk.py`
- [Policy gates](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/policy.py): `backend/app/services/policy.py`

### Security intelligence

- [Knowledge retrieval](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/intelligence.py): `backend/app/services/intelligence.py`
- [Knowledge embeddings](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/embeddings.py): `backend/app/services/embeddings.py`
- [AI assessment](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/services/ai_assessment.py): `backend/app/services/ai_assessment.py`

### Platform state

- [Redis job queue](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/core/redis.py): `backend/app/core/redis.py`
- [PostgreSQL and pgvector](https://github.com/shahebaz2210/codesentinel/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Other components

- **Engineering team**
- **Google Gemini**
- **GitHub**

## Connections

- Engineering team → Web application: uses
- Web application → API client: requests data
- API client → FastAPI application: REST calls
- FastAPI application → API routes: dispatches
- API routes → Repository management: manages repositories
- API routes → Scan requests: triggers scans
- API routes → Webhook endpoint: routes webhooks
- Webhook endpoint → Webhook processing: passes event
- GitHub → Webhook endpoint: sends events
- Webhook processing → Scan requests: triggers PR scan
- Repository management → GitHub integration: fetches repositories
- GitHub integration → GitHub: GitHub API
- Scan requests → Redis job queue: enqueues job
- Redis job queue → Scan worker: dispatches job
- Scan worker → Scan pipeline: runs scan
- Scan pipeline → SAST and secret scanners: runs analysis
- Scan pipeline → Code context: extracts context
- Scan pipeline → Knowledge retrieval: retrieves knowledge
- Scan pipeline → AI assessment: assesses findings
- AI assessment → Google Gemini: requests assessment
- Scan pipeline → Policy gates: evaluates gates
- Scan pipeline → Risk scoring: scores risk
- Scan pipeline → Finding management: records findings
- Knowledge retrieval → PostgreSQL and pgvector: queries vectors
- Knowledge embeddings → PostgreSQL and pgvector: stores vectors
- Scan pipeline → PostgreSQL and pgvector: persists scan results
- API routes → Dashboard metrics: requests metrics
- API routes → Audit logging: requests audit data
- Scan pipeline → GitHub integration: posts PR feedback
- GitHub integration → GitHub: posts checks and comments