# intrusive-thots/james-linux architecture

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

- Interactive diagram: https://gitdiagram.com/intrusive-thots/james-linux
- Repository: https://github.com/intrusive-thots/james-linux

## Overview

JAMES is a Linux wireless-security operations application with a PyQt desktop client, FastAPI/WebSocket backend, and React web client. Users inspect wireless networks, select targets, run authorized assessment actions, monitor capture or cracking progress, and review logs and results; an AI agent and autopilot provide additional action and workflow modes. The orchestrator coordinates execution tools and the native layer, while a separate Wireless SOC API stores sensor observations and tracks approved access points and detections. Arrows reflect documented or indexed references; unsampled subsystem internals and live sensor wiring are not asserted.

Main entry points: [`james/core/orchestrator/orchestrator.py`](https://github.com/intrusive-thots/james-linux/blob/master/james/core/orchestrator/orchestrator.py) (Action orchestrator), [`james/core/agent/agent.py`](https://github.com/intrusive-thots/james-linux/blob/master/james/core/agent/agent.py) (AI agent), [`web/src/App.tsx`](https://github.com/intrusive-thots/james-linux/blob/master/web/src/App.tsx) (React workspace), [`james/gui/main_window.py`](https://github.com/intrusive-thots/james-linux/blob/master/james/gui/main_window.py) (Desktop UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["User Interfaces"]
  node_desktop["Desktop UI<br/>[main_window.py]"]
  node_desktop_workflows["Desktop workflows"]
  node_web_app["React workspace<br/>[App.tsx]"]
  node_web_state["Client state<br/>[useAppState.ts]"]
  node_websocket["WebSocket client<br/>[useWebSocket.ts]"]
  node_web_pages["Workspace pages"]
end

subgraph group_backend["API and Coordination"]
  node_entry["Application entry<br/>[main.py]"]
  node_api["FastAPI backend<br/>[server.py]"]
  node_orchestrator["Action orchestrator<br/>[orchestrator.py]"]
  node_agent["AI agent<br/>[agent.py]"]
  node_ai_engine["AI engine<br/>[ai_engine.py]"]
  node_primers["Agent primers<br/>[primers.py]"]
  node_reports["Assessment reports<br/>[report.py]"]
  node_autopilot["Autopilot agent<br/>[auto_agent.py]"]
  node_wordlists["Wordlist generator<br/>[generator.py]"]
end

subgraph group_assessment["Wireless Assessment"]
  node_native["Native execution<br/>[native.py]"]
  node_wifi_tools["Wi-Fi tools<br/>[wifi.py]"]
  node_pineap["PineAP suite<br/>[pineap.py]"]
  node_network_guard["Network guard<br/>[net_guard.py]"]
end

subgraph group_soc["Wireless SOC"]
  node_soc_routes["SOC endpoints"]
  node_soc_store[("SOC inventory store<br/>[wireless_soc.py]")]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_desktop
node_operator -->|"uses"| node_web_app
node_entry -->|"launches"| node_desktop
node_entry -->|"starts"| node_api
node_desktop -->|"uses"| node_orchestrator
node_desktop -->|"hosts"| node_desktop_workflows
node_web_app -->|"renders"| node_web_pages
node_web_app -->|"connects"| node_websocket
node_web_app -->|"uses state"| node_web_state
node_websocket -->|"exchanges messages"| node_api
node_api -->|"dispatches actions"| node_orchestrator
node_orchestrator -->|"executes commands"| node_native
node_orchestrator -->|"uses protection"| node_network_guard
node_orchestrator -->|"dispatches attacks"| node_pineap
node_orchestrator -.->|"uses tools"| node_wifi_tools
node_orchestrator -->|"generates lists"| node_wordlists
node_agent -->|"uses"| node_ai_engine
node_agent -->|"coordinates actions"| node_orchestrator
node_agent -->|"loads guidance"| node_primers
node_agent -->|"uses reports"| node_reports
node_api -->|"registers routes"| node_soc_routes
node_soc_routes -->|"reads and writes"| node_soc_store

click node_desktop "https://github.com/intrusive-thots/james-linux/blob/master/james/gui/main_window.py"
click node_desktop_workflows "https://github.com/intrusive-thots/james-linux/tree/master/james/gui/tabs"
click node_web_app "https://github.com/intrusive-thots/james-linux/blob/master/web/src/App.tsx"
click node_web_state "https://github.com/intrusive-thots/james-linux/blob/master/web/src/hooks/useAppState.ts"
click node_websocket "https://github.com/intrusive-thots/james-linux/blob/master/web/src/hooks/useWebSocket.ts"
click node_web_pages "https://github.com/intrusive-thots/james-linux/tree/master/web/src/pages"
click node_entry "https://github.com/intrusive-thots/james-linux/blob/master/main.py"
click node_api "https://github.com/intrusive-thots/james-linux/blob/master/james/api/server.py"
click node_orchestrator "https://github.com/intrusive-thots/james-linux/blob/master/james/core/orchestrator/orchestrator.py"
click node_agent "https://github.com/intrusive-thots/james-linux/blob/master/james/core/agent/agent.py"
click node_ai_engine "https://github.com/intrusive-thots/james-linux/blob/master/james/core/ai_engine.py"
click node_primers "https://github.com/intrusive-thots/james-linux/blob/master/james/core/primers.py"
click node_reports "https://github.com/intrusive-thots/james-linux/blob/master/james/core/report.py"
click node_autopilot "https://github.com/intrusive-thots/james-linux/blob/master/james/core/auto_agent.py"
click node_wordlists "https://github.com/intrusive-thots/james-linux/blob/master/james/wordlists/generator.py"
click node_native "https://github.com/intrusive-thots/james-linux/blob/master/james/layers/native.py"
click node_wifi_tools "https://github.com/intrusive-thots/james-linux/blob/master/james/tools/wifi.py"
click node_pineap "https://github.com/intrusive-thots/james-linux/blob/master/james/tools/pineap.py"
click node_network_guard "https://github.com/intrusive-thots/james-linux/blob/master/james/core/net_guard.py"
click node_soc_routes "https://github.com/intrusive-thots/james-linux/blob/master/james/api/wireless_soc_routes.py"
click node_soc_store "https://github.com/intrusive-thots/james-linux/blob/master/james/api/wireless_soc.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_desktop,node_desktop_workflows,node_web_app,node_web_state,node_websocket,node_web_pages toneBlue
class node_entry,node_api,node_orchestrator,node_agent,node_ai_engine,node_primers,node_reports,node_autopilot,node_wordlists toneAmber
class node_native,node_wifi_tools,node_pineap,node_network_guard toneMint
class node_soc_routes,node_soc_store toneRose
class node_operator toneIndigo
```

## Components

### User Interfaces

- [Desktop UI](https://github.com/intrusive-thots/james-linux/blob/master/james/gui/main_window.py): `james/gui/main_window.py`
- [Desktop workflows](https://github.com/intrusive-thots/james-linux/tree/master/james/gui/tabs): `james/gui/tabs`
- [React workspace](https://github.com/intrusive-thots/james-linux/blob/master/web/src/App.tsx): `web/src/App.tsx`
- [Client state](https://github.com/intrusive-thots/james-linux/blob/master/web/src/hooks/useAppState.ts): `web/src/hooks/useAppState.ts`
- [WebSocket client](https://github.com/intrusive-thots/james-linux/blob/master/web/src/hooks/useWebSocket.ts): `web/src/hooks/useWebSocket.ts`
- [Workspace pages](https://github.com/intrusive-thots/james-linux/tree/master/web/src/pages): `web/src/pages`

### API and Coordination

- [Application entry](https://github.com/intrusive-thots/james-linux/blob/master/main.py): `main.py`
- [FastAPI backend](https://github.com/intrusive-thots/james-linux/blob/master/james/api/server.py): `james/api/server.py`
- [Action orchestrator](https://github.com/intrusive-thots/james-linux/blob/master/james/core/orchestrator/orchestrator.py): `james/core/orchestrator/orchestrator.py`
- [AI agent](https://github.com/intrusive-thots/james-linux/blob/master/james/core/agent/agent.py): `james/core/agent/agent.py`
- [AI engine](https://github.com/intrusive-thots/james-linux/blob/master/james/core/ai_engine.py): `james/core/ai_engine.py`
- [Agent primers](https://github.com/intrusive-thots/james-linux/blob/master/james/core/primers.py): `james/core/primers.py`
- [Assessment reports](https://github.com/intrusive-thots/james-linux/blob/master/james/core/report.py): `james/core/report.py`
- [Autopilot agent](https://github.com/intrusive-thots/james-linux/blob/master/james/core/auto_agent.py): `james/core/auto_agent.py`
- [Wordlist generator](https://github.com/intrusive-thots/james-linux/blob/master/james/wordlists/generator.py): `james/wordlists/generator.py`

### Wireless Assessment

- [Native execution](https://github.com/intrusive-thots/james-linux/blob/master/james/layers/native.py): `james/layers/native.py`
- [Wi-Fi tools](https://github.com/intrusive-thots/james-linux/blob/master/james/tools/wifi.py): `james/tools/wifi.py`
- [PineAP suite](https://github.com/intrusive-thots/james-linux/blob/master/james/tools/pineap.py): `james/tools/pineap.py`
- [Network guard](https://github.com/intrusive-thots/james-linux/blob/master/james/core/net_guard.py): `james/core/net_guard.py`

### Wireless SOC

- [SOC endpoints](https://github.com/intrusive-thots/james-linux/blob/master/james/api/wireless_soc_routes.py): `james/api/wireless_soc_routes.py`
- [SOC inventory store](https://github.com/intrusive-thots/james-linux/blob/master/james/api/wireless_soc.py): `james/api/wireless_soc.py`

### Other components

- **Operator**

## Connections

- Operator → Desktop UI: uses (evidence: `README.md`)
- Operator → React workspace: uses (evidence: `README.md`)
- Application entry → Desktop UI: launches (evidence: `main.py`)
- Application entry → FastAPI backend: starts (evidence: `main.py`)
- Desktop UI → Action orchestrator: uses (evidence: `james/gui/main_window.py`)
- Desktop UI → Desktop workflows: hosts (evidence: `james/gui/main_window.py`)
- React workspace → Workspace pages: renders (evidence: `web/src/App.tsx`)
- React workspace → WebSocket client: connects (evidence: `web/src/App.tsx`)
- React workspace → Client state: uses state (evidence: `web/src/App.tsx`)
- WebSocket client → FastAPI backend: exchanges messages (evidence: `README.md`)
- FastAPI backend → Action orchestrator: dispatches actions (evidence: `james/api/server.py`)
- Action orchestrator → Native execution: executes commands (evidence: `james/core/orchestrator/orchestrator.py`)
- Action orchestrator → Network guard: uses protection (evidence: `james/core/orchestrator/orchestrator.py`)
- Action orchestrator → PineAP suite: dispatches attacks (evidence: `james/core/orchestrator/orchestrator.py`)
- Action orchestrator → Wi-Fi tools: uses tools
- Action orchestrator → Wordlist generator: generates lists (evidence: `james/core/orchestrator/orchestrator.py`)
- AI agent → AI engine: uses (evidence: `james/core/agent/agent.py`)
- AI agent → Action orchestrator: coordinates actions (evidence: `james/core/agent/agent.py`)
- AI agent → Agent primers: loads guidance (evidence: `james/core/agent/agent.py`)
- AI agent → Assessment reports: uses reports (evidence: `james/core/agent/agent.py`)
- FastAPI backend → SOC endpoints: registers routes (evidence: `james/api/server.py`)
- SOC endpoints → SOC inventory store: reads and writes (evidence: `james/api/wireless_soc_routes.py`)