# ivancyao/capstone-securescan architecture

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

- Interactive diagram: https://gitdiagram.com/ivancyao/capstone-securescan
- Repository: https://github.com/ivancyao/capstone-securescan

## Overview

SecureScan is a web vulnerability assessment and management platform. Users register projects and web assets, launch controlled evaluations, follow progress, review CVSS/OWASP-prioritized findings, track remediation, compare runs, and generate PDF reports. The React interface calls a FastAPI backend; the backend persists accounts and assessment data in PostgreSQL and orchestrates Nmap, with OWASP ZAP and VirusTotal documented as optional integrations. The graph covers the documented quick-analysis, metrics, administration, and reporting branches as well. Some subsystem paths and links rely on README or source-index references; unsampled internals are not inferred beyond those references.

Main entry points: [`backend/app/database.py`](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/database.py) (Database access), [`frontend/src/App.jsx`](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/App.jsx) (React application), [`backend/app/main.py`](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/main.py) (FastAPI entry), [`backend/app/scan_service.py`](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/scan_service.py) (Evaluation orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_react_app["React application<br/>[App.jsx]"]
  node_data_context["Data and actions<br/>[DataContext.jsx]"]
  node_api_client["API client<br/>[http.js]"]
  node_project_ui["Projects and assets<br/>[Proyectos.jsx]"]
  node_evaluation_ui["Evaluations and findings<br/>[Evaluaciones.jsx]"]
  node_analysis_ui["Quick analysis<br/>[Analisis.jsx]"]
  node_reports_ui["Reports and comparison<br/>[Reportes.jsx]"]
  node_admin_ui["Administration<br/>[Admin.jsx]"]
end

subgraph group_api["API and access"]
  node_api_entry["FastAPI entry<br/>[main.py]"]
  node_auth_routes["Authentication<br/>[auth.py]"]
  node_project_routes["Projects and evaluations API<br/>[proyectos.py]"]
  node_analysis_routes["Analysis API<br/>[analisis.py]"]
  node_metrics_routes["Metrics API<br/>[metricas.py]"]
  node_admin_routes["Users and configuration API<br/>[usuarios.py]"]
end

subgraph group_assessment["Assessment domain"]
  node_evaluation_service["Evaluation orchestration<br/>[scan_service.py]"]
  node_analysis_service["Quick analysis service"]
  node_risk["Risk classification<br/>[risk.py]"]
end

subgraph group_integrations["Scanning integrations"]
  node_scanner["Port and service scan<br/>[scanner.py]"]
  node_zap_client["OWASP ZAP client<br/>[zap_client.py]"]
  node_virustotal{{"VirusTotal"}}
end

subgraph group_data["Persistence and output"]
  node_postgres[("PostgreSQL")]
  node_database_layer["Database access<br/>[database.py]"]
  node_models["Domain records<br/>[models.py]"]
  node_reports_api["Report generation API<br/>[reportes.py]"]
  node_pdf["PDF renderer<br/>[reportes_pdf.py]"]
end

node_user(("Organization user"))

node_user -->|"uses"| node_react_app
node_react_app -->|"routes to"| node_project_ui
node_react_app -->|"routes to"| node_evaluation_ui
node_react_app -->|"routes to"| node_analysis_ui
node_react_app -->|"routes to"| node_reports_ui
node_react_app -->|"routes to"| node_admin_ui
node_data_context -->|"calls"| node_api_client
node_api_client -->|"sends requests"| node_api_entry
node_api_entry -->|"registers"| node_auth_routes
node_api_entry -->|"registers"| node_project_routes
node_api_entry -->|"registers"| node_analysis_routes
node_api_entry -->|"registers"| node_metrics_routes
node_api_entry -->|"registers"| node_admin_routes
node_project_routes -->|"starts evaluation"| node_evaluation_service
node_analysis_routes -->|"invokes"| node_analysis_service
node_evaluation_service -->|"runs scan"| node_scanner
node_evaluation_service -->|"classifies findings"| node_risk
node_evaluation_service -->|"requests scan"| node_zap_client
node_evaluation_service -->|"persists results"| node_database_layer
node_analysis_service -->|"uses"| node_scanner
node_analysis_service -->|"accesses"| node_database_layer
node_analysis_service -.->|"checks reputation"| node_virustotal
node_scanner -->|"scans authorized target"| node_user
node_zap_client -->|"classifies findings"| node_risk
node_database_layer -->|"connects"| node_postgres
node_models -->|"defines mapped records"| node_database_layer
node_project_routes -->|"queries and updates"| node_database_layer
node_auth_routes -->|"accesses accounts"| node_database_layer
node_metrics_routes -->|"queries metrics"| node_database_layer
node_reports_api -->|"generates PDF"| node_pdf
node_reports_api -->|"stores report records"| node_database_layer

click node_react_app "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/App.jsx"
click node_data_context "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/context/DataContext.jsx"
click node_api_client "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/services/http.js"
click node_project_ui "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Proyectos.jsx"
click node_evaluation_ui "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Evaluaciones.jsx"
click node_analysis_ui "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Analisis.jsx"
click node_reports_ui "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Reportes.jsx"
click node_admin_ui "https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Admin.jsx"
click node_api_entry "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/main.py"
click node_auth_routes "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/auth.py"
click node_project_routes "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/proyectos.py"
click node_analysis_routes "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/analisis.py"
click node_metrics_routes "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/metricas.py"
click node_admin_routes "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/usuarios.py"
click node_evaluation_service "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/scan_service.py"
click node_analysis_service "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/analisis_service.py"
click node_risk "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/risk.py"
click node_scanner "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/scanner.py"
click node_zap_client "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/zap_client.py"
click node_database_layer "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/database.py"
click node_models "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/models.py"
click node_reports_api "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/reportes.py"
click node_pdf "https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/reportes_pdf.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_react_app,node_data_context,node_api_client,node_project_ui,node_evaluation_ui,node_analysis_ui,node_reports_ui,node_admin_ui,node_user toneBlue
class node_api_entry,node_auth_routes,node_project_routes,node_analysis_routes,node_metrics_routes,node_admin_routes toneAmber
class node_evaluation_service,node_analysis_service,node_risk toneMint
class node_scanner,node_zap_client,node_virustotal toneRose
class node_postgres,node_database_layer,node_models,node_reports_api,node_pdf toneIndigo
```

## Components

### User interface

- [React application](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Data and actions](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/context/DataContext.jsx): `frontend/src/context/DataContext.jsx`
- [API client](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/services/http.js): `frontend/src/services/http.js`
- [Projects and assets](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Proyectos.jsx): `frontend/src/pages/Proyectos.jsx`
- [Evaluations and findings](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Evaluaciones.jsx): `frontend/src/pages/Evaluaciones.jsx`
- [Quick analysis](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Analisis.jsx): `frontend/src/pages/Analisis.jsx`
- [Reports and comparison](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Reportes.jsx): `frontend/src/pages/Reportes.jsx`
- [Administration](https://github.com/ivancyao/capstone-securescan/blob/main/frontend/src/pages/Admin.jsx): `frontend/src/pages/Admin.jsx`

### API and access

- [FastAPI entry](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/auth.py): `backend/app/routers/auth.py`
- [Projects and evaluations API](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/proyectos.py): `backend/app/routers/proyectos.py`
- [Analysis API](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/analisis.py): `backend/app/routers/analisis.py`
- [Metrics API](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/metricas.py): `backend/app/routers/metricas.py`
- [Users and configuration API](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/usuarios.py): `backend/app/routers/usuarios.py`

### Assessment domain

- [Evaluation orchestration](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/scan_service.py): `backend/app/scan_service.py`
- [Quick analysis service](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/analisis_service.py): `backend/app/analisis_service.py`
- [Risk classification](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/risk.py): `backend/app/risk.py`

### Scanning integrations

- [Port and service scan](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/scanner.py): `backend/app/scanner.py`
- [OWASP ZAP client](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/zap_client.py): `backend/app/zap_client.py`
- **VirusTotal**

### Persistence and output

- **PostgreSQL**
- [Database access](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain records](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/models.py): `backend/app/models.py`
- [Report generation API](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/routers/reportes.py): `backend/app/routers/reportes.py`
- [PDF renderer](https://github.com/ivancyao/capstone-securescan/blob/main/backend/app/reportes_pdf.py): `backend/app/reportes_pdf.py`

### Other components

- **Organization user**

## Connections

- Organization user → React application: uses (evidence: `README.md`)
- React application → Projects and assets: routes to (evidence: `frontend/src/App.jsx`)
- React application → Evaluations and findings: routes to (evidence: `frontend/src/App.jsx`)
- React application → Quick analysis: routes to (evidence: `frontend/src/App.jsx`)
- React application → Reports and comparison: routes to (evidence: `frontend/src/App.jsx`)
- React application → Administration: routes to (evidence: `frontend/src/App.jsx`)
- Data and actions → API client: calls (evidence: `frontend/src/context/DataContext.jsx`)
- API client → FastAPI entry: sends requests (evidence: `README.md`)
- FastAPI entry → Authentication: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Projects and evaluations API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Analysis API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Metrics API: registers (evidence: `backend/app/main.py`)
- FastAPI entry → Users and configuration API: registers (evidence: `backend/app/main.py`)
- Projects and evaluations API → Evaluation orchestration: starts evaluation (evidence: `backend/app/routers/proyectos.py`)
- Analysis API → Quick analysis service: invokes (evidence: `backend/app/routers/analisis.py`)
- Evaluation orchestration → Port and service scan: runs scan (evidence: `backend/app/scan_service.py`)
- Evaluation orchestration → Risk classification: classifies findings (evidence: `backend/app/scan_service.py`)
- Evaluation orchestration → OWASP ZAP client: requests scan (evidence: `backend/app/scan_service.py`)
- Evaluation orchestration → Database access: persists results (evidence: `backend/app/scan_service.py`)
- Quick analysis service → Port and service scan: uses (evidence: `backend/app/analisis_service.py`)
- Quick analysis service → Database access: accesses (evidence: `backend/app/analisis_service.py`)
- Quick analysis service → VirusTotal: checks reputation (evidence: `README.md`)
- Port and service scan → Organization user: scans authorized target (evidence: `README.md`)
- OWASP ZAP client → Risk classification: classifies findings (evidence: `backend/app/zap_client.py`)
- Database access → PostgreSQL: connects (evidence: `backend/app/database.py`)
- Domain records → Database access: defines mapped records (evidence: `backend/app/models.py`)
- Projects and evaluations API → Database access: queries and updates (evidence: `backend/app/routers/proyectos.py`)
- Authentication → Database access: accesses accounts (evidence: `backend/app/routers/auth.py`)
- Metrics API → Database access: queries metrics (evidence: `backend/app/routers/metricas.py`)
- Report generation API → PDF renderer: generates PDF (evidence: `backend/app/routers/reportes.py`)
- Report generation API → Database access: stores report records (evidence: `backend/app/routers/reportes.py`)
