# x03tanuj/sentinel-api architecture

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

- Interactive diagram: https://gitdiagram.com/x03tanuj/sentinel-api
- Repository: https://github.com/x03tanuj/sentinel-api

## Overview

SentinelAPI is an authorized-use API security scanner with a React results interface. The principal workflow accepts an OpenAPI contract and target, runs a bounded scan across multiple identities, evaluates differential responses for security findings, and stores results for live monitoring and triage. The README documents the scanner’s major check categories, risk/evidence analysis, and optional evidence-only AI branch. Some subsystem wiring is based on that documentation because the corresponding source was not sampled; uncertain links are omitted.

Main entry points: [`frontend/src/api/client.ts`](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/api/client.ts) (API Client), [`frontend/src/App.tsx`](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/App.tsx) (Web Application), [`backend/app/engine/runner.py`](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/runner.py) (Scan Runner), [`backend/app/routes/ai.py`](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/routes/ai.py) (AI Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Scan Interface"]
  node_webapp["Web Application<br/>[App.tsx]"]
  node_scanpages["Scan Pages<br/>[NewScanPage.tsx]"]
  node_livepage["Live Scan View<br/>[LiveScanPage.tsx]"]
  node_triage["Triage Workspace"]
  node_history["Scan History<br/>[HistoryPage.tsx]"]
  node_client["API Client<br/>[client.ts]"]
end

subgraph group_api["API Orchestration"]
  node_app["FastAPI Application<br/>[main.py]"]
  node_scanroutes["Scan Routes<br/>[scans.py]"]
  node_manager["Scan Manager<br/>[scan_manager.py]"]
  node_store[("Scan Store<br/>[store.py]")]
end

subgraph group_engine["Security Engine"]
  node_parser["OpenAPI Parser<br/>[openapi_loader.py]"]
  node_surface["Surface Mapper<br/>[surface_mapper.py]"]
  node_runner["Scan Runner<br/>[runner.py]"]
  node_identity["Identity Manager<br/>[identity.py]"]
  node_executor["HTTP Executor<br/>[http_executor.py]"]
  node_checks["Security Checks"]
end

subgraph group_analysis["Findings Analysis"]
  node_differential["Differential Analysis<br/>[differential.py]"]
  node_evidence["Evidence &amp; Risk<br/>[evidence.py]"]
  node_report["Report Generation<br/>[report.py]"]
end

subgraph group_ai["Optional AI"]
  node_airoutes["AI Routes<br/>[ai.py]"]
  node_analyst["AI Analyst<br/>[analyst.py]"]
  node_payload["Evidence Payload<br/>[payload.py]"]
  node_providers["Model Providers<br/>[providers.py]"]
end

node_operator(("Scanner User"))
node_contract["OpenAPI Contract"]
node_target{{"Authorized Target API"}}
node_llm{{"External LLM"}}

node_operator -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_scanpages
node_webapp -->|"routes to"| node_livepage
node_webapp -->|"routes to"| node_triage
node_webapp -->|"routes to"| node_history
node_scanpages -->|"submits scan"| node_client
node_livepage -->|"streams events"| node_client
node_triage -->|"fetches results"| node_client
node_history -->|"fetches history"| node_client
node_client -->|"calls API"| node_scanroutes
node_app -->|"includes router"| node_scanroutes
node_scanroutes -->|"delegates lifecycle"| node_manager
node_manager -->|"persists scan state"| node_store
node_manager -->|"runs scan"| node_runner
node_contract -->|"provides specification"| node_parser
node_parser -->|"extracts endpoints"| node_surface
node_surface -->|"prioritizes surface"| node_runner
node_runner -->|"manages personas"| node_identity
node_runner -->|"dispatches probes"| node_executor
node_executor -->|"sends probes"| node_target
node_target -->|"returns responses"| node_executor
node_runner -->|"analyzes responses"| node_differential
node_differential -->|"evaluates differences"| node_checks
node_checks -->|"produces findings"| node_evidence
node_evidence -->|"informs risk report"| node_report
node_evidence -.->|"supplies sanitized findings"| node_airoutes
node_app -->|"includes router"| node_airoutes
node_airoutes -->|"requests analysis"| node_analyst
node_analyst -->|"prepares evidence"| node_payload
node_analyst -->|"selects provider"| node_providers
node_providers -.->|"sends analysis"| node_llm
node_airoutes -.->|"serves AI results"| node_client

click node_webapp "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/App.tsx"
click node_scanpages "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/NewScanPage.tsx"
click node_livepage "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/LiveScanPage.tsx"
click node_triage "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/TriageWorkspacePage.tsx"
click node_history "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/HistoryPage.tsx"
click node_client "https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/api/client.ts"
click node_app "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/main.py"
click node_scanroutes "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/routes/scans.py"
click node_manager "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/scan_manager.py"
click node_store "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/store.py"
click node_parser "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/parser/openapi_loader.py"
click node_surface "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/parser/surface_mapper.py"
click node_runner "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/runner.py"
click node_identity "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/identity.py"
click node_executor "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/http_executor.py"
click node_checks "https://github.com/x03tanuj/sentinel-api/tree/main/backend/app/engine/checks"
click node_differential "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/differential.py"
click node_evidence "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/evidence.py"
click node_report "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/report.py"
click node_airoutes "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/routes/ai.py"
click node_analyst "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/analyst.py"
click node_payload "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/payload.py"
click node_providers "https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/providers.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_webapp,node_scanpages,node_livepage,node_triage,node_history,node_client,node_operator toneBlue
class node_app,node_scanroutes,node_manager,node_store toneAmber
class node_parser,node_surface,node_runner,node_identity,node_executor,node_checks,node_contract,node_target toneMint
class node_differential,node_evidence,node_report toneRose
class node_airoutes,node_analyst,node_payload,node_providers,node_llm toneIndigo
```

## Components

### Scan Interface

- [Web Application](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Scan Pages](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/NewScanPage.tsx): `frontend/src/pages/NewScanPage.tsx`
- [Live Scan View](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/LiveScanPage.tsx): `frontend/src/pages/LiveScanPage.tsx`
- [Triage Workspace](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/TriageWorkspacePage.tsx): `frontend/src/pages/TriageWorkspacePage.tsx`
- [Scan History](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/pages/HistoryPage.tsx): `frontend/src/pages/HistoryPage.tsx`
- [API Client](https://github.com/x03tanuj/sentinel-api/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API Orchestration

- [FastAPI Application](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/main.py): `backend/app/main.py`
- [Scan Routes](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/routes/scans.py): `backend/app/routes/scans.py`
- [Scan Manager](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/scan_manager.py): `backend/app/scan_manager.py`
- [Scan Store](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/store.py): `backend/app/store.py`

### Security Engine

- [OpenAPI Parser](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/parser/openapi_loader.py): `backend/app/parser/openapi_loader.py`
- [Surface Mapper](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/parser/surface_mapper.py): `backend/app/parser/surface_mapper.py`
- [Scan Runner](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/runner.py): `backend/app/engine/runner.py`
- [Identity Manager](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/identity.py): `backend/app/engine/identity.py`
- [HTTP Executor](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/http_executor.py): `backend/app/engine/http_executor.py`
- [Security Checks](https://github.com/x03tanuj/sentinel-api/tree/main/backend/app/engine/checks): `backend/app/engine/checks`

### Findings Analysis

- [Differential Analysis](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/differential.py): `backend/app/engine/differential.py`
- [Evidence & Risk](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/engine/evidence.py): `backend/app/engine/evidence.py`
- [Report Generation](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/report.py): `backend/app/report.py`

### Optional AI

- [AI Routes](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/routes/ai.py): `backend/app/routes/ai.py`
- [AI Analyst](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/analyst.py): `backend/app/ai/analyst.py`
- [Evidence Payload](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/payload.py): `backend/app/ai/payload.py`
- [Model Providers](https://github.com/x03tanuj/sentinel-api/blob/main/backend/app/ai/providers.py): `backend/app/ai/providers.py`

### Other components

- **Scanner User**
- **OpenAPI Contract**
- **Authorized Target API**
- **External LLM**

## Connections

- Scanner User → Web Application: uses
- Web Application → Scan Pages: routes to
- Web Application → Live Scan View: routes to
- Web Application → Triage Workspace: routes to
- Web Application → Scan History: routes to
- Scan Pages → API Client: submits scan
- Live Scan View → API Client: streams events
- Triage Workspace → API Client: fetches results
- Scan History → API Client: fetches history
- API Client → Scan Routes: calls API
- FastAPI Application → Scan Routes: includes router
- Scan Routes → Scan Manager: delegates lifecycle
- Scan Manager → Scan Store: persists scan state
- Scan Manager → Scan Runner: runs scan
- OpenAPI Contract → OpenAPI Parser: provides specification
- OpenAPI Parser → Surface Mapper: extracts endpoints
- Surface Mapper → Scan Runner: prioritizes surface
- Scan Runner → Identity Manager: manages personas
- Scan Runner → HTTP Executor: dispatches probes
- HTTP Executor → Authorized Target API: sends probes
- Authorized Target API → HTTP Executor: returns responses
- Scan Runner → Differential Analysis: analyzes responses
- Differential Analysis → Security Checks: evaluates differences
- Security Checks → Evidence & Risk: produces findings
- Evidence & Risk → Report Generation: informs risk report
- Evidence & Risk → AI Routes: supplies sanitized findings
- FastAPI Application → AI Routes: includes router
- AI Routes → AI Analyst: requests analysis
- AI Analyst → Evidence Payload: prepares evidence
- AI Analyst → Model Providers: selects provider
- Model Providers → External LLM: sends analysis
- AI Routes → API Client: serves AI results