# jaykwok/artex architecture

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

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

## Overview

ARTEX is a self-hosted AI penetration-testing system with a Go backend and Next.js interface. Users configure a task and its scope; the backend coordinates exploration agents that use tools to investigate assets and record findings, while traffic capture, evidence, approvals, and reports support review. The UI also exposes task execution, findings, traffic, and system configuration. Edges are limited to relationships shown by the README or SOURCE INDEX references; several important subsystems are represented from documented capabilities and the file tree, without asserting unsampled internal call chains.

Main entry points: [`server/server.go`](https://github.com/jaykwok/artex/blob/main/server/server.go) (HTTP API), [`agent/worker.go`](https://github.com/jaykwok/artex/blob/main/agent/worker.go) (Intent worker), [`db/sqlite.go`](https://github.com/jaykwok/artex/blob/main/db/sqlite.go) (Business SQLite), [`server/manager.go`](https://github.com/jaykwok/artex/blob/main/server/manager.go) (Task manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interface"]
  node_web_tasks["Task workspace<br/>[page.tsx]"]
  node_web_findings["Findings UI<br/>[page.tsx]"]
  node_web_chat["Human-in-loop chat<br/>[page.tsx]"]
  node_http_api["HTTP API<br/>[server.go]"]
end

subgraph group_execution["Exploration runtime"]
  node_task_manager["Task manager<br/>[manager.go]"]
  node_engine["Exploration engine<br/>[engine.go]"]
  node_planner["Intent planner<br/>[planner.go]"]
  node_worker["Intent worker<br/>[worker.go]"]
  node_tool_runtime["Agent tools<br/>[tools.go]"]
  node_toolrun["Long-running tools<br/>[manager.go]"]
  node_mcp_client["Remote MCP<br/>[client.go]"]
end

subgraph group_review["Evidence and review"]
  node_findings["Finding records<br/>[findings.go]"]
  node_reporting["Finding reports<br/>[findings.go]"]
  node_traffic["Traffic capture<br/>[traffic.go]"]
  node_evidence[("Evidence store<br/>[store.go]")]
  node_intercept["Command approvals<br/>[intercept.go]"]
end

subgraph group_persistence["State and integrations"]
  node_business_db[("Business SQLite<br/>[sqlite.go]")]
  node_llm_recording["LLM recordings<br/>[llmrec.go]"]
  node_asset_sync["ScopeSentry sync"]
end

node_user(("Operator"))

node_user -->|"manages tasks"| node_web_tasks
node_web_tasks -.->|"requests task data"| node_http_api
node_web_findings -.->|"requests findings"| node_http_api
node_web_chat -.->|"sends chat"| node_http_api
node_http_api -->|"uses manager"| node_task_manager
node_http_api -->|"uses engine"| node_engine
node_task_manager -->|"persists state"| node_business_db
node_engine -->|"runs worker steps"| node_worker
node_worker -->|"reads and writes"| node_business_db
node_worker -->|"gates tool calls"| node_intercept
node_worker -->|"uses tools"| node_tool_runtime
node_engine -.->|"runs planner"| node_planner
node_tool_runtime -.->|"delegates async runs"| node_toolrun
node_tool_runtime -.->|"invokes remote tools"| node_mcp_client
node_worker -.->|"records findings"| node_findings
node_http_api -->|"serves finding reports"| node_reporting
node_task_manager -->|"starts capture proxy"| node_traffic
node_evidence -->|"references traffic"| node_traffic
node_llm_recording -->|"stores usage"| node_business_db
node_http_api -.->|"exposes asset sync"| node_asset_sync
node_asset_sync -->|"imports scoped assets"| node_business_db
node_user -->|"reviews findings"| node_web_findings
node_user -->|"steers exploration"| node_web_chat

click node_web_tasks "https://github.com/jaykwok/artex/blob/main/web/src/app/(main)/function/tasks/page.tsx"
click node_web_findings "https://github.com/jaykwok/artex/blob/main/web/src/app/(main)/function/findings/page.tsx"
click node_web_chat "https://github.com/jaykwok/artex/blob/main/web/src/app/(main)/chat/page.tsx"
click node_http_api "https://github.com/jaykwok/artex/blob/main/server/server.go"
click node_task_manager "https://github.com/jaykwok/artex/blob/main/server/manager.go"
click node_engine "https://github.com/jaykwok/artex/blob/main/server/engine.go"
click node_planner "https://github.com/jaykwok/artex/blob/main/agent/planner.go"
click node_worker "https://github.com/jaykwok/artex/blob/main/agent/worker.go"
click node_tool_runtime "https://github.com/jaykwok/artex/blob/main/agent/tools.go"
click node_toolrun "https://github.com/jaykwok/artex/blob/main/internal/toolrun/manager.go"
click node_mcp_client "https://github.com/jaykwok/artex/blob/main/mcphttp/client.go"
click node_findings "https://github.com/jaykwok/artex/blob/main/db/findings.go"
click node_reporting "https://github.com/jaykwok/artex/blob/main/report/findings.go"
click node_traffic "https://github.com/jaykwok/artex/blob/main/traffic/traffic.go"
click node_evidence "https://github.com/jaykwok/artex/blob/main/evidence/store.go"
click node_intercept "https://github.com/jaykwok/artex/blob/main/intercept/intercept.go"
click node_business_db "https://github.com/jaykwok/artex/blob/main/db/sqlite.go"
click node_llm_recording "https://github.com/jaykwok/artex/blob/main/llmrec/llmrec.go"
click node_asset_sync "https://github.com/jaykwok/artex/blob/main/server/sync_scopesentry.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_tasks,node_web_findings,node_web_chat,node_http_api toneBlue
class node_task_manager,node_engine,node_planner,node_worker,node_tool_runtime,node_toolrun,node_mcp_client toneAmber
class node_findings,node_reporting,node_traffic,node_evidence,node_intercept toneMint
class node_business_db,node_llm_recording,node_asset_sync toneRose
class node_user toneIndigo
```

## Components

### User interface

- [Task workspace](https://github.com/jaykwok/artex/blob/main/web/src/app/(main)/function/tasks/page.tsx): `web/src/app/(main)/function/tasks/page.tsx`
- [Findings UI](https://github.com/jaykwok/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/jaykwok/artex/blob/main/web/src/app/(main)/chat/page.tsx): `web/src/app/(main)/chat/page.tsx`
- [HTTP API](https://github.com/jaykwok/artex/blob/main/server/server.go): `server/server.go`

### Exploration runtime

- [Task manager](https://github.com/jaykwok/artex/blob/main/server/manager.go): `server/manager.go`
- [Exploration engine](https://github.com/jaykwok/artex/blob/main/server/engine.go): `server/engine.go`
- [Intent planner](https://github.com/jaykwok/artex/blob/main/agent/planner.go): `agent/planner.go`
- [Intent worker](https://github.com/jaykwok/artex/blob/main/agent/worker.go): `agent/worker.go`
- [Agent tools](https://github.com/jaykwok/artex/blob/main/agent/tools.go): `agent/tools.go`
- [Long-running tools](https://github.com/jaykwok/artex/blob/main/internal/toolrun/manager.go): `internal/toolrun/manager.go`
- [Remote MCP](https://github.com/jaykwok/artex/blob/main/mcphttp/client.go): `mcphttp/client.go`

### Evidence and review

- [Finding records](https://github.com/jaykwok/artex/blob/main/db/findings.go): `db/findings.go`
- [Finding reports](https://github.com/jaykwok/artex/blob/main/report/findings.go): `report/findings.go`
- [Traffic capture](https://github.com/jaykwok/artex/blob/main/traffic/traffic.go): `traffic/traffic.go`
- [Evidence store](https://github.com/jaykwok/artex/blob/main/evidence/store.go): `evidence/store.go`
- [Command approvals](https://github.com/jaykwok/artex/blob/main/intercept/intercept.go): `intercept/intercept.go`

### State and integrations

- [Business SQLite](https://github.com/jaykwok/artex/blob/main/db/sqlite.go): `db/sqlite.go`
- [LLM recordings](https://github.com/jaykwok/artex/blob/main/llmrec/llmrec.go): `llmrec/llmrec.go`
- [ScopeSentry sync](https://github.com/jaykwok/artex/blob/main/server/sync_scopesentry.go): `server/sync_scopesentry.go`

### Other components

- **Operator**

## Connections

- Operator → Task workspace: manages tasks (evidence: `README.md`)
- Task workspace → HTTP API: requests task data
- Findings UI → HTTP API: requests findings
- Human-in-loop chat → HTTP API: sends chat
- HTTP API → Task manager: uses manager (evidence: `server/server.go`)
- HTTP API → Exploration engine: uses engine (evidence: `server/server.go`)
- Task manager → Business SQLite: persists state (evidence: `README.md`)
- Exploration engine → Intent worker: runs worker steps (evidence: `server/engine.go`)
- Intent worker → Business SQLite: reads and writes (evidence: `agent/worker.go`)
- Intent worker → Command approvals: gates tool calls (evidence: `agent/worker.go`)
- Intent worker → Agent tools: uses tools (evidence: `agent/tools.go`)
- Exploration engine → Intent planner: runs planner
- Agent tools → Long-running tools: delegates async runs
- Agent tools → Remote MCP: invokes remote tools
- Intent worker → Finding records: records findings
- HTTP API → Finding reports: serves finding reports (evidence: `server/server.go`)
- Task manager → Traffic capture: starts capture proxy (evidence: `server/manager.go`)
- Evidence store → Traffic capture: references traffic (evidence: `evidence/store.go`)
- LLM recordings → Business SQLite: stores usage (evidence: `llmrec/llmrec.go`)
- HTTP API → ScopeSentry sync: exposes asset sync
- ScopeSentry sync → Business SQLite: imports scoped assets (evidence: `README.md`)
- Operator → Findings UI: reviews findings (evidence: `README.md`)
- Operator → Human-in-loop chat: steers exploration (evidence: `README.md`)
