# booksiyi1412/artex architecture

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

- Interactive diagram: https://gitdiagram.com/booksiyi1412/artex
- Repository: https://github.com/booksiyi1412/artex

## Overview

ARTEX is an AI-assisted autonomous penetration-testing system: users configure scope and agents, run exploration tasks, inspect live activity and evidence, and manage findings and retests through a web UI. The backend coordinates planner/worker execution, persists task and security data, and exposes an API; optional capabilities include traffic capture, MCP tools, notifications, ScopeSentry synchronization, and side-question chat. The graph reflects README claims and sampled source references; several feature paths are represented at their exact directory level because their implementation was not sampled.

Main entry points: [`agent/worker.go`](https://github.com/booksiyi1412/artex/blob/main/agent/worker.go) (Intent worker), [`server/server.go`](https://github.com/booksiyi1412/artex/blob/main/server/server.go) (HTTP API), [`server/manager.go`](https://github.com/booksiyi1412/artex/blob/main/server/manager.go) (Task manager), [`db`](https://github.com/booksiyi1412/artex/tree/main/db) (PostgreSQL stores)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_web["ARTEX web UI"]
end

subgraph group_runtime["Task execution"]
  node_manager["Task manager<br/>[manager.go]"]
  node_engine["Exploration engine<br/>[engine.go]"]
  node_worker["Intent worker<br/>[worker.go]"]
  node_agentcore["Agent runtime<br/>[agentcore.go]"]
  node_harness["Tool harness<br/>[query.go]"]
  node_sideq["Side questions<br/>[service.go]"]
end

subgraph group_security["Testing evidence"]
  node_traffic["Traffic capture<br/>[traffic.go]"]
  node_evidence[("Evidence store<br/>[store.go]")]
  node_findings["Findings and retests"]
  node_report["Finding reports<br/>[findings.go]"]
  node_guard["Tool-call approvals<br/>[guard.go]"]
  node_intercept["Interception review<br/>[intercept.go]"]
end

subgraph group_platform["Backend services"]
  node_api["HTTP API<br/>[server.go]"]
  node_store[("PostgreSQL stores")]
end

subgraph group_integrations["External integrations"]
  node_llm["LLM providers<br/>[provider.go]"]
  node_mcp["Remote MCP tools<br/>[client.go]"]
  node_sync["ScopeSentry sync"]
  node_notify["Notifications<br/>[notify.go]"]
end

node_user(("Security operator"))
node_taskuser(("Assessment targets"))
node_postgres[("PostgreSQL")]
node_scopesentry["ScopeSentry"]

node_user -->|"configures and reviews"| node_web
node_web -->|"calls API"| node_api
node_api -.->|"resolves tasks"| node_manager
node_manager -.->|"coordinates runs"| node_engine
node_engine -->|"runs intents"| node_worker
node_worker -->|"executes agent"| node_agentcore
node_worker -->|"runs tool loop"| node_harness
node_agentcore -->|"uses harness"| node_harness
node_harness -->|"requests completions"| node_llm
node_worker -->|"records exploration"| node_store
node_manager -.->|"opens database"| node_store
node_postgres -->|"stores task data"| node_manager
node_manager -->|"starts proxy"| node_traffic
node_traffic -->|"records traffic"| node_store
node_traffic -.->|"provides evidence"| node_evidence
node_api -->|"serves workflows"| node_findings
node_findings -.->|"persists findings"| node_store
node_report -->|"reads findings"| node_store
node_worker -->|"gates tool calls"| node_guard
node_guard -->|"consults review"| node_intercept
node_worker -.->|"invokes remote tools"| node_mcp
node_api -.->|"offers synchronization"| node_sync
node_sync -->|"imports assets"| node_scopesentry
node_api -.->|"configures delivery"| node_notify
node_api -.->|"handles questions"| node_sideq
node_taskuser -.->|"requests assessment"| node_engine

click node_web "https://github.com/booksiyi1412/artex/tree/main/web/src/app/(main)"
click node_api "https://github.com/booksiyi1412/artex/blob/main/server/server.go"
click node_manager "https://github.com/booksiyi1412/artex/blob/main/server/manager.go"
click node_engine "https://github.com/booksiyi1412/artex/blob/main/server/engine.go"
click node_worker "https://github.com/booksiyi1412/artex/blob/main/agent/worker.go"
click node_agentcore "https://github.com/booksiyi1412/artex/blob/main/norma/agentcore/agentcore.go"
click node_harness "https://github.com/booksiyi1412/artex/blob/main/norma/harness/query.go"
click node_store "https://github.com/booksiyi1412/artex/tree/main/db"
click node_traffic "https://github.com/booksiyi1412/artex/blob/main/traffic/traffic.go"
click node_evidence "https://github.com/booksiyi1412/artex/blob/main/evidence/store.go"
click node_findings "https://github.com/booksiyi1412/artex/blob/main/server/finding_workflow.go"
click node_report "https://github.com/booksiyi1412/artex/blob/main/report/findings.go"
click node_guard "https://github.com/booksiyi1412/artex/blob/main/guard/guard.go"
click node_intercept "https://github.com/booksiyi1412/artex/blob/main/intercept/intercept.go"
click node_llm "https://github.com/booksiyi1412/artex/blob/main/norma/llm/provider.go"
click node_mcp "https://github.com/booksiyi1412/artex/blob/main/mcphttp/client.go"
click node_sync "https://github.com/booksiyi1412/artex/blob/main/server/sync_scopesentry.go"
click node_notify "https://github.com/booksiyi1412/artex/blob/main/notify/notify.go"
click node_sideq "https://github.com/booksiyi1412/artex/blob/main/sidequestion/service.go"

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_web toneBlue
class node_manager,node_engine,node_worker,node_agentcore,node_harness,node_sideq,node_postgres toneAmber
class node_traffic,node_evidence,node_findings,node_report,node_guard,node_intercept toneMint
class node_api,node_store toneRose
class node_llm,node_mcp,node_sync,node_notify,node_user,node_taskuser,node_scopesentry toneIndigo
```

## Components

### Web interface

- [ARTEX web UI](https://github.com/booksiyi1412/artex/tree/main/web/src/app/(main)): `web/src/app/(main)`

### Task execution

- [Task manager](https://github.com/booksiyi1412/artex/blob/main/server/manager.go): `server/manager.go`
- [Exploration engine](https://github.com/booksiyi1412/artex/blob/main/server/engine.go): `server/engine.go`
- [Intent worker](https://github.com/booksiyi1412/artex/blob/main/agent/worker.go): `agent/worker.go`
- [Agent runtime](https://github.com/booksiyi1412/artex/blob/main/norma/agentcore/agentcore.go): `norma/agentcore/agentcore.go`
- [Tool harness](https://github.com/booksiyi1412/artex/blob/main/norma/harness/query.go): `norma/harness/query.go`
- [Side questions](https://github.com/booksiyi1412/artex/blob/main/sidequestion/service.go): `sidequestion/service.go`

### Testing evidence

- [Traffic capture](https://github.com/booksiyi1412/artex/blob/main/traffic/traffic.go): `traffic/traffic.go`
- [Evidence store](https://github.com/booksiyi1412/artex/blob/main/evidence/store.go): `evidence/store.go`
- [Findings and retests](https://github.com/booksiyi1412/artex/blob/main/server/finding_workflow.go): `server/finding_workflow.go`
- [Finding reports](https://github.com/booksiyi1412/artex/blob/main/report/findings.go): `report/findings.go`
- [Tool-call approvals](https://github.com/booksiyi1412/artex/blob/main/guard/guard.go): `guard/guard.go`
- [Interception review](https://github.com/booksiyi1412/artex/blob/main/intercept/intercept.go): `intercept/intercept.go`

### Backend services

- [HTTP API](https://github.com/booksiyi1412/artex/blob/main/server/server.go): `server/server.go`
- [PostgreSQL stores](https://github.com/booksiyi1412/artex/tree/main/db): `db`

### External integrations

- [LLM providers](https://github.com/booksiyi1412/artex/blob/main/norma/llm/provider.go): `norma/llm/provider.go`
- [Remote MCP tools](https://github.com/booksiyi1412/artex/blob/main/mcphttp/client.go): `mcphttp/client.go`
- [ScopeSentry sync](https://github.com/booksiyi1412/artex/blob/main/server/sync_scopesentry.go): `server/sync_scopesentry.go`
- [Notifications](https://github.com/booksiyi1412/artex/blob/main/notify/notify.go): `notify/notify.go`

### Other components

- **Security operator**
- **Assessment targets**
- **PostgreSQL**
- **ScopeSentry**

## Connections

- Security operator → ARTEX web UI: configures and reviews (evidence: `README.md`)
- ARTEX web UI → HTTP API: calls API (evidence: `README.md`)
- HTTP API → Task manager: resolves tasks
- Task manager → Exploration engine: coordinates runs
- Exploration engine → Intent worker: runs intents (evidence: `server/engine.go`)
- Intent worker → Agent runtime: executes agent (evidence: `agent/worker.go`)
- Intent worker → Tool harness: runs tool loop (evidence: `agent/worker.go`)
- Agent runtime → Tool harness: uses harness (evidence: `norma/agentcore/agentcore.go`)
- Tool harness → LLM providers: requests completions (evidence: `norma/harness/query.go`)
- Intent worker → PostgreSQL stores: records exploration (evidence: `agent/worker.go`)
- Task manager → PostgreSQL stores: opens database (evidence: `server/manager.go`)
- PostgreSQL → Task manager: stores task data (evidence: `server/manager.go`)
- Task manager → Traffic capture: starts proxy (evidence: `server/manager.go`)
- Traffic capture → PostgreSQL stores: records traffic (evidence: `traffic/traffic.go`)
- Traffic capture → Evidence store: provides evidence
- HTTP API → Findings and retests: serves workflows (evidence: `server/server.go`)
- Findings and retests → PostgreSQL stores: persists findings
- Finding reports → PostgreSQL stores: reads findings (evidence: `report/findings.go`)
- Intent worker → Tool-call approvals: gates tool calls (evidence: `agent/worker.go`)
- Tool-call approvals → Interception review: consults review (evidence: `guard/guard.go`)
- Intent worker → Remote MCP tools: invokes remote tools
- HTTP API → ScopeSentry sync: offers synchronization
- ScopeSentry sync → ScopeSentry: imports assets (evidence: `README.md`)
- HTTP API → Notifications: configures delivery
- HTTP API → Side questions: handles questions
- Assessment targets → Exploration engine: requests assessment
