# mhtsec/artex architecture

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

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

## Overview

ARTEX is an AI-driven autonomous penetration-testing system: users configure scope and a task, then the backend coordinates planner/worker agents to explore targets, record assets and findings, and expose progress and evidence in the web UI. The README also documents traffic capture, human approval/chat, vulnerability retesting, notifications, external asset synchronization, and MCP integrations. Edges cite the supplied excerpts or README; several substantial feature links are documented capabilities because their individual implementation files were not sampled.

Main entry points: [`server/server.go`](https://github.com/mhtsec/artex/blob/main/server/server.go) (HTTP API and SSE), [`agent/worker.go`](https://github.com/mhtsec/artex/blob/main/agent/worker.go) (Worker agents), [`server/engine.go`](https://github.com/mhtsec/artex/blob/main/server/engine.go) (Exploration engine), [`db/db.go`](https://github.com/mhtsec/artex/blob/main/db/db.go) (PostgreSQL domain store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Web interface"]
  node_web["Task workspace<br/>[page.tsx]"]
  node_findingsui["Findings views<br/>[page.tsx]"]
  node_chatui["Human-in-loop chat<br/>[page.tsx]"]
end

subgraph group_control["Task control"]
  node_server["HTTP API and SSE<br/>[server.go]"]
  node_manager["Task manager<br/>[manager.go]"]
  node_engine["Exploration engine<br/>[engine.go]"]
end

subgraph group_agents["Agent exploration"]
  node_planner["Planner<br/>[planner.go]"]
  node_worker["Worker agents<br/>[worker.go]"]
  node_tools["Security tools<br/>[tools.go]"]
  node_guard["Tool guard<br/>[guard.go]"]
  node_intercept["Approval interception<br/>[intercept.go]"]
  node_retest["Finding retester<br/>[retester.go]"]
end

subgraph group_data["Evidence and storage"]
  node_pg[("PostgreSQL domain store<br/>[db.go]")]
  node_traffic[("Traffic recorder<br/>[traffic.go]")]
  node_evidence[("Durable finding evidence<br/>[store.go]")]
  node_llmrec[("LLM call records<br/>[llmrec.go]")]
  node_report["Finding reports<br/>[findings.go]"]
end

subgraph group_integrations["External integrations"]
  node_llm["LLM provider<br/>[provider.go]"]
  node_mcp["MCP services<br/>[client.go]"]
  node_notifier["Notification channels<br/>[notify.go]"]
  node_scopesentry["ScopeSentry"]
end

node_user(("Operator"))
node_target(("Authorized targets"))

node_user -->|"configures tasks"| node_web
node_web -->|"calls API"| node_server
node_server -->|"manages lifecycle"| node_manager
node_server -->|"routes controls"| node_engine
node_manager -->|"persists tasks"| node_pg
node_engine -->|"runs planning"| node_planner
node_engine -->|"dispatches work"| node_worker
node_worker -->|"invokes tools"| node_tools
node_worker -->|"gates calls"| node_guard
node_guard -->|"requests review"| node_intercept
node_worker -->|"writes exploration"| node_pg
node_worker -.->|"requests completion"| node_llm
node_engine -.->|"records usage"| node_llmrec
node_llmrec -->|"stores call records"| node_pg
node_target -.->|"exchanges HTTP"| node_traffic
node_traffic -->|"indexes exchanges"| node_pg
node_evidence -->|"snapshots exchanges"| node_traffic
node_evidence -->|"binds evidence"| node_pg
node_findingsui -->|"requests findings"| node_server
node_server -->|"generates exports"| node_report
node_user -->|"steers execution"| node_chatui
node_chatui -->|"sends messages"| node_server
node_engine -.->|"runs retest agent"| node_retest
node_server -.->|"dispatches notifications"| node_notifier
node_server -.->|"imports assets"| node_scopesentry
node_worker -.->|"uses MCP tools"| node_mcp
node_traffic -.->|"records requests"| node_target

click node_web "https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/function/tasks/page.tsx"
click node_findingsui "https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/function/findings/page.tsx"
click node_chatui "https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/chat/page.tsx"
click node_server "https://github.com/mhtsec/artex/blob/main/server/server.go"
click node_manager "https://github.com/mhtsec/artex/blob/main/server/manager.go"
click node_engine "https://github.com/mhtsec/artex/blob/main/server/engine.go"
click node_planner "https://github.com/mhtsec/artex/blob/main/agent/planner.go"
click node_worker "https://github.com/mhtsec/artex/blob/main/agent/worker.go"
click node_tools "https://github.com/mhtsec/artex/blob/main/agent/tools.go"
click node_guard "https://github.com/mhtsec/artex/blob/main/guard/guard.go"
click node_intercept "https://github.com/mhtsec/artex/blob/main/intercept/intercept.go"
click node_retest "https://github.com/mhtsec/artex/blob/main/agent/retester.go"
click node_pg "https://github.com/mhtsec/artex/blob/main/db/db.go"
click node_traffic "https://github.com/mhtsec/artex/blob/main/traffic/traffic.go"
click node_evidence "https://github.com/mhtsec/artex/blob/main/evidence/store.go"
click node_llmrec "https://github.com/mhtsec/artex/blob/main/llmrec/llmrec.go"
click node_report "https://github.com/mhtsec/artex/blob/main/report/findings.go"
click node_llm "https://github.com/mhtsec/artex/blob/main/agent/provider.go"
click node_mcp "https://github.com/mhtsec/artex/blob/main/mcphttp/client.go"
click node_notifier "https://github.com/mhtsec/artex/blob/main/notify/notify.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,node_findingsui,node_chatui toneBlue
class node_server,node_manager,node_engine toneAmber
class node_planner,node_worker,node_tools,node_guard,node_intercept,node_retest toneMint
class node_pg,node_traffic,node_evidence,node_llmrec,node_report toneRose
class node_llm,node_mcp,node_notifier,node_scopesentry,node_user,node_target toneIndigo
```

## Components

### Web interface

- [Task workspace](https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/function/tasks/page.tsx): `web/src/app/(main)/function/tasks/page.tsx`
- [Findings views](https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/function/findings/page.tsx): `web/src/app/(main)/function/findings/page.tsx`
- [Human-in-loop chat](https://github.com/mhtsec/artex/blob/main/web/src/app/(main)/chat/page.tsx): `web/src/app/(main)/chat/page.tsx`

### Task control

- [HTTP API and SSE](https://github.com/mhtsec/artex/blob/main/server/server.go): `server/server.go`
- [Task manager](https://github.com/mhtsec/artex/blob/main/server/manager.go): `server/manager.go`
- [Exploration engine](https://github.com/mhtsec/artex/blob/main/server/engine.go): `server/engine.go`

### Agent exploration

- [Planner](https://github.com/mhtsec/artex/blob/main/agent/planner.go): `agent/planner.go`
- [Worker agents](https://github.com/mhtsec/artex/blob/main/agent/worker.go): `agent/worker.go`
- [Security tools](https://github.com/mhtsec/artex/blob/main/agent/tools.go): `agent/tools.go`
- [Tool guard](https://github.com/mhtsec/artex/blob/main/guard/guard.go): `guard/guard.go`
- [Approval interception](https://github.com/mhtsec/artex/blob/main/intercept/intercept.go): `intercept/intercept.go`
- [Finding retester](https://github.com/mhtsec/artex/blob/main/agent/retester.go): `agent/retester.go`

### Evidence and storage

- [PostgreSQL domain store](https://github.com/mhtsec/artex/blob/main/db/db.go): `db/db.go`
- [Traffic recorder](https://github.com/mhtsec/artex/blob/main/traffic/traffic.go): `traffic/traffic.go`
- [Durable finding evidence](https://github.com/mhtsec/artex/blob/main/evidence/store.go): `evidence/store.go`
- [LLM call records](https://github.com/mhtsec/artex/blob/main/llmrec/llmrec.go): `llmrec/llmrec.go`
- [Finding reports](https://github.com/mhtsec/artex/blob/main/report/findings.go): `report/findings.go`

### External integrations

- [LLM provider](https://github.com/mhtsec/artex/blob/main/agent/provider.go): `agent/provider.go`
- [MCP services](https://github.com/mhtsec/artex/blob/main/mcphttp/client.go): `mcphttp/client.go`
- [Notification channels](https://github.com/mhtsec/artex/blob/main/notify/notify.go): `notify/notify.go`
- **ScopeSentry**

### Other components

- **Operator**
- **Authorized targets**

## Connections

- Operator → Task workspace: configures tasks
- Task workspace → HTTP API and SSE: calls API
- HTTP API and SSE → Task manager: manages lifecycle (evidence: `server/server.go`)
- HTTP API and SSE → Exploration engine: routes controls (evidence: `server/server.go`)
- Task manager → PostgreSQL domain store: persists tasks (evidence: `server/manager.go`)
- Exploration engine → Planner: runs planning (evidence: `server/engine.go`)
- Exploration engine → Worker agents: dispatches work (evidence: `server/engine.go`)
- Worker agents → Security tools: invokes tools (evidence: `agent/worker.go`)
- Worker agents → Tool guard: gates calls (evidence: `agent/worker.go`)
- Tool guard → Approval interception: requests review (evidence: `guard/guard.go`)
- Worker agents → PostgreSQL domain store: writes exploration (evidence: `agent/worker.go`)
- Worker agents → LLM provider: requests completion
- Exploration engine → LLM call records: records usage
- LLM call records → PostgreSQL domain store: stores call records (evidence: `llmrec/llmrec.go`)
- Authorized targets → Traffic recorder: exchanges HTTP
- Traffic recorder → PostgreSQL domain store: indexes exchanges (evidence: `traffic/traffic.go`)
- Durable finding evidence → Traffic recorder: snapshots exchanges (evidence: `evidence/store.go`)
- Durable finding evidence → PostgreSQL domain store: binds evidence (evidence: `evidence/store.go`)
- Findings views → HTTP API and SSE: requests findings
- HTTP API and SSE → Finding reports: generates exports (evidence: `server/server.go`)
- Operator → Human-in-loop chat: steers execution
- Human-in-loop chat → HTTP API and SSE: sends messages
- Exploration engine → Finding retester: runs retest agent
- HTTP API and SSE → Notification channels: dispatches notifications
- HTTP API and SSE → ScopeSentry: imports assets
- Worker agents → MCP services: uses MCP tools
- Traffic recorder → Authorized targets: records requests
