# vatshal27/backend architecture

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

- Interactive diagram: https://gitdiagram.com/vatshal27/backend
- Repository: https://github.com/vatshal27/backend

## Overview

SentinelAI is a security-analysis backend. Its main workflow accepts a project scan, runs static checks, enriches findings with optional LLM analysis, and can validate findings in a Docker sandbox before returning results. The graph also shows the separate runtime-discovery/check and sandbox-control API capabilities. Relationships are limited to the shown excerpts, SOURCE INDEX references, and README; unsampled implementation details are not inferred.

Main entry points: [`docker/sandbox.js`](https://github.com/vatshal27/backend/blob/main/docker/sandbox.js) (Sandbox orchestrator), [`server.js`](https://github.com/vatshal27/backend/blob/main/server.js) (Express API), [`scanner/scanner.js`](https://github.com/vatshal27/backend/blob/main/scanner/scanner.js) (Scan orchestrator), [`llm/analyzer.js`](https://github.com/vatshal27/backend/blob/main/llm/analyzer.js) (Finding analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API orchestration"]
  node_server["Express API<br/>[server.js]"]
  node_runtime["Runtime checks<br/>[runtime.js]"]
end

subgraph group_static["Static analysis"]
  node_scanner["Scan orchestrator<br/>[scanner.js]"]
  node_eslint["ESLint checks<br/>[eslint.js]"]
  node_bandit["Bandit checks<br/>[bandit.js]"]
  node_semgrep["Semgrep checks<br/>[semgrep.js]"]
  node_file_context["File context<br/>[context.js]"]
  node_normalization["Finding normalization<br/>[normalize.js]"]
  node_sanitizer["Output sanitization<br/>[sanitizer.js]"]
  node_rules["Security rules"]
  node_docker_scanner["Docker static scan<br/>[docker-scanner.js]"]
end

subgraph group_ai["AI analysis"]
  node_analyzer["Finding analysis<br/>[analyzer.js]"]
  node_prompt["Prompt builder<br/>[prompt-builder.js]"]
  node_ollama_client["Ollama client<br/>[ollama.js]"]
  node_parser["Finding parser<br/>[parser.js]"]
  node_filters["Finding filters<br/>[filters.js]"]
end

subgraph group_sandbox["Docker validation"]
  node_sandbox["Sandbox orchestrator<br/>[sandbox.js]"]
  node_docker_client["Docker client<br/>[client.js]"]
  node_docker_config["Sandbox config<br/>[config.js]"]
  node_planner["Attack planner<br/>[planner.js]"]
  node_target["Synthetic target<br/>[target.js]"]
  node_runner["Attack runner<br/>[runner.js]"]
  node_evidence["Evidence capture<br/>[evidence.js]"]
  node_validator["Finding validators<br/>[validator.js]"]
  node_validators["Tool validators"]
  node_report["Sandbox report<br/>[report.js]"]
end

node_client_actor(("API client"))
node_ollama_service["Ollama service"]
node_docker_service["Docker daemon"]

node_client_actor -->|"sends requests"| node_server
node_server -->|"runs scans"| node_scanner
node_scanner -->|"dispatches checks"| node_eslint
node_scanner -->|"dispatches checks"| node_bandit
node_scanner -->|"dispatches checks"| node_semgrep
node_scanner -->|"normalizes findings"| node_normalization
node_normalization -->|"gets context"| node_file_context
node_server -->|"uses scanner"| node_docker_scanner
node_server -.->|"requests analysis"| node_analyzer
node_analyzer -->|"builds prompts"| node_prompt
node_analyzer -->|"requests completions"| node_ollama_client
node_analyzer -->|"parses findings"| node_parser
node_analyzer -->|"filters findings"| node_filters
node_ollama_client -.->|"sends requests"| node_ollama_service
node_server -->|"checks runtime"| node_runtime
node_server -->|"runs sandbox"| node_sandbox
node_sandbox -->|"manages containers"| node_docker_client
node_sandbox -->|"uses settings"| node_docker_config
node_sandbox -->|"plans attacks"| node_planner
node_sandbox -->|"creates target"| node_target
node_sandbox -->|"runs attacks"| node_runner
node_sandbox -->|"uses evidence"| node_evidence
node_sandbox -->|"validates findings"| node_validator
node_sandbox -->|"builds report"| node_report
node_validator -.->|"uses tool validators"| node_validators
node_docker_client -->|"controls containers"| node_docker_service

click node_server "https://github.com/vatshal27/backend/blob/main/server.js"
click node_runtime "https://github.com/vatshal27/backend/blob/main/runtime.js"
click node_scanner "https://github.com/vatshal27/backend/blob/main/scanner/scanner.js"
click node_eslint "https://github.com/vatshal27/backend/blob/main/scanner/eslint.js"
click node_bandit "https://github.com/vatshal27/backend/blob/main/scanner/bandit.js"
click node_semgrep "https://github.com/vatshal27/backend/blob/main/scanner/semgrep.js"
click node_file_context "https://github.com/vatshal27/backend/blob/main/scanner/context.js"
click node_normalization "https://github.com/vatshal27/backend/blob/main/scanner/normalize.js"
click node_sanitizer "https://github.com/vatshal27/backend/blob/main/scanner/sanitizer.js"
click node_rules "https://github.com/vatshal27/backend/tree/main/scanner/rules"
click node_docker_scanner "https://github.com/vatshal27/backend/blob/main/docker-scanner.js"
click node_analyzer "https://github.com/vatshal27/backend/blob/main/llm/analyzer.js"
click node_prompt "https://github.com/vatshal27/backend/blob/main/llm/prompt-builder.js"
click node_ollama_client "https://github.com/vatshal27/backend/blob/main/llm/ollama.js"
click node_parser "https://github.com/vatshal27/backend/blob/main/llm/parser.js"
click node_filters "https://github.com/vatshal27/backend/blob/main/llm/filters.js"
click node_sandbox "https://github.com/vatshal27/backend/blob/main/docker/sandbox.js"
click node_docker_client "https://github.com/vatshal27/backend/blob/main/docker/client.js"
click node_docker_config "https://github.com/vatshal27/backend/blob/main/docker/config.js"
click node_planner "https://github.com/vatshal27/backend/blob/main/docker/planner.js"
click node_target "https://github.com/vatshal27/backend/blob/main/docker/target.js"
click node_runner "https://github.com/vatshal27/backend/blob/main/docker/runner.js"
click node_evidence "https://github.com/vatshal27/backend/blob/main/docker/evidence.js"
click node_validator "https://github.com/vatshal27/backend/blob/main/docker/validator.js"
click node_validators "https://github.com/vatshal27/backend/tree/main/docker/validators"
click node_report "https://github.com/vatshal27/backend/blob/main/docker/report.js"

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_server,node_runtime,node_client_actor toneBlue
class node_scanner,node_eslint,node_bandit,node_semgrep,node_file_context,node_normalization,node_sanitizer,node_rules,node_docker_scanner toneAmber
class node_analyzer,node_prompt,node_ollama_client,node_parser,node_filters toneMint
class node_sandbox,node_docker_client,node_docker_config,node_planner,node_target,node_runner,node_evidence,node_validator,node_validators,node_report toneRose
class node_ollama_service,node_docker_service toneIndigo
```

## Components

### API orchestration

- [Express API](https://github.com/vatshal27/backend/blob/main/server.js): `server.js`
- [Runtime checks](https://github.com/vatshal27/backend/blob/main/runtime.js): `runtime.js`

### Static analysis

- [Scan orchestrator](https://github.com/vatshal27/backend/blob/main/scanner/scanner.js): `scanner/scanner.js`
- [ESLint checks](https://github.com/vatshal27/backend/blob/main/scanner/eslint.js): `scanner/eslint.js`
- [Bandit checks](https://github.com/vatshal27/backend/blob/main/scanner/bandit.js): `scanner/bandit.js`
- [Semgrep checks](https://github.com/vatshal27/backend/blob/main/scanner/semgrep.js): `scanner/semgrep.js`
- [File context](https://github.com/vatshal27/backend/blob/main/scanner/context.js): `scanner/context.js`
- [Finding normalization](https://github.com/vatshal27/backend/blob/main/scanner/normalize.js): `scanner/normalize.js`
- [Output sanitization](https://github.com/vatshal27/backend/blob/main/scanner/sanitizer.js): `scanner/sanitizer.js`
- [Security rules](https://github.com/vatshal27/backend/tree/main/scanner/rules): `scanner/rules`
- [Docker static scan](https://github.com/vatshal27/backend/blob/main/docker-scanner.js): `docker-scanner.js`

### AI analysis

- [Finding analysis](https://github.com/vatshal27/backend/blob/main/llm/analyzer.js): `llm/analyzer.js`
- [Prompt builder](https://github.com/vatshal27/backend/blob/main/llm/prompt-builder.js): `llm/prompt-builder.js`
- [Ollama client](https://github.com/vatshal27/backend/blob/main/llm/ollama.js): `llm/ollama.js`
- [Finding parser](https://github.com/vatshal27/backend/blob/main/llm/parser.js): `llm/parser.js`
- [Finding filters](https://github.com/vatshal27/backend/blob/main/llm/filters.js): `llm/filters.js`

### Docker validation

- [Sandbox orchestrator](https://github.com/vatshal27/backend/blob/main/docker/sandbox.js): `docker/sandbox.js`
- [Docker client](https://github.com/vatshal27/backend/blob/main/docker/client.js): `docker/client.js`
- [Sandbox config](https://github.com/vatshal27/backend/blob/main/docker/config.js): `docker/config.js`
- [Attack planner](https://github.com/vatshal27/backend/blob/main/docker/planner.js): `docker/planner.js`
- [Synthetic target](https://github.com/vatshal27/backend/blob/main/docker/target.js): `docker/target.js`
- [Attack runner](https://github.com/vatshal27/backend/blob/main/docker/runner.js): `docker/runner.js`
- [Evidence capture](https://github.com/vatshal27/backend/blob/main/docker/evidence.js): `docker/evidence.js`
- [Finding validators](https://github.com/vatshal27/backend/blob/main/docker/validator.js): `docker/validator.js`
- [Tool validators](https://github.com/vatshal27/backend/tree/main/docker/validators): `docker/validators`
- [Sandbox report](https://github.com/vatshal27/backend/blob/main/docker/report.js): `docker/report.js`

### Other components

- **API client**
- **Ollama service**
- **Docker daemon**

## Connections

- API client → Express API: sends requests (evidence: `README.md`)
- Express API → Scan orchestrator: runs scans (evidence: `scanner/scanner.js`)
- Scan orchestrator → ESLint checks: dispatches checks (evidence: `scanner/scanner.js`)
- Scan orchestrator → Bandit checks: dispatches checks (evidence: `scanner/scanner.js`)
- Scan orchestrator → Semgrep checks: dispatches checks (evidence: `scanner/scanner.js`)
- Scan orchestrator → Finding normalization: normalizes findings (evidence: `scanner/scanner.js`)
- Finding normalization → File context: gets context (evidence: `scanner/normalize.js`)
- Express API → Docker static scan: uses scanner (evidence: `server.js`)
- Express API → Finding analysis: requests analysis (evidence: `server.js`)
- Finding analysis → Prompt builder: builds prompts (evidence: `llm/analyzer.js`)
- Finding analysis → Ollama client: requests completions (evidence: `llm/analyzer.js`)
- Finding analysis → Finding parser: parses findings (evidence: `llm/analyzer.js`)
- Finding analysis → Finding filters: filters findings (evidence: `llm/analyzer.js`)
- Ollama client → Ollama service: sends requests
- Express API → Runtime checks: checks runtime (evidence: `server.js`)
- Express API → Sandbox orchestrator: runs sandbox (evidence: `server.js`)
- Sandbox orchestrator → Docker client: manages containers (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Sandbox config: uses settings (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Attack planner: plans attacks (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Synthetic target: creates target (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Attack runner: runs attacks (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Evidence capture: uses evidence (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Finding validators: validates findings (evidence: `docker/sandbox.js`)
- Sandbox orchestrator → Sandbox report: builds report (evidence: `docker/sandbox.js`)
- Finding validators → Tool validators: uses tool validators
- Docker client → Docker daemon: controls containers (evidence: `docker/client.js`)
