# averysmallsoap/restackapi architecture

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

- Interactive diagram: https://gitdiagram.com/averysmallsoap/restackapi
- Repository: https://github.com/averysmallsoap/restackapi

## Overview

Restack is a backend API that coordinates web-application security scans and exposes findings, reports, and analytics to the web application. The main workflow begins with an API request, runs scanner integrations, normalizes and analyzes results, then persists and serves scan data. Separate capabilities include scheduled scans, report export, and analytics. The excerpts show key orchestration and persistence links; some route and integration details are unsampled, so those relationships are omitted rather than inferred.

Main entry points: [`services/managers/ScannerManager.py`](https://github.com/averysmallsoap/restackapi/blob/master/services/managers/ScannerManager.py) (Scanner manager), [`modules/db/database.py`](https://github.com/averysmallsoap/restackapi/blob/master/modules/db/database.py) (Database access), [`main.py`](https://github.com/averysmallsoap/restackapi/blob/master/main.py) (REST API), [`modules/utils/background_runnable.py`](https://github.com/averysmallsoap/restackapi/blob/master/modules/utils/background_runnable.py) (Scan runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and orchestration"]
  node_api["REST API<br/>[main.py]"]
  node_runner["Scan runner"]
  node_tracker["Scan tracker<br/>[ScanTracker.py]"]
end

subgraph group_scanning["Scanning"]
  node_scanner_manager["Scanner manager<br/>[ScannerManager.py]"]
  node_scanner_adapters["Scanner adapters<br/>[IScannerAdapter.py]"]
  node_whatweb["WhatWeb discovery<br/>[WhatWebScanner.py]"]
  node_wapiti["Wapiti scanner<br/>[WapitiScanner.py]"]
  node_zap["ZAP scanner<br/>[ZapScanner.py]"]
  node_nuclei["Nuclei scanner<br/>[nuclei.py]"]
  node_discovery_tools["Other discovery tools"]
end

subgraph group_results["Results and storage"]
  node_analysis["Vulnerability analysis"]
  node_database["Database access<br/>[database.py]"]
  node_models["Scan data models"]
  node_report_export["Report generation"]
end

subgraph group_insights["Analytics"]
  node_analytics_api["Analytics calculations"]
  node_ai_summary["AI summaries<br/>[ai_recosum.py]"]
end

subgraph group_scheduling["Scheduling"]
  node_scheduler["Schedule manager<br/>[ScheduleManager.py]"]
  node_scheduler_service["Scheduler service"]
  node_schedule_store[("Schedule records")]
end

node_webapp(("Web application"))

node_webapp -->|"requests scans"| node_api
node_api -->|"starts scans"| node_scanner_manager
node_api -->|"exports reports"| node_report_export
node_api -->|"serves analytics"| node_analytics_api
node_scanner_manager -->|"starts discovery"| node_whatweb
node_scanner_manager -->|"dispatches scans"| node_zap
node_scanner_manager -->|"dispatches scans"| node_wapiti
node_scanner_manager -->|"dispatches scans"| node_nuclei
node_scanner_manager -->|"implements contract"| node_scanner_adapters
node_runner -->|"runs scans"| node_scanner_manager
node_runner -->|"analyzes findings"| node_analysis
node_runner -->|"saves results"| node_database
node_runner -->|"generates summaries"| node_ai_summary
node_analysis -->|"loads configuration"| node_database
node_database -->|"uses models"| node_models
node_report_export -->|"reads reports"| node_database
node_analytics_api -->|"queries scan data"| node_database
node_scheduler_service -->|"runs scheduling"| node_scheduler
node_scheduler -->|"reads schedules"| node_schedule_store
node_scheduler -.->|"starts scheduled scans"| node_runner
node_api -->|"tracks scan state"| node_tracker
node_tracker -->|"persists scan state"| node_database

click node_api "https://github.com/averysmallsoap/restackapi/blob/master/main.py"
click node_runner "https://github.com/averysmallsoap/restackapi/blob/master/modules/utils/background_runnable.py"
click node_tracker "https://github.com/averysmallsoap/restackapi/blob/master/services/ScanTracker.py"
click node_scanner_manager "https://github.com/averysmallsoap/restackapi/blob/master/services/managers/ScannerManager.py"
click node_scanner_adapters "https://github.com/averysmallsoap/restackapi/blob/master/modules/interfaces/IScannerAdapter.py"
click node_whatweb "https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/discovery/WhatWebScanner.py"
click node_wapiti "https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/WapitiScanner.py"
click node_zap "https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/ZapScanner.py"
click node_nuclei "https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/vulnerabilities/nuclei.py"
click node_discovery_tools "https://github.com/averysmallsoap/restackapi/tree/master/modules/scanners/discovery"
click node_analysis "https://github.com/averysmallsoap/restackapi/blob/master/modules/analytics/vulnerability_analysis.py"
click node_database "https://github.com/averysmallsoap/restackapi/blob/master/modules/db/database.py"
click node_models "https://github.com/averysmallsoap/restackapi/blob/master/modules/db/table_collection.py"
click node_report_export "https://github.com/averysmallsoap/restackapi/blob/master/services/FileReportGenerator.py"
click node_analytics_api "https://github.com/averysmallsoap/restackapi/tree/master/modules/analytics"
click node_ai_summary "https://github.com/averysmallsoap/restackapi/blob/master/modules/analytics/ai_recosum.py"
click node_scheduler "https://github.com/averysmallsoap/restackapi/blob/master/services/managers/ScheduleManager.py"
click node_scheduler_service "https://github.com/averysmallsoap/restackapi/blob/master/scheduler_service.py"
click node_schedule_store "https://github.com/averysmallsoap/restackapi/blob/master/modules/db/table_collection.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_api,node_runner,node_tracker toneBlue
class node_scanner_manager,node_scanner_adapters,node_whatweb,node_wapiti,node_zap,node_nuclei,node_discovery_tools toneAmber
class node_analysis,node_database,node_models,node_report_export toneMint
class node_analytics_api,node_ai_summary toneRose
class node_scheduler,node_scheduler_service,node_schedule_store,node_webapp toneIndigo
```

## Components

### API and orchestration

- [REST API](https://github.com/averysmallsoap/restackapi/blob/master/main.py): `main.py`
- [Scan runner](https://github.com/averysmallsoap/restackapi/blob/master/modules/utils/background_runnable.py): `modules/utils/background_runnable.py`
- [Scan tracker](https://github.com/averysmallsoap/restackapi/blob/master/services/ScanTracker.py): `services/ScanTracker.py`

### Scanning

- [Scanner manager](https://github.com/averysmallsoap/restackapi/blob/master/services/managers/ScannerManager.py): `services/managers/ScannerManager.py`
- [Scanner adapters](https://github.com/averysmallsoap/restackapi/blob/master/modules/interfaces/IScannerAdapter.py): `modules/interfaces/IScannerAdapter.py`
- [WhatWeb discovery](https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/discovery/WhatWebScanner.py): `modules/scanners/discovery/WhatWebScanner.py`
- [Wapiti scanner](https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/WapitiScanner.py): `modules/scanners/WapitiScanner.py`
- [ZAP scanner](https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/ZapScanner.py): `modules/scanners/ZapScanner.py`
- [Nuclei scanner](https://github.com/averysmallsoap/restackapi/blob/master/modules/scanners/vulnerabilities/nuclei.py): `modules/scanners/vulnerabilities/nuclei.py`
- [Other discovery tools](https://github.com/averysmallsoap/restackapi/tree/master/modules/scanners/discovery): `modules/scanners/discovery`

### Results and storage

- [Vulnerability analysis](https://github.com/averysmallsoap/restackapi/blob/master/modules/analytics/vulnerability_analysis.py): `modules/analytics/vulnerability_analysis.py`
- [Database access](https://github.com/averysmallsoap/restackapi/blob/master/modules/db/database.py): `modules/db/database.py`
- [Scan data models](https://github.com/averysmallsoap/restackapi/blob/master/modules/db/table_collection.py): `modules/db/table_collection.py`
- [Report generation](https://github.com/averysmallsoap/restackapi/blob/master/services/FileReportGenerator.py): `services/FileReportGenerator.py`

### Analytics

- [Analytics calculations](https://github.com/averysmallsoap/restackapi/tree/master/modules/analytics): `modules/analytics`
- [AI summaries](https://github.com/averysmallsoap/restackapi/blob/master/modules/analytics/ai_recosum.py): `modules/analytics/ai_recosum.py`

### Scheduling

- [Schedule manager](https://github.com/averysmallsoap/restackapi/blob/master/services/managers/ScheduleManager.py): `services/managers/ScheduleManager.py`
- [Scheduler service](https://github.com/averysmallsoap/restackapi/blob/master/scheduler_service.py): `scheduler_service.py`
- [Schedule records](https://github.com/averysmallsoap/restackapi/blob/master/modules/db/table_collection.py): `modules/db/table_collection.py`

### Other components

- **Web application**

## Connections

- Web application → REST API: requests scans (evidence: `README.md`)
- REST API → Scanner manager: starts scans (evidence: `main.py`)
- REST API → Report generation: exports reports (evidence: `main.py`)
- REST API → Analytics calculations: serves analytics (evidence: `main.py`)
- Scanner manager → WhatWeb discovery: starts discovery (evidence: `services/managers/ScannerManager.py`)
- Scanner manager → ZAP scanner: dispatches scans (evidence: `services/managers/ScannerManager.py`)
- Scanner manager → Wapiti scanner: dispatches scans (evidence: `services/managers/ScannerManager.py`)
- Scanner manager → Nuclei scanner: dispatches scans (evidence: `services/managers/ScannerManager.py`)
- Scanner manager → Scanner adapters: implements contract
- Scan runner → Scanner manager: runs scans (evidence: `modules/utils/background_runnable.py`)
- Scan runner → Vulnerability analysis: analyzes findings (evidence: `modules/utils/background_runnable.py`)
- Scan runner → Database access: saves results (evidence: `modules/utils/background_runnable.py`)
- Scan runner → AI summaries: generates summaries (evidence: `modules/utils/background_runnable.py`)
- Vulnerability analysis → Database access: loads configuration (evidence: `modules/analytics/vulnerability_analysis.py`)
- Database access → Scan data models: uses models (evidence: `modules/db/database.py`)
- Report generation → Database access: reads reports (evidence: `services/FileReportGenerator.py`)
- Analytics calculations → Database access: queries scan data (evidence: `modules/analytics/formal/correlation_regression.py`)
- Scheduler service → Schedule manager: runs scheduling (evidence: `scheduler_service.py`)
- Schedule manager → Schedule records: reads schedules (evidence: `services/managers/ScheduleManager.py`)
- Schedule manager → Scan runner: starts scheduled scans (evidence: `services/managers/ScheduleManager.py`)
- REST API → Scan tracker: tracks scan state (evidence: `main.py`)
- Scan tracker → Database access: persists scan state (evidence: `services/ScanTracker.py`)