# alsaifybashar/synosec-buildathon architecture

> Architecture diagram of the GitHub repository alsaifybashar/synosec-buildathon, 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/alsaifybashar/synosec-buildathon
- Repository: https://github.com/alsaifybashar/synosec-buildathon

## Overview

SynoSec is an AI-assisted security discovery and orchestration platform. An analyst configures targets and workflows in the dashboard, starts a run through the backend, and receives streamed execution progress plus evidence-backed findings, coverage, reports, and attack paths. The backend reasons over observations, selects and brokers tools, and can dispatch execution through a remote connector; findings and relationships are persisted for review. The graph emphasizes documented product stages and indexed modules; unsampled subsystem links are included only where the README documents them.

Main entry points: [`apps/backend/src/engine/workflow/workflow-execution.service.ts`](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/workflow-execution.service.ts) (Workflow execution), [`apps/frontend/src/app/App.tsx`](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/app/App.tsx) (Security dashboard), [`apps/backend/src/engine/workflow/broker/tool-broker.ts`](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/broker/tool-broker.ts) (Policy and tool broker), [`apps/backend/src/modules/workflows/workflows.routes.ts`](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/workflows/workflows.routes.ts) (Workflow run API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Analyst experience"]
  node_dashboard["Security dashboard<br/>[App.tsx]"]
  node_target_ui["Target management<br/>[page.tsx]"]
  node_workflow_ui["Workflow console<br/>[page.tsx]"]
  node_report_ui["Reports and attack map<br/>[page.tsx]"]
end

subgraph group_orchestration["Backend orchestration"]
  node_api["Backend API<br/>[register-routes.ts]"]
  node_workflow_routes["Workflow run API"]
  node_workflow_engine["Workflow execution"]
  node_reasoning["Agent reasoning"]
  node_target_store[("Target records")]
end

subgraph group_execution["Tool execution"]
  node_tool_registry["AI tool registry<br/>[ai-tools.routes.ts]"]
  node_tool_runtime["Tool runtime<br/>[tool-runtime.ts]"]
  node_tool_runner["AI tool runner<br/>[ai-tool-runner.ts]"]
  node_tool_catalog["Security tool catalog<br/>[tool-catalog.ts]"]
  node_broker["Policy and tool broker<br/>[tool-broker.ts]"]
  node_local_exec["Local tool execution<br/>[script-executor.ts]"]
  node_connector["Remote connector<br/>[main.ts]"]
end

subgraph group_evidence["Evidence and reporting"]
  node_evidence_store[("Scan and evidence state<br/>[scan-store.ts]")]
  node_confidence["Evidence confidence"]
  node_attack_map["Attack-path correlation"]
  node_reports["Execution reports"]
end

subgraph group_contracts["Shared contracts"]
  node_contracts["Shared schemas<br/>[resources.ts]"]
end

node_analyst(("Security analyst"))
node_target(("Authorized target"))

node_analyst -->|"uses"| node_dashboard
node_dashboard -->|"calls API"| node_api
node_dashboard -->|"manages targets"| node_target_ui
node_dashboard -->|"configures runs"| node_workflow_ui
node_dashboard -->|"reviews results"| node_report_ui
node_api -.->|"registers routes"| node_workflow_routes
node_workflow_routes -->|"starts run"| node_workflow_engine
node_workflow_engine -->|"coordinates"| node_reasoning
node_workflow_engine -->|"selects tools"| node_tool_catalog
node_workflow_engine -->|"dispatches requests"| node_broker
node_workflow_engine -->|"records scan"| node_evidence_store
node_workflow_engine -->|"correlates findings"| node_attack_map
node_target_ui -.->|"manages records"| node_target_store
node_tool_registry -->|"resolves tools"| node_tool_runtime
node_tool_runtime -->|"runs tool"| node_tool_runner
node_tool_runner -->|"uses runtime"| node_tool_runtime
node_broker -->|"dispatches locally"| node_local_exec
node_broker -->|"dispatches remotely"| node_connector
node_local_exec -->|"probes"| node_target
node_connector -->|"executes tools"| node_target
node_broker -->|"records observations"| node_evidence_store
node_evidence_store -.->|"supplies observations"| node_confidence
node_workflow_engine -.->|"produces reports"| node_reports
node_reports -->|"serves reports"| node_report_ui
node_attack_map -->|"presents attack paths"| node_report_ui
node_workflow_routes -->|"validates payloads"| node_contracts
node_tool_registry -->|"validates tool data"| node_contracts
node_dashboard -->|"uses shared types"| node_contracts

click node_dashboard "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/app/App.tsx"
click node_target_ui "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/targets/page.tsx"
click node_workflow_ui "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/workflows/page.tsx"
click node_report_ui "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/execution-reports/page.tsx"
click node_api "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/app/register-routes.ts"
click node_workflow_routes "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/workflows/workflows.routes.ts"
click node_workflow_engine "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/workflow-execution.service.ts"
click node_reasoning "https://github.com/alsaifybashar/synosec-buildathon/tree/main/apps/backend/src/engine/workflow"
click node_target_store "https://github.com/alsaifybashar/synosec-buildathon/tree/main/apps/backend/src/modules/targets"
click node_tool_registry "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/ai-tools.routes.ts"
click node_tool_runtime "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/tool-runtime.ts"
click node_tool_runner "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/ai-tool-runner.ts"
click node_tool_catalog "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/tools/tool-catalog.ts"
click node_broker "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/broker/tool-broker.ts"
click node_local_exec "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/tools/script-executor.ts"
click node_connector "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/connector/src/main.ts"
click node_evidence_store "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/scans/scan-store.ts"
click node_confidence "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/broker/confidence-engine.ts"
click node_attack_map "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/findings/cross-host-lateral-routes.ts"
click node_reports "https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/execution-reports/execution-reports.service.ts"
click node_contracts "https://github.com/alsaifybashar/synosec-buildathon/blob/main/packages/contracts/src/resources.ts"

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_dashboard,node_target_ui,node_workflow_ui,node_report_ui toneBlue
class node_api,node_workflow_routes,node_workflow_engine,node_reasoning,node_target_store toneAmber
class node_tool_registry,node_tool_runtime,node_tool_runner,node_tool_catalog,node_broker,node_local_exec,node_connector toneMint
class node_evidence_store,node_confidence,node_attack_map,node_reports toneRose
class node_contracts,node_analyst,node_target toneIndigo
```

## Components

### Analyst experience

- [Security dashboard](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/app/App.tsx): `apps/frontend/src/app/App.tsx`
- [Target management](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/targets/page.tsx): `apps/frontend/src/features/targets/page.tsx`
- [Workflow console](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/workflows/page.tsx): `apps/frontend/src/features/workflows/page.tsx`
- [Reports and attack map](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/frontend/src/features/execution-reports/page.tsx): `apps/frontend/src/features/execution-reports/page.tsx`

### Backend orchestration

- [Backend API](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/app/register-routes.ts): `apps/backend/src/app/register-routes.ts`
- [Workflow run API](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/workflows/workflows.routes.ts): `apps/backend/src/modules/workflows/workflows.routes.ts`
- [Workflow execution](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/workflow-execution.service.ts): `apps/backend/src/engine/workflow/workflow-execution.service.ts`
- [Agent reasoning](https://github.com/alsaifybashar/synosec-buildathon/tree/main/apps/backend/src/engine/workflow): `apps/backend/src/engine/workflow`
- [Target records](https://github.com/alsaifybashar/synosec-buildathon/tree/main/apps/backend/src/modules/targets): `apps/backend/src/modules/targets`

### Tool execution

- [AI tool registry](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/ai-tools.routes.ts): `apps/backend/src/modules/ai-tools/ai-tools.routes.ts`
- [Tool runtime](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/tool-runtime.ts): `apps/backend/src/modules/ai-tools/tool-runtime.ts`
- [AI tool runner](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/ai-tools/ai-tool-runner.ts): `apps/backend/src/modules/ai-tools/ai-tool-runner.ts`
- [Security tool catalog](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/tools/tool-catalog.ts): `apps/backend/src/engine/tools/tool-catalog.ts`
- [Policy and tool broker](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/broker/tool-broker.ts): `apps/backend/src/engine/workflow/broker/tool-broker.ts`
- [Local tool execution](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/tools/script-executor.ts): `apps/backend/src/engine/tools/script-executor.ts`
- [Remote connector](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/connector/src/main.ts): `apps/connector/src/main.ts`

### Evidence and reporting

- [Scan and evidence state](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/scans/scan-store.ts): `apps/backend/src/engine/scans/scan-store.ts`
- [Evidence confidence](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/workflow/broker/confidence-engine.ts): `apps/backend/src/engine/workflow/broker/confidence-engine.ts`
- [Attack-path correlation](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/engine/findings/cross-host-lateral-routes.ts): `apps/backend/src/engine/findings/cross-host-lateral-routes.ts`
- [Execution reports](https://github.com/alsaifybashar/synosec-buildathon/blob/main/apps/backend/src/modules/execution-reports/execution-reports.service.ts): `apps/backend/src/modules/execution-reports/execution-reports.service.ts`

### Shared contracts

- [Shared schemas](https://github.com/alsaifybashar/synosec-buildathon/blob/main/packages/contracts/src/resources.ts): `packages/contracts/src/resources.ts`

### Other components

- **Security analyst**
- **Authorized target**

## Connections

- Security analyst → Security dashboard: uses
- Security dashboard → Backend API: calls API
- Security dashboard → Target management: manages targets
- Security dashboard → Workflow console: configures runs
- Security dashboard → Reports and attack map: reviews results
- Backend API → Workflow run API: registers routes
- Workflow run API → Workflow execution: starts run (evidence: `apps/backend/src/modules/workflows/workflows.routes.ts`)
- Workflow execution → Agent reasoning: coordinates
- Workflow execution → Security tool catalog: selects tools
- Workflow execution → Policy and tool broker: dispatches requests
- Workflow execution → Scan and evidence state: records scan
- Workflow execution → Attack-path correlation: correlates findings
- Target management → Target records: manages records
- AI tool registry → Tool runtime: resolves tools (evidence: `apps/backend/src/modules/ai-tools/ai-tools.routes.ts`)
- Tool runtime → AI tool runner: runs tool (evidence: `apps/backend/src/modules/ai-tools/ai-tools.routes.ts`)
- AI tool runner → Tool runtime: uses runtime (evidence: `apps/backend/src/modules/ai-tools/ai-tool-runner.ts`)
- Policy and tool broker → Local tool execution: dispatches locally
- Policy and tool broker → Remote connector: dispatches remotely
- Local tool execution → Authorized target: probes
- Remote connector → Authorized target: executes tools
- Policy and tool broker → Scan and evidence state: records observations
- Scan and evidence state → Evidence confidence: supplies observations
- Workflow execution → Execution reports: produces reports
- Execution reports → Reports and attack map: serves reports
- Attack-path correlation → Reports and attack map: presents attack paths
- Workflow run API → Shared schemas: validates payloads (evidence: `apps/backend/src/modules/workflows/workflows.routes.ts`)
- AI tool registry → Shared schemas: validates tool data (evidence: `apps/backend/src/modules/ai-tools/ai-tools.routes.ts`)
- Security dashboard → Shared schemas: uses shared types
