# yv1ing/z3r0 architecture

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

- Interactive diagram: https://gitdiagram.com/yv1ing/z3r0
- Repository: https://github.com/yv1ing/z3r0

## Overview

Z3r0 is an AI-native workbench for authorized security assessments. Operators use the React console to manage assessment projects and sandbox resources, then submit scoped work through the API to a session-based multi-agent runtime. Agents use tools to investigate in sandboxes and coordinate project work; project records preserve assets, evidence, findings, and attack paths, while session events support live updates and replay. The README documents these capabilities and the router-handler-service-model layering; unsampled implementation details are represented only where that documentation supports them.

Main entry points: [`core/runtime/session.py`](https://github.com/yv1ing/z3r0/blob/main/core/runtime/session.py) (Session runtime), [`service/sandbox`](https://github.com/yv1ing/z3r0/tree/main/service/sandbox) (Sandbox services), [`app.py`](https://github.com/yv1ing/z3r0/blob/main/app.py) (FastAPI API), [`core/tools`](https://github.com/yv1ing/z3r0/tree/main/core/tools) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Operator console"]
  node_workbench["React workbench<br/>[App.tsx]"]
end

subgraph group_control["Control plane"]
  node_api["FastAPI API<br/>[app.py]"]
  node_agent_routes["Agent routes<br/>[sessions.py]"]
  node_project_routes["Project routes<br/>[records.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_session_runtime["Session runtime<br/>[session.py]"]
  node_agent_system["Agent system<br/>[registry.py]"]
  node_tool_layer["Agent tools"]
  node_timeline["Session timeline<br/>[timeline.py]"]
  node_timeline_data[("Event records<br/>[event_log.py]")]
  node_knowledge["Knowledge retrieval<br/>[runtime.py]"]
end

subgraph group_assessment["Assessment records"]
  node_project_services["Project services"]
  node_project_data[("Project records")]
end

subgraph group_execution["Sandbox execution"]
  node_sandbox_services["Sandbox services"]
  node_sandbox_data[("Sandbox records")]
  node_proxy["Control and egress proxy<br/>[main.go]"]
  node_hosts["Managed hosts<br/>[hosts.py]"]
end

node_operator(("Authorized operator"))
node_postgres[("PostgreSQL")]
node_browser_api["REST and WebSocket API"]
node_external_network(("External targets"))

node_operator -->|"operates"| node_workbench
node_workbench -->|"sends requests"| node_browser_api
node_browser_api -->|"serves"| node_api
node_api -->|"mounts routes"| node_agent_routes
node_api -->|"mounts routes"| node_project_routes
node_agent_routes -->|"starts sessions"| node_session_runtime
node_session_runtime -->|"runs agents"| node_agent_system
node_session_runtime -->|"retrieves context"| node_knowledge
node_agent_system -->|"invokes tools"| node_tool_layer
node_tool_layer -->|"records assessment work"| node_project_services
node_project_routes -->|"handles requests"| node_project_services
node_project_services -->|"persists records"| node_project_data
node_tool_layer -->|"uses sandbox"| node_sandbox_services
node_sandbox_services -->|"uses managed hosts"| node_hosts
node_sandbox_services -->|"persists task state"| node_sandbox_data
node_sandbox_services -->|"uses control proxy"| node_proxy
node_proxy -->|"controls egress"| node_external_network
node_session_runtime -->|"emits events"| node_timeline
node_timeline -->|"persists events"| node_timeline_data
node_project_data -->|"stores records"| node_postgres
node_timeline_data -->|"stores events"| node_postgres
node_sandbox_data -->|"stores state"| node_postgres
node_knowledge -->|"uses storage"| node_postgres

click node_workbench "https://github.com/yv1ing/z3r0/blob/main/web/src/app/App.tsx"
click node_api "https://github.com/yv1ing/z3r0/blob/main/app.py"
click node_agent_routes "https://github.com/yv1ing/z3r0/blob/main/router/agent/sessions.py"
click node_project_routes "https://github.com/yv1ing/z3r0/blob/main/router/work_project/records.py"
click node_project_services "https://github.com/yv1ing/z3r0/tree/main/service/work_project"
click node_project_data "https://github.com/yv1ing/z3r0/tree/main/model/work_project"
click node_session_runtime "https://github.com/yv1ing/z3r0/blob/main/core/runtime/session.py"
click node_agent_system "https://github.com/yv1ing/z3r0/blob/main/core/agent/registry.py"
click node_tool_layer "https://github.com/yv1ing/z3r0/tree/main/core/tools"
click node_timeline "https://github.com/yv1ing/z3r0/blob/main/core/runtime/timeline.py"
click node_timeline_data "https://github.com/yv1ing/z3r0/blob/main/model/agent/event_log.py"
click node_knowledge "https://github.com/yv1ing/z3r0/blob/main/core/lightrag/runtime.py"
click node_sandbox_services "https://github.com/yv1ing/z3r0/tree/main/service/sandbox"
click node_sandbox_data "https://github.com/yv1ing/z3r0/tree/main/model/sandbox"
click node_proxy "https://github.com/yv1ing/z3r0/blob/main/sandbox/proxy/main.go"
click node_hosts "https://github.com/yv1ing/z3r0/blob/main/service/host/hosts.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_workbench toneBlue
class node_api,node_agent_routes,node_project_routes,node_postgres toneAmber
class node_session_runtime,node_agent_system,node_tool_layer,node_timeline,node_timeline_data,node_knowledge,node_browser_api toneMint
class node_project_services,node_project_data toneRose
class node_sandbox_services,node_sandbox_data,node_proxy,node_hosts,node_operator,node_external_network toneIndigo
```

## Components

### Operator console

- [React workbench](https://github.com/yv1ing/z3r0/blob/main/web/src/app/App.tsx): `web/src/app/App.tsx`

### Control plane

- [FastAPI API](https://github.com/yv1ing/z3r0/blob/main/app.py): `app.py`
- [Agent routes](https://github.com/yv1ing/z3r0/blob/main/router/agent/sessions.py): `router/agent/sessions.py`
- [Project routes](https://github.com/yv1ing/z3r0/blob/main/router/work_project/records.py): `router/work_project/records.py`

### Agent runtime

- [Session runtime](https://github.com/yv1ing/z3r0/blob/main/core/runtime/session.py): `core/runtime/session.py`
- [Agent system](https://github.com/yv1ing/z3r0/blob/main/core/agent/registry.py): `core/agent/registry.py`
- [Agent tools](https://github.com/yv1ing/z3r0/tree/main/core/tools): `core/tools`
- [Session timeline](https://github.com/yv1ing/z3r0/blob/main/core/runtime/timeline.py): `core/runtime/timeline.py`
- [Event records](https://github.com/yv1ing/z3r0/blob/main/model/agent/event_log.py): `model/agent/event_log.py`
- [Knowledge retrieval](https://github.com/yv1ing/z3r0/blob/main/core/lightrag/runtime.py): `core/lightrag/runtime.py`

### Assessment records

- [Project services](https://github.com/yv1ing/z3r0/tree/main/service/work_project): `service/work_project`
- [Project records](https://github.com/yv1ing/z3r0/tree/main/model/work_project): `model/work_project`

### Sandbox execution

- [Sandbox services](https://github.com/yv1ing/z3r0/tree/main/service/sandbox): `service/sandbox`
- [Sandbox records](https://github.com/yv1ing/z3r0/tree/main/model/sandbox): `model/sandbox`
- [Control and egress proxy](https://github.com/yv1ing/z3r0/blob/main/sandbox/proxy/main.go): `sandbox/proxy/main.go`
- [Managed hosts](https://github.com/yv1ing/z3r0/blob/main/service/host/hosts.py): `service/host/hosts.py`

### Other components

- **Authorized operator**
- **PostgreSQL**
- **REST and WebSocket API**
- **External targets**

## Connections

- Authorized operator → React workbench: operates
- React workbench → REST and WebSocket API: sends requests
- REST and WebSocket API → FastAPI API: serves
- FastAPI API → Agent routes: mounts routes
- FastAPI API → Project routes: mounts routes
- Agent routes → Session runtime: starts sessions
- Session runtime → Agent system: runs agents
- Session runtime → Knowledge retrieval: retrieves context
- Agent system → Agent tools: invokes tools
- Agent tools → Project services: records assessment work
- Project routes → Project services: handles requests
- Project services → Project records: persists records
- Agent tools → Sandbox services: uses sandbox
- Sandbox services → Managed hosts: uses managed hosts
- Sandbox services → Sandbox records: persists task state
- Sandbox services → Control and egress proxy: uses control proxy
- Control and egress proxy → External targets: controls egress
- Session runtime → Session timeline: emits events
- Session timeline → Event records: persists events
- Project records → PostgreSQL: stores records
- Event records → PostgreSQL: stores events
- Sandbox records → PostgreSQL: stores state
- Knowledge retrieval → PostgreSQL: uses storage