# ciphernet01/sentinelstack architecture

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

- Interactive diagram: https://gitdiagram.com/ciphernet01/sentinelstack
- Repository: https://github.com/ciphernet01/sentinelstack

## Overview

SentinelStack is a multi-tenant security assessment and cyber-risk platform: users manage assessments, scan authorized targets, review findings and reports, and quantify organizational risk. Its repository also contains a separate Log-Whisperer service for log ingestion, anomaly detection, and crash analysis. The graph preserves those documented branches and the risk-engine stages; several connections are omitted where the sampled files do not show runtime wiring.

Main entry points: [`log-whisperer/backend/app/api/routes.py`](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/api/routes.py) (Log analysis API), [`src/routes/index.ts`](https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/index.ts) (API routes), [`src/services/risk/riskEngine.service.ts`](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/riskEngine.service.ts) (Risk calculation engine), [`src/routes/public-api.routes.ts`](https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/public-api.routes.ts) (Public assessment API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product["SentinelStack product"]
  node_dashboard["Dashboard UI<br/>[page.tsx]"]
  node_assessment_ui["Assessment views"]
  node_report_ui["Reports and analytics<br/>[page.tsx]"]
end

subgraph group_api["API and identity"]
  node_api_server["API server<br/>[server.ts]"]
  node_api_routes["API routes<br/>[index.ts]"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_org["Organization management<br/>[org.controller.ts]"]
  node_db[("Application database<br/>[db.ts]")]
  node_public_api["Public assessment API"]
end

subgraph group_scanning["Assessment scanning"]
  node_queue["Scan queue"]
  node_worker["Scan worker<br/>[worker.service.ts]"]
  node_scanner_engine["Scanner engine<br/>[engine.py]"]
  node_scanner_tools["Security scanner tools"]
  node_findings["Findings and reports"]
end

subgraph group_risk["Risk analysis"]
  node_risk_controller["Cyber-risk API"]
  node_risk_engine["Risk calculation engine"]
  node_evidence_signals["Evidence signals"]
  node_severity["Severity modeling"]
  node_driver_attribution["Risk driver attribution"]
end

subgraph group_logs["Log Whisperer"]
  node_log_api["Log analysis API<br/>[routes.py]"]
  node_ingest["Log ingestion<br/>[service.py]"]
  node_schemas["Log data schemas<br/>[schemas.py]"]
  node_anomaly["Anomaly detection<br/>[anomaly.py]"]
  node_enhancement["Enhanced analysis<br/>[integration.py]"]
  node_crash_reports["Crash report generation<br/>[generator.py]"]
end

node_user(("Platform user"))
node_log_client(("Log operator"))

node_user -.->|"uses"| node_dashboard
node_dashboard -.->|"opens assessments"| node_assessment_ui
node_assessment_ui -.->|"requests data"| node_api_server
node_api_server -->|"mounts routes"| node_api_routes
node_api_routes -.->|"uses authentication"| node_auth
node_api_routes -->|"routes organization requests"| node_org
node_auth -->|"loads user membership"| node_db
node_api_routes -.->|"registers API routes"| node_public_api
node_public_api -->|"reads assessments and reports"| node_db
node_public_api -->|"queues scans"| node_queue
node_worker -->|"accesses application data"| node_db
node_worker -.->|"processes scan work"| node_queue
node_scanner_engine -.->|"executes tools"| node_scanner_tools
node_risk_controller -.->|"calculates risk"| node_risk_engine
node_risk_engine -->|"aggregates signals"| node_evidence_signals
node_risk_engine -->|"composes severity"| node_severity
node_risk_engine -->|"attributes drivers"| node_driver_attribution
node_log_client -.->|"uploads and queries logs"| node_log_api
node_log_api -->|"ingests log files"| node_ingest
node_log_api -->|"queries anomalies"| node_anomaly
node_log_api -->|"queries crash reports"| node_crash_reports
node_log_api -->|"requests causal analysis"| node_enhancement
node_log_api -->|"uses request and response models"| node_schemas
node_enhancement -->|"uses shared schemas"| node_schemas

click node_dashboard "https://github.com/ciphernet01/sentinelstack/blob/main/src/app/dashboard/page.tsx"
click node_assessment_ui "https://github.com/ciphernet01/sentinelstack/blob/main/src/components/assessments/AssessmentListClient.tsx"
click node_report_ui "https://github.com/ciphernet01/sentinelstack/blob/main/src/app/dashboard/reports/page.tsx"
click node_api_server "https://github.com/ciphernet01/sentinelstack/blob/main/src/server.ts"
click node_api_routes "https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/index.ts"
click node_auth "https://github.com/ciphernet01/sentinelstack/blob/main/src/middleware/auth.ts"
click node_org "https://github.com/ciphernet01/sentinelstack/blob/main/src/controllers/org.controller.ts"
click node_db "https://github.com/ciphernet01/sentinelstack/blob/main/src/config/db.ts"
click node_public_api "https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/public-api.routes.ts"
click node_queue "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/scanQueue.service.ts"
click node_worker "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/worker.service.ts"
click node_scanner_engine "https://github.com/ciphernet01/sentinelstack/blob/main/scanners/engine/engine.py"
click node_scanner_tools "https://github.com/ciphernet01/sentinelstack/tree/main/scanners/tools"
click node_findings "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/findings.service.ts"
click node_risk_controller "https://github.com/ciphernet01/sentinelstack/blob/main/src/controllers/cyber-risk.controller.ts"
click node_risk_engine "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/riskEngine.service.ts"
click node_evidence_signals "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/evidenceSignals.service.ts"
click node_severity "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/severity.service.ts"
click node_driver_attribution "https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/driverAttribution.service.ts"
click node_log_api "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/api/routes.py"
click node_ingest "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/ingest/service.py"
click node_schemas "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/core/schemas.py"
click node_anomaly "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/detect/anomaly.py"
click node_enhancement "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/enhance/integration.py"
click node_crash_reports "https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/report/generator.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_dashboard,node_assessment_ui,node_report_ui,node_user toneBlue
class node_api_server,node_api_routes,node_auth,node_org,node_db,node_public_api toneAmber
class node_queue,node_worker,node_scanner_engine,node_scanner_tools,node_findings toneMint
class node_risk_controller,node_risk_engine,node_evidence_signals,node_severity,node_driver_attribution toneRose
class node_log_api,node_ingest,node_schemas,node_anomaly,node_enhancement,node_crash_reports,node_log_client toneIndigo
```

## Components

### SentinelStack product

- [Dashboard UI](https://github.com/ciphernet01/sentinelstack/blob/main/src/app/dashboard/page.tsx): `src/app/dashboard/page.tsx`
- [Assessment views](https://github.com/ciphernet01/sentinelstack/blob/main/src/components/assessments/AssessmentListClient.tsx): `src/components/assessments/AssessmentListClient.tsx`
- [Reports and analytics](https://github.com/ciphernet01/sentinelstack/blob/main/src/app/dashboard/reports/page.tsx): `src/app/dashboard/reports/page.tsx`

### API and identity

- [API server](https://github.com/ciphernet01/sentinelstack/blob/main/src/server.ts): `src/server.ts`
- [API routes](https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/index.ts): `src/routes/index.ts`
- [Authentication](https://github.com/ciphernet01/sentinelstack/blob/main/src/middleware/auth.ts): `src/middleware/auth.ts`
- [Organization management](https://github.com/ciphernet01/sentinelstack/blob/main/src/controllers/org.controller.ts): `src/controllers/org.controller.ts`
- [Application database](https://github.com/ciphernet01/sentinelstack/blob/main/src/config/db.ts): `src/config/db.ts`
- [Public assessment API](https://github.com/ciphernet01/sentinelstack/blob/main/src/routes/public-api.routes.ts): `src/routes/public-api.routes.ts`

### Assessment scanning

- [Scan queue](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/scanQueue.service.ts): `src/services/scanQueue.service.ts`
- [Scan worker](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/worker.service.ts): `src/services/worker.service.ts`
- [Scanner engine](https://github.com/ciphernet01/sentinelstack/blob/main/scanners/engine/engine.py): `scanners/engine/engine.py`
- [Security scanner tools](https://github.com/ciphernet01/sentinelstack/tree/main/scanners/tools): `scanners/tools`
- [Findings and reports](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/findings.service.ts): `src/services/findings.service.ts`

### Risk analysis

- [Cyber-risk API](https://github.com/ciphernet01/sentinelstack/blob/main/src/controllers/cyber-risk.controller.ts): `src/controllers/cyber-risk.controller.ts`
- [Risk calculation engine](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/riskEngine.service.ts): `src/services/risk/riskEngine.service.ts`
- [Evidence signals](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/evidenceSignals.service.ts): `src/services/risk/evidenceSignals.service.ts`
- [Severity modeling](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/severity.service.ts): `src/services/risk/severity.service.ts`
- [Risk driver attribution](https://github.com/ciphernet01/sentinelstack/blob/main/src/services/risk/driverAttribution.service.ts): `src/services/risk/driverAttribution.service.ts`

### Log Whisperer

- [Log analysis API](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/api/routes.py): `log-whisperer/backend/app/api/routes.py`
- [Log ingestion](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/ingest/service.py): `log-whisperer/backend/app/ingest/service.py`
- [Log data schemas](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/core/schemas.py): `log-whisperer/backend/app/core/schemas.py`
- [Anomaly detection](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/detect/anomaly.py): `log-whisperer/backend/app/detect/anomaly.py`
- [Enhanced analysis](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/enhance/integration.py): `log-whisperer/backend/app/enhance/integration.py`
- [Crash report generation](https://github.com/ciphernet01/sentinelstack/blob/main/log-whisperer/backend/app/report/generator.py): `log-whisperer/backend/app/report/generator.py`

### Other components

- **Platform user**
- **Log operator**

## Connections

- Platform user → Dashboard UI: uses
- Dashboard UI → Assessment views: opens assessments
- Assessment views → API server: requests data
- API server → API routes: mounts routes (evidence: `src/server.ts`)
- API routes → Authentication: uses authentication
- API routes → Organization management: routes organization requests
- Authentication → Application database: loads user membership (evidence: `src/middleware/auth.ts`)
- API routes → Public assessment API: registers API routes
- Public assessment API → Application database: reads assessments and reports (evidence: `src/routes/public-api.routes.ts`)
- Public assessment API → Scan queue: queues scans (evidence: `src/routes/public-api.routes.ts`)
- Scan worker → Application database: accesses application data (evidence: `src/services/worker.service.ts`)
- Scan worker → Scan queue: processes scan work
- Scanner engine → Security scanner tools: executes tools
- Cyber-risk API → Risk calculation engine: calculates risk
- Risk calculation engine → Evidence signals: aggregates signals (evidence: `src/services/risk/riskEngine.service.ts`)
- Risk calculation engine → Severity modeling: composes severity (evidence: `src/services/risk/riskEngine.service.ts`)
- Risk calculation engine → Risk driver attribution: attributes drivers (evidence: `src/services/risk/riskEngine.service.ts`)
- Log operator → Log analysis API: uploads and queries logs
- Log analysis API → Log ingestion: ingests log files (evidence: `log-whisperer/backend/app/api/routes.py`)
- Log analysis API → Anomaly detection: queries anomalies (evidence: `log-whisperer/backend/app/api/routes.py`)
- Log analysis API → Crash report generation: queries crash reports (evidence: `log-whisperer/backend/app/api/routes.py`)
- Log analysis API → Enhanced analysis: requests causal analysis (evidence: `log-whisperer/backend/app/api/routes.py`)
- Log analysis API → Log data schemas: uses request and response models (evidence: `log-whisperer/backend/app/api/routes.py`)
- Enhanced analysis → Log data schemas: uses shared schemas (evidence: `log-whisperer/backend/app/enhance/integration.py`)
