# paras7955/web-security-audit-platform architecture

> Architecture diagram of the GitHub repository paras7955/web-security-audit-platform, 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/paras7955/web-security-audit-platform
- Repository: https://github.com/paras7955/web-security-audit-platform

## Overview

ScopeHarbor is a local-first, guarded application-security audit workspace. Operators configure authorized targets or repository assets, choose an eligible profile, confirm authorization, launch scans, and review normalized findings, posture, comparisons, reports, and optional finding guidance. The README documents the browser/API/database and queued worker architecture, plus relay-isolated web scanning and bounded repository analysis. Some domain modules are unsampled; their presence and capabilities are documented, but uncertain internal call paths are left unconnected.

Main entry points: [`backend/app/main.py`](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/main.py) (FastAPI routes), [`backend/worker/main.py`](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/worker/main.py) (Lease-fenced worker), [`backend/app/findings/service.py`](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/findings/service.py) (Finding triage), [`backend/relay/main.py`](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/relay/main.py) (Guarded relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operator["Operator workspace"]
  node_ui["Workspace UI<br/>[AppShell.tsx]"]
end

subgraph group_control["API and policy"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_auth["Identity and profiles<br/>[auth.py]"]
  node_scope["Targets and policies<br/>[targets.py]"]
  node_repoassets["Repository assets"]
end

subgraph group_execution["Audit execution"]
  node_worker["Lease-fenced worker<br/>[main.py]"]
  node_lifecycle["Scan lifecycle<br/>[lifecycle.py]"]
  node_webscan["Guarded web scanner<br/>[crawler.py]"]
  node_relay["Guarded relay<br/>[main.py]"]
  node_zap["Disposable-demo ZAP<br/>[active.py]"]
  node_reposcan["Repository analysis<br/>[adapters.py]"]
end

subgraph group_review["Evidence and intelligence"]
  node_findings["Finding triage<br/>[service.py]"]
  node_risk["Risk intelligence<br/>[risk.py]"]
  node_reports["Reports<br/>[service.py]"]
  node_guidance["AI guidance<br/>[service.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_state[("Audit state<br/>[models.py]")]
  node_contracts["Scan contracts<br/>[contracts.py]"]
  node_safety["Sanitization<br/>[sanitization.py]"]
end

node_operator(("Operator"))
node_target(("Authorized target"))

node_operator -->|"uses"| node_ui
node_ui -->|"calls API"| node_api
node_api -->|"authenticates"| node_auth
node_api -->|"reads and writes"| node_state
node_api -->|"routes requests"| node_scope
node_api -->|"routes requests"| node_repoassets
node_api -->|"queues scans"| node_worker
node_worker -->|"claims scans"| node_state
node_worker -->|"uses lifecycle"| node_lifecycle
node_worker -.->|"executes scans"| node_webscan
node_worker -->|"runs analysis"| node_reposcan
node_worker -->|"runs eligible ZAP"| node_zap
node_webscan -->|"fetches through"| node_relay
node_relay -->|"validates and dials"| node_target
node_zap -->|"uses validated scope"| node_relay
node_lifecycle -.->|"normalizes evidence"| node_findings
node_findings -.->|"informs posture"| node_risk
node_findings -.->|"supplies evidence"| node_reports
node_findings -.->|"requests guidance"| node_guidance
node_api -.->|"serves reports"| node_reports
node_api -.->|"serves guidance"| node_guidance
node_contracts -.->|"defines scan states"| node_worker
node_safety -->|"sanitizes evidence"| node_findings
node_safety -->|"sanitizes output"| node_reports

click node_ui "https://github.com/paras7955/web-security-audit-platform/blob/main/frontend/src/components/AppShell.tsx"
click node_api "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/main.py"
click node_auth "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/security/auth.py"
click node_scope "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/api/targets.py"
click node_repoassets "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/api/repository_assets.py"
click node_state "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/models.py"
click node_contracts "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/core/contracts.py"
click node_worker "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/worker/main.py"
click node_lifecycle "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/scans/lifecycle.py"
click node_webscan "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/scanner/crawler.py"
click node_relay "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/relay/main.py"
click node_zap "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/zap/active.py"
click node_reposcan "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/repo_scanner/adapters.py"
click node_findings "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/findings/service.py"
click node_risk "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/risk.py"
click node_reports "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/reports/service.py"
click node_guidance "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/ai/service.py"
click node_safety "https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/security/sanitization.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_ui toneBlue
class node_api,node_auth,node_scope,node_repoassets toneAmber
class node_worker,node_lifecycle,node_webscan,node_relay,node_zap,node_reposcan toneMint
class node_findings,node_risk,node_reports,node_guidance toneRose
class node_state,node_contracts,node_safety,node_operator,node_target toneIndigo
```

## Components

### Operator workspace

- [Workspace UI](https://github.com/paras7955/web-security-audit-platform/blob/main/frontend/src/components/AppShell.tsx): `frontend/src/components/AppShell.tsx`

### API and policy

- [FastAPI routes](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/main.py): `backend/app/main.py`
- [Identity and profiles](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/security/auth.py): `backend/app/security/auth.py`
- [Targets and policies](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/api/targets.py): `backend/app/api/targets.py`
- [Repository assets](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/api/repository_assets.py): `backend/app/api/repository_assets.py`

### Audit execution

- [Lease-fenced worker](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/worker/main.py): `backend/worker/main.py`
- [Scan lifecycle](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/scans/lifecycle.py): `backend/app/scans/lifecycle.py`
- [Guarded web scanner](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/scanner/crawler.py): `backend/app/scanner/crawler.py`
- [Guarded relay](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/relay/main.py): `backend/relay/main.py`
- [Disposable-demo ZAP](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/zap/active.py): `backend/app/zap/active.py`
- [Repository analysis](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/repo_scanner/adapters.py): `backend/app/repo_scanner/adapters.py`

### Evidence and intelligence

- [Finding triage](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/findings/service.py): `backend/app/findings/service.py`
- [Risk intelligence](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/risk.py): `backend/app/risk.py`
- [Reports](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/reports/service.py): `backend/app/reports/service.py`
- [AI guidance](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/ai/service.py): `backend/app/ai/service.py`

### Shared foundations

- [Audit state](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/models.py): `backend/app/models.py`
- [Scan contracts](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/core/contracts.py): `backend/app/core/contracts.py`
- [Sanitization](https://github.com/paras7955/web-security-audit-platform/blob/main/backend/app/security/sanitization.py): `backend/app/security/sanitization.py`

### Other components

- **Operator**
- **Authorized target**

## Connections

- Operator → Workspace UI: uses (evidence: `README.md`)
- Workspace UI → FastAPI routes: calls API (evidence: `README.md`)
- FastAPI routes → Identity and profiles: authenticates (evidence: `backend/app/main.py`)
- FastAPI routes → Audit state: reads and writes (evidence: `README.md`)
- FastAPI routes → Targets and policies: routes requests (evidence: `backend/app/main.py`)
- FastAPI routes → Repository assets: routes requests (evidence: `backend/app/main.py`)
- FastAPI routes → Lease-fenced worker: queues scans (evidence: `README.md`)
- Lease-fenced worker → Audit state: claims scans (evidence: `README.md`)
- Lease-fenced worker → Scan lifecycle: uses lifecycle (evidence: `backend/worker/main.py`)
- Lease-fenced worker → Guarded web scanner: executes scans (evidence: `README.md`)
- Lease-fenced worker → Repository analysis: runs analysis (evidence: `README.md`)
- Lease-fenced worker → Disposable-demo ZAP: runs eligible ZAP (evidence: `README.md`)
- Guarded web scanner → Guarded relay: fetches through (evidence: `README.md`)
- Guarded relay → Authorized target: validates and dials (evidence: `README.md`)
- Disposable-demo ZAP → Guarded relay: uses validated scope (evidence: `README.md`)
- Scan lifecycle → Finding triage: normalizes evidence
- Finding triage → Risk intelligence: informs posture (evidence: `README.md`)
- Finding triage → Reports: supplies evidence (evidence: `README.md`)
- Finding triage → AI guidance: requests guidance (evidence: `README.md`)
- FastAPI routes → Reports: serves reports (evidence: `README.md`)
- FastAPI routes → AI guidance: serves guidance (evidence: `README.md`)
- Scan contracts → Lease-fenced worker: defines scan states (evidence: `backend/worker/main.py`)
- Sanitization → Finding triage: sanitizes evidence (evidence: `backend/app/findings/service.py`)
- Sanitization → Reports: sanitizes output (evidence: `backend/app/reports/service.py`)