# smzuhaib06/securefix-x architecture

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

- Interactive diagram: https://gitdiagram.com/smzuhaib06/securefix-x
- Repository: https://github.com/smzuhaib06/securefix-x

## Overview

SECUREFIX X is a web platform for evidence-grounded vulnerability investigation and human-approved remediation assurance. A developer submits a repository through the frontend; the API creates and persists an investigation, and the orchestrator gathers repository and security evidence, correlates findings, derives an invariant, adds grounded AI reasoning, and proposes a patch. Approval triggers patch application and verification before completion and report export. The README documents additional agent, RAG, adversarial, and mutation capabilities; some are represented at their documented subsystem paths because their wiring is not fully visible in the excerpts.

Main entry points: [`backend/app/orchestrator.py`](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/orchestrator.py) (Workflow orchestrator), [`backend/app/main.py`](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/main.py) (Backend API), [`frontend/app/investigations/new/page.tsx`](https://github.com/smzuhaib06/securefix-x/blob/main/frontend/app/investigations/new/page.tsx) (Investigation UI), [`frontend/components/investigation`](https://github.com/smzuhaib06/securefix-x/tree/main/frontend/components/investigation) (Progress and review UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_frontend["Investigation UI<br/>[page.tsx]"]
  node_live_ui["Progress and review UI"]
  node_frontend_api["Frontend API client<br/>[api.ts]"]
end

subgraph group_workflow["Investigation workflow"]
  node_orchestrator["Workflow orchestrator<br/>[orchestrator.py]"]
  node_agents["Evidence agents"]
  node_correlation["Evidence correlation<br/>[engine.py]"]
  node_invariant["Invariant and root cause<br/>[root_cause.py]"]
  node_evidence_package["Evidence package"]
  node_rag["Security knowledge RAG<br/>[rag.py]"]
  node_reasoning["Grounded AI reasoning"]
  node_nodejs_analysis["Node.js analysis<br/>[js_analyzer.py]"]
  node_runtime_agent["Runtime and log analysis<br/>[runtime_agent.py]"]
end

subgraph group_assurance["Remediation assurance"]
  node_remediation["Patch proposal and apply<br/>[engine.py]"]
  node_approval["Human approval<br/>[main.py]"]
  node_verification["Adversarial verification<br/>[engine.py]"]
  node_mutation["Mutation assurance<br/>[mutation.py]"]
end

subgraph group_platform["State and integrations"]
  node_api["Backend API<br/>[main.py]"]
  node_repository_connector["Repository sandbox<br/>[repository.py]"]
  node_ai_provider["AI provider<br/>[provider.py]"]
  node_store[("Investigation state<br/>[store.py]")]
  node_db[("Persistent database<br/>[db.py]")]
  node_report["Report export<br/>[report.py]"]
end

subgraph group_demo["Demonstration target"]
  node_demo_app["SecureBank demo API<br/>[main.py]"]
  node_demo_db[("Demo SQLite database<br/>[database.py]")]
end

node_developer(("Developer"))

node_developer -->|"starts investigation"| node_frontend
node_frontend -->|"submits request"| node_frontend_api
node_frontend_api -->|"calls API"| node_api
node_api -->|"starts workflow"| node_orchestrator
node_api -->|"reads and updates"| node_store
node_api -->|"streams progress"| node_live_ui
node_api -->|"requests report"| node_report
node_orchestrator -->|"resolves repository"| node_repository_connector
node_repository_connector -.->|"clones remote repository"| node_developer
node_orchestrator -->|"runs agents"| node_agents
node_agents -->|"analyzes JavaScript"| node_nodejs_analysis
node_orchestrator -->|"correlates findings"| node_correlation
node_orchestrator -->|"derives invariant"| node_invariant
node_orchestrator -->|"assembles evidence"| node_evidence_package
node_orchestrator -->|"retrieves guidance"| node_rag
node_orchestrator -->|"requests explanation"| node_reasoning
node_reasoning -.->|"generates reasoning"| node_ai_provider
node_orchestrator -->|"proposes patch"| node_remediation
node_api -->|"records decision"| node_approval
node_approval -->|"continues approved work"| node_orchestrator
node_orchestrator -->|"applies approved patch"| node_remediation
node_orchestrator -->|"verifies patch"| node_verification
node_verification -->|"tests weakened fixes"| node_mutation
node_orchestrator -->|"runs telemetry analysis"| node_runtime_agent
node_live_ui -->|"presents findings and diff"| node_developer
node_report -->|"returns Markdown"| node_api
node_demo_app -->|"reads and writes"| node_demo_db

click node_frontend "https://github.com/smzuhaib06/securefix-x/blob/main/frontend/app/investigations/new/page.tsx"
click node_live_ui "https://github.com/smzuhaib06/securefix-x/tree/main/frontend/components/investigation"
click node_frontend_api "https://github.com/smzuhaib06/securefix-x/blob/main/frontend/lib/api.ts"
click node_api "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/main.py"
click node_orchestrator "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/orchestrator.py"
click node_repository_connector "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/repository.py"
click node_agents "https://github.com/smzuhaib06/securefix-x/tree/main/backend/app/agents"
click node_correlation "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/correlation/engine.py"
click node_invariant "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/remediation/root_cause.py"
click node_evidence_package "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/evidence_package.py"
click node_rag "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/rag.py"
click node_reasoning "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/security_reasoner.py"
click node_ai_provider "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/provider.py"
click node_remediation "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/remediation/engine.py"
click node_approval "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/main.py"
click node_verification "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/verification/engine.py"
click node_mutation "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/verification/mutation.py"
click node_nodejs_analysis "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/nodejs/js_analyzer.py"
click node_runtime_agent "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/agents/runtime_agent.py"
click node_store "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/store.py"
click node_db "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/db.py"
click node_report "https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/report.py"
click node_demo_app "https://github.com/smzuhaib06/securefix-x/blob/main/demo-app/app/main.py"
click node_demo_db "https://github.com/smzuhaib06/securefix-x/blob/main/demo-app/app/database.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_frontend,node_live_ui,node_frontend_api toneBlue
class node_orchestrator,node_agents,node_correlation,node_invariant,node_evidence_package,node_rag,node_reasoning,node_nodejs_analysis,node_runtime_agent toneAmber
class node_remediation,node_approval,node_verification,node_mutation toneMint
class node_api,node_repository_connector,node_ai_provider,node_store,node_db,node_report toneRose
class node_demo_app,node_demo_db,node_developer toneIndigo
```

## Components

### Web experience

- [Investigation UI](https://github.com/smzuhaib06/securefix-x/blob/main/frontend/app/investigations/new/page.tsx): `frontend/app/investigations/new/page.tsx`
- [Progress and review UI](https://github.com/smzuhaib06/securefix-x/tree/main/frontend/components/investigation): `frontend/components/investigation`
- [Frontend API client](https://github.com/smzuhaib06/securefix-x/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`

### Investigation workflow

- [Workflow orchestrator](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/orchestrator.py): `backend/app/orchestrator.py`
- [Evidence agents](https://github.com/smzuhaib06/securefix-x/tree/main/backend/app/agents): `backend/app/agents`
- [Evidence correlation](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/correlation/engine.py): `backend/app/correlation/engine.py`
- [Invariant and root cause](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/remediation/root_cause.py): `backend/app/remediation/root_cause.py`
- [Evidence package](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/evidence_package.py): `backend/app/ai/evidence_package.py`
- [Security knowledge RAG](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/rag.py): `backend/app/ai/rag.py`
- [Grounded AI reasoning](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/security_reasoner.py): `backend/app/ai/security_reasoner.py`
- [Node.js analysis](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/nodejs/js_analyzer.py): `backend/app/nodejs/js_analyzer.py`
- [Runtime and log analysis](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/agents/runtime_agent.py): `backend/app/agents/runtime_agent.py`

### Remediation assurance

- [Patch proposal and apply](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/remediation/engine.py): `backend/app/remediation/engine.py`
- [Human approval](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/main.py): `backend/app/main.py`
- [Adversarial verification](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/verification/engine.py): `backend/app/verification/engine.py`
- [Mutation assurance](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/verification/mutation.py): `backend/app/verification/mutation.py`

### State and integrations

- [Backend API](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/main.py): `backend/app/main.py`
- [Repository sandbox](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/repository.py): `backend/app/repository.py`
- [AI provider](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/ai/provider.py): `backend/app/ai/provider.py`
- [Investigation state](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/store.py): `backend/app/store.py`
- [Persistent database](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/db.py): `backend/app/db.py`
- [Report export](https://github.com/smzuhaib06/securefix-x/blob/main/backend/app/report.py): `backend/app/report.py`

### Demonstration target

- [SecureBank demo API](https://github.com/smzuhaib06/securefix-x/blob/main/demo-app/app/main.py): `demo-app/app/main.py`
- [Demo SQLite database](https://github.com/smzuhaib06/securefix-x/blob/main/demo-app/app/database.py): `demo-app/app/database.py`

### Other components

- **Developer**

## Connections

- Developer → Investigation UI: starts investigation
- Investigation UI → Frontend API client: submits request
- Frontend API client → Backend API: calls API
- Backend API → Workflow orchestrator: starts workflow
- Backend API → Investigation state: reads and updates
- Backend API → Progress and review UI: streams progress
- Backend API → Report export: requests report
- Workflow orchestrator → Repository sandbox: resolves repository
- Repository sandbox → Developer: clones remote repository
- Workflow orchestrator → Evidence agents: runs agents
- Evidence agents → Node.js analysis: analyzes JavaScript
- Workflow orchestrator → Evidence correlation: correlates findings
- Workflow orchestrator → Invariant and root cause: derives invariant
- Workflow orchestrator → Evidence package: assembles evidence
- Workflow orchestrator → Security knowledge RAG: retrieves guidance
- Workflow orchestrator → Grounded AI reasoning: requests explanation
- Grounded AI reasoning → AI provider: generates reasoning
- Workflow orchestrator → Patch proposal and apply: proposes patch
- Backend API → Human approval: records decision
- Human approval → Workflow orchestrator: continues approved work
- Workflow orchestrator → Patch proposal and apply: applies approved patch
- Workflow orchestrator → Adversarial verification: verifies patch
- Adversarial verification → Mutation assurance: tests weakened fixes
- Workflow orchestrator → Runtime and log analysis: runs telemetry analysis
- Progress and review UI → Developer: presents findings and diff
- Report export → Backend API: returns Markdown
- SecureBank demo API → Demo SQLite database: reads and writes