# omercn1/orod-security-lab architecture

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

- Interactive diagram: https://gitdiagram.com/omercn1/orod-security-lab
- Repository: https://github.com/omercn1/orod-security-lab

## Overview

OROD is a local-first security review and refactoring application. A user starts a scan in the dashboard; the API coordinates a multi-agent run that prepares a repository, scans and selects findings, proposes a patch, validates it, pauses for review, and may publish a draft pull request. The dashboard follows persisted run events and supports replay and review decisions. The graph reflects the documented workflow and sampled wiring; implementation details for several agent stages and API routes were not sampled, so uncertain links are omitted.

Main entry points: [`backend/src/orod/graph/builder.py`](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/builder.py) (Security team graph), [`backend/src/orod/agents/developer/__init__.py`](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/developer/__init__.py) (Patch development), [`frontend/src/features/runs/useRun.ts`](https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/features/runs/useRun.ts) (Run lifecycle), [`backend/src/orod/adapters/repository/validation_checks.py`](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/repository/validation_checks.py) (Patch validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard<br/>[App.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
  node_run_hook["Run lifecycle<br/>[useRun.ts]"]
  node_replay["Event replay<br/>[useReplay.ts]"]
end

subgraph group_api["API and runs"]
  node_runs_api["Run routes<br/>[runs.py]"]
  node_coordinator["Run coordinator<br/>[run_analysis.py]"]
  node_event_stream["Event streaming<br/>[stream_events.py]"]
  node_vulnerability_sync["Advisory sync"]
end

subgraph group_workflow["Agent workflow"]
  node_team_graph["Security team graph<br/>[builder.py]"]
  node_repository_stage["Repository survey<br/>[__init__.py]"]
  node_security_stage["Security analysis<br/>[__init__.py]"]
  node_finding_selection["Finding selection<br/>[routing.py]"]
  node_developer_stage["Patch development<br/>[__init__.py]"]
  node_validation_stage["Patch validation"]
  node_review_stage["Human review<br/>[routing.py]"]
  node_publish_stage["Draft PR publishing<br/>[cli.py]"]
end

subgraph group_integrations["Repository and security"]
  node_repository_adapter["Git repository<br/>[git.py]"]
  node_scanner_adapters["Security scanners"]
  node_llm_routing["Patch providers<br/>[routing.py]"]
  node_osv_adapter["OSV advisories<br/>[osv.py]"]
end

subgraph group_state["Run and advisory state"]
  node_run_store[("Run event store<br/>[sqlite.py]")]
  node_storage_ports["Storage contracts<br/>[storage.py]"]
  node_advisory_store[("Advisory index<br/>[chroma.py]")]
end

node_user(("User"))
node_github_service["GitHub"]
node_model_service["LLM service"]
node_docker_service["Docker validation"]

node_user -->|"starts and reviews"| node_dashboard_app
node_dashboard_app -->|"controls run"| node_run_hook
node_run_hook -->|"requests run"| node_api_client
node_api_client -->|"calls API"| node_runs_api
node_runs_api -->|"coordinates"| node_coordinator
node_coordinator -->|"runs workflow"| node_team_graph
node_team_graph -->|"surveys repository"| node_repository_stage
node_team_graph -->|"runs security analysis"| node_security_stage
node_security_stage -->|"returns findings"| node_finding_selection
node_finding_selection -->|"routes selected findings"| node_developer_stage
node_team_graph -->|"proposes fixes"| node_developer_stage
node_developer_stage -->|"validates patch"| node_validation_stage
node_validation_stage -->|"routes outcome"| node_review_stage
node_review_stage -->|"requests regeneration"| node_developer_stage
node_review_stage -->|"approves validated patch"| node_publish_stage
node_repository_stage -->|"prepares repository"| node_repository_adapter
node_security_stage -->|"runs scanners"| node_scanner_adapters
node_developer_stage -->|"requests patch"| node_llm_routing
node_llm_routing -.->|"requests generation"| node_model_service
node_validation_stage -->|"validates changes"| node_repository_adapter
node_repository_adapter -->|"clones repository"| node_github_service
node_validation_stage -.->|"runs trusted tests"| node_docker_service
node_publish_stage -.->|"opens draft PR"| node_github_service
node_coordinator -->|"persists run"| node_run_store
node_team_graph -->|"records events"| node_run_store
node_run_hook -->|"subscribes to events"| node_event_stream
node_event_stream -->|"reads event history"| node_run_store
node_run_hook -->|"replays events"| node_replay
node_vulnerability_sync -->|"fetches advisories"| node_osv_adapter
node_osv_adapter -->|"indexes advisories"| node_advisory_store
node_team_graph -->|"searches advisories"| node_advisory_store

click node_dashboard_app "https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/App.tsx"
click node_api_client "https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/api/client.ts"
click node_run_hook "https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/features/runs/useRun.ts"
click node_replay "https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/features/runs/useReplay.ts"
click node_runs_api "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/api/routes/runs.py"
click node_coordinator "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/run_analysis.py"
click node_event_stream "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/stream_events.py"
click node_team_graph "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/builder.py"
click node_repository_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/architect/__init__.py"
click node_security_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/security/__init__.py"
click node_finding_selection "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/routing.py"
click node_developer_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/developer/__init__.py"
click node_validation_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/repository/validation_checks.py"
click node_review_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/routing.py"
click node_publish_stage "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/github/cli.py"
click node_repository_adapter "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/repository/git.py"
click node_scanner_adapters "https://github.com/omercn1/orod-security-lab/tree/main/backend/src/orod/adapters/scanners"
click node_llm_routing "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/llm/routing.py"
click node_osv_adapter "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/scanners/osv.py"
click node_run_store "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/persistence/sqlite.py"
click node_storage_ports "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/ports/storage.py"
click node_advisory_store "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/vector/chroma.py"
click node_vulnerability_sync "https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/sync_vulnerabilities.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_dashboard_app,node_api_client,node_run_hook,node_replay,node_user toneBlue
class node_runs_api,node_coordinator,node_event_stream,node_vulnerability_sync toneAmber
class node_team_graph,node_repository_stage,node_security_stage,node_finding_selection,node_developer_stage,node_validation_stage,node_review_stage,node_publish_stage toneMint
class node_repository_adapter,node_scanner_adapters,node_llm_routing,node_osv_adapter toneRose
class node_run_store,node_storage_ports,node_advisory_store,node_github_service,node_model_service,node_docker_service toneIndigo
```

## Components

### Dashboard

- [Dashboard](https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Run lifecycle](https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/features/runs/useRun.ts): `frontend/src/features/runs/useRun.ts`
- [Event replay](https://github.com/omercn1/orod-security-lab/blob/main/frontend/src/features/runs/useReplay.ts): `frontend/src/features/runs/useReplay.ts`

### API and runs

- [Run routes](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/api/routes/runs.py): `backend/src/orod/api/routes/runs.py`
- [Run coordinator](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/run_analysis.py): `backend/src/orod/application/run_analysis.py`
- [Event streaming](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/stream_events.py): `backend/src/orod/application/stream_events.py`
- [Advisory sync](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/application/sync_vulnerabilities.py): `backend/src/orod/application/sync_vulnerabilities.py`

### Agent workflow

- [Security team graph](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/builder.py): `backend/src/orod/graph/builder.py`
- [Repository survey](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/architect/__init__.py): `backend/src/orod/agents/architect/__init__.py`
- [Security analysis](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/security/__init__.py): `backend/src/orod/agents/security/__init__.py`
- [Finding selection](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/routing.py): `backend/src/orod/graph/routing.py`
- [Patch development](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/agents/developer/__init__.py): `backend/src/orod/agents/developer/__init__.py`
- [Patch validation](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/repository/validation_checks.py): `backend/src/orod/adapters/repository/validation_checks.py`
- [Human review](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/graph/routing.py): `backend/src/orod/graph/routing.py`
- [Draft PR publishing](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/github/cli.py): `backend/src/orod/adapters/github/cli.py`

### Repository and security

- [Git repository](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/repository/git.py): `backend/src/orod/adapters/repository/git.py`
- [Security scanners](https://github.com/omercn1/orod-security-lab/tree/main/backend/src/orod/adapters/scanners): `backend/src/orod/adapters/scanners`
- [Patch providers](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/llm/routing.py): `backend/src/orod/adapters/llm/routing.py`
- [OSV advisories](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/scanners/osv.py): `backend/src/orod/adapters/scanners/osv.py`

### Run and advisory state

- [Run event store](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/persistence/sqlite.py): `backend/src/orod/adapters/persistence/sqlite.py`
- [Storage contracts](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/ports/storage.py): `backend/src/orod/ports/storage.py`
- [Advisory index](https://github.com/omercn1/orod-security-lab/blob/main/backend/src/orod/adapters/vector/chroma.py): `backend/src/orod/adapters/vector/chroma.py`

### Other components

- **User**
- **GitHub**
- **LLM service**
- **Docker validation**

## Connections

- User → Dashboard: starts and reviews
- Dashboard → Run lifecycle: controls run
- Run lifecycle → API client: requests run
- API client → Run routes: calls API
- Run routes → Run coordinator: coordinates
- Run coordinator → Security team graph: runs workflow
- Security team graph → Repository survey: surveys repository
- Security team graph → Security analysis: runs security analysis
- Security analysis → Finding selection: returns findings
- Finding selection → Patch development: routes selected findings
- Security team graph → Patch development: proposes fixes
- Patch development → Patch validation: validates patch
- Patch validation → Human review: routes outcome
- Human review → Patch development: requests regeneration
- Human review → Draft PR publishing: approves validated patch
- Repository survey → Git repository: prepares repository
- Security analysis → Security scanners: runs scanners
- Patch development → Patch providers: requests patch
- Patch providers → LLM service: requests generation
- Patch validation → Git repository: validates changes
- Git repository → GitHub: clones repository
- Patch validation → Docker validation: runs trusted tests
- Draft PR publishing → GitHub: opens draft PR
- Run coordinator → Run event store: persists run
- Security team graph → Run event store: records events
- Run lifecycle → Event streaming: subscribes to events
- Event streaming → Run event store: reads event history
- Run lifecycle → Event replay: replays events
- Advisory sync → OSV advisories: fetches advisories
- OSV advisories → Advisory index: indexes advisories
- Security team graph → Advisory index: searches advisories