# vansh-quant/sentinalapi architecture

> Architecture diagram of the GitHub repository vansh-quant/sentinalapi, 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/vansh-quant/sentinalapi
- Repository: https://github.com/vansh-quant/sentinalapi

## Overview

SentinelAPI lets users manage projects, upload OpenAPI specifications, and run isolated vulnerability scans against authorized sandbox targets. The workflow proceeds from authentication and spec ingestion through endpoint discovery, asynchronous scanning, persisted and sanitized findings, and dashboard/report or live-feed consumption. The README also documents attack-surface and timeline views. The graph reflects documented capabilities; sampled source confirms the API entry point, database, scan manager, and WebSocket broadcaster, while some route-to-service wiring is described only at a high level.

Main entry points: [`backend/app/core/database.py`](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/core/database.py) (Application Database), [`backend/app/main.py`](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/main.py) (FastAPI Application), [`backend/app/services/scan_manager.py`](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/scan_manager.py) (Async Scan Manager), [`frontend/app.js`](https://github.com/vansh-quant/sentinalapi/blob/main/frontend/app.js) (Dashboard & Reports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Interface"]
  node_frontend["Dashboard &amp; Reports<br/>[app.js]"]
end

subgraph group_api["Backend API"]
  node_app["FastAPI Application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_projects["Project Management<br/>[projects.py]"]
  node_scans["Scan API<br/>[scans.py]"]
  node_findings_api["Findings API<br/>[findings.py]"]
end

subgraph group_execution["Scan Execution"]
  node_openapi["OpenAPI Parser<br/>[openapi_parser.py]"]
  node_manager["Async Scan Manager<br/>[scan_manager.py]"]
  node_scanner_client["Scanner Client<br/>[scanner_client.py]"]
  node_scanner["Scanner Engine<br/>[service.py]"]
  node_sandbox["Vulnerable Sandbox<br/>[app.py]"]
end

subgraph group_data["Persistence"]
  node_storage["Upload Storage<br/>[storage.py]"]
  node_database[("Application Database<br/>[database.py]")]
end

subgraph group_insights["Results &amp; Feeds"]
  node_sanitizer["Result Sanitizer"]
  node_dashboard["Dashboard &amp; Reports"]
  node_events["Scan Timeline<br/>[scan_event.py]"]
  node_websocket["Live Feed Manager<br/>[ws_manager.py]"]
end

node_user(("Security Engineer"))
node_external_scanner["Optional Scanner Service"]

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_app
node_frontend -->|"subscribes"| node_websocket
node_app -->|"routes auth"| node_auth
node_app -->|"routes projects"| node_projects
node_app -->|"routes scans"| node_scans
node_app -->|"routes findings"| node_findings_api
node_auth -->|"reads/writes users"| node_database
node_projects -->|"persists projects"| node_database
node_scans -->|"stores uploads"| node_storage
node_scans -->|"parses spec"| node_openapi
node_scans -->|"starts/cancels"| node_manager
node_openapi -->|"stores endpoints"| node_database
node_manager -->|"reads/writes scan data"| node_database
node_manager -->|"executes scan"| node_scanner_client
node_scanner_client -->|"uses fallback"| node_scanner
node_scanner_client -.->|"dispatches"| node_external_scanner
node_scanner -->|"sends test requests"| node_sandbox
node_manager -->|"sanitizes results"| node_sanitizer
node_manager -->|"broadcasts updates"| node_websocket
node_websocket -->|"streams events"| node_frontend
node_findings_api -->|"reads/writes findings"| node_database
node_findings_api -->|"sanitizes evidence"| node_sanitizer
node_dashboard -->|"reads scan data"| node_database
node_events -->|"persists timeline"| node_database
node_frontend -->|"requests metrics/reports"| node_dashboard

click node_frontend "https://github.com/vansh-quant/sentinalapi/blob/main/frontend/app.js"
click node_app "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/main.py"
click node_auth "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/auth.py"
click node_projects "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/projects.py"
click node_scans "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/scans.py"
click node_findings_api "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/findings.py"
click node_openapi "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/openapi_parser.py"
click node_manager "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/scan_manager.py"
click node_scanner_client "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/scanner_client.py"
click node_scanner "https://github.com/vansh-quant/sentinalapi/blob/main/scanner/service.py"
click node_sandbox "https://github.com/vansh-quant/sentinalapi/blob/main/sandbox/app.py"
click node_storage "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/storage.py"
click node_database "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/core/database.py"
click node_sanitizer "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/security_sanitizer.py"
click node_dashboard "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/dashboard_service.py"
click node_events "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/models/scan_event.py"
click node_websocket "https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/ws_manager.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_frontend toneBlue
class node_app,node_auth,node_projects,node_scans,node_findings_api toneAmber
class node_openapi,node_manager,node_scanner_client,node_scanner,node_sandbox toneMint
class node_storage,node_database toneRose
class node_sanitizer,node_dashboard,node_events,node_websocket,node_user,node_external_scanner toneIndigo
```

## Components

### User Interface

- [Dashboard & Reports](https://github.com/vansh-quant/sentinalapi/blob/main/frontend/app.js): `frontend/app.js`

### Backend API

- [FastAPI Application](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Project Management](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/projects.py): `backend/app/api/projects.py`
- [Scan API](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/scans.py): `backend/app/api/scans.py`
- [Findings API](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/api/findings.py): `backend/app/api/findings.py`

### Scan Execution

- [OpenAPI Parser](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/openapi_parser.py): `backend/app/services/openapi_parser.py`
- [Async Scan Manager](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/scan_manager.py): `backend/app/services/scan_manager.py`
- [Scanner Client](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/scanner_client.py): `backend/app/services/scanner_client.py`
- [Scanner Engine](https://github.com/vansh-quant/sentinalapi/blob/main/scanner/service.py): `scanner/service.py`
- [Vulnerable Sandbox](https://github.com/vansh-quant/sentinalapi/blob/main/sandbox/app.py): `sandbox/app.py`

### Persistence

- [Upload Storage](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`
- [Application Database](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Results & Feeds

- [Result Sanitizer](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/security_sanitizer.py): `backend/app/services/security_sanitizer.py`
- [Dashboard & Reports](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/dashboard_service.py): `backend/app/services/dashboard_service.py`
- [Scan Timeline](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/models/scan_event.py): `backend/app/models/scan_event.py`
- [Live Feed Manager](https://github.com/vansh-quant/sentinalapi/blob/main/backend/app/services/ws_manager.py): `backend/app/services/ws_manager.py`

### Other components

- **Security Engineer**
- **Optional Scanner Service**

## Connections

- Security Engineer → Dashboard & Reports: uses
- Dashboard & Reports → FastAPI Application: calls API
- Dashboard & Reports → Live Feed Manager: subscribes
- FastAPI Application → Authentication: routes auth
- FastAPI Application → Project Management: routes projects
- FastAPI Application → Scan API: routes scans
- FastAPI Application → Findings API: routes findings
- Authentication → Application Database: reads/writes users
- Project Management → Application Database: persists projects
- Scan API → Upload Storage: stores uploads
- Scan API → OpenAPI Parser: parses spec
- Scan API → Async Scan Manager: starts/cancels
- OpenAPI Parser → Application Database: stores endpoints
- Async Scan Manager → Application Database: reads/writes scan data
- Async Scan Manager → Scanner Client: executes scan
- Scanner Client → Scanner Engine: uses fallback
- Scanner Client → Optional Scanner Service: dispatches
- Scanner Engine → Vulnerable Sandbox: sends test requests
- Async Scan Manager → Result Sanitizer: sanitizes results
- Async Scan Manager → Live Feed Manager: broadcasts updates
- Live Feed Manager → Dashboard & Reports: streams events
- Findings API → Application Database: reads/writes findings
- Findings API → Result Sanitizer: sanitizes evidence
- Dashboard & Reports → Application Database: reads scan data
- Scan Timeline → Application Database: persists timeline
- Dashboard & Reports → Dashboard & Reports: requests metrics/reports