# tsukhani/jclaw architecture

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

- Interactive diagram: https://gitdiagram.com/tsukhani/jclaw
- Repository: https://github.com/tsukhani/jclaw

## Overview

JClaw is a Java AI-assistant and automation platform. Its primary workflow is an operator or channel user submitting a conversation, which is routed through the application to an agent; the agent builds context, calls an LLM and tools, then returns a response through the originating channel. The repository also contains persistent memory, model routing, scheduled work, and browser/scrape capabilities. The map combines README-described capabilities with relationships visible in indexed references and excerpts; unsampled implementation details are not inferred as call edges.

Main entry points: [`app/agents/AgentRunner.java`](https://github.com/tsukhani/jclaw/blob/main/app/agents/AgentRunner.java) (Agent Execution), [`app/controllers/ApiConversationsController.java`](https://github.com/tsukhani/jclaw/blob/main/app/controllers/ApiConversationsController.java) (Conversation Handling), [`app/agents/ContextWindowManager.java`](https://github.com/tsukhani/jclaw/blob/main/app/agents/ContextWindowManager.java) (Context Management), [`app/agents/ToolRegistry.java`](https://github.com/tsukhani/jclaw/blob/main/app/agents/ToolRegistry.java) (Agent Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User Interaction"]
  node_web["Web Frontend"]
  node_api["HTTP API"]
  node_channels["Chat Channels"]
end

subgraph group_agent["Agent Runtime"]
  node_conversation["Conversation Handling"]
  node_runner["Agent Execution<br/>[AgentRunner.java]"]
  node_context["Context Management"]
  node_compression["Context Compression"]
end

subgraph group_intelligence["AI Capabilities"]
  node_provider["LLM Providers<br/>[LlmProvider.java]"]
  node_router["Model Router<br/>[ModelRouter.java]"]
  node_memory[("Agent Memory")]
  node_tools["Agent Tools<br/>[ToolRegistry.java]"]
  node_mcp["MCP Integration"]
end

subgraph group_automation["Automation"]
  node_scraping["Browser And Scraping"]
  node_tasks["Scheduled Tasks"]
  node_taskrun["Task Execution<br/>[TaskExecutor.java]"]
end

subgraph group_platform["Platform State"]
  node_models[("Domain Records<br/>[Conversation.java]")]
  node_config[("Configuration<br/>[ConfigService.java]")]
  node_events[("Event Logging<br/>[EventLogger.java]")]
  node_search[("Message Search<br/>[LuceneIndexer.java]")]
end

node_user(("User"))

node_user -->|"uses chat"| node_web
node_user -->|"messages through"| node_channels
node_web -.->|"requests"| node_api
node_api -->|"routes conversations"| node_conversation
node_conversation -->|"queues turns"| node_runner
node_channels -.->|"delivers turns"| node_runner
node_runner -.->|"prepares context"| node_context
node_context -.->|"compresses messages"| node_compression
node_runner -->|"calls model"| node_provider
node_runner -->|"executes tools"| node_tools
node_runner -->|"uses memory"| node_memory
node_router -->|"selects model"| node_provider
node_tools -->|"exposes MCP tools"| node_mcp
node_tools -->|"runs scrape jobs"| node_scraping
node_tasks -.->|"dispatches work"| node_taskrun
node_conversation -->|"reads and writes"| node_models
node_conversation -->|"uses message search"| node_search
node_context -->|"reads settings"| node_config
node_compression -->|"reads settings"| node_config
node_scraping -->|"persists jobs"| node_models
node_scraping -->|"invokes agent"| node_runner
node_events -->|"persists event logs"| node_models

click node_web "https://github.com/tsukhani/jclaw/tree/main/frontend"
click node_api "https://github.com/tsukhani/jclaw/tree/main/app/controllers"
click node_channels "https://github.com/tsukhani/jclaw/tree/main/app/channels"
click node_conversation "https://github.com/tsukhani/jclaw/blob/main/app/controllers/ApiConversationsController.java"
click node_runner "https://github.com/tsukhani/jclaw/blob/main/app/agents/AgentRunner.java"
click node_context "https://github.com/tsukhani/jclaw/blob/main/app/agents/ContextWindowManager.java"
click node_compression "https://github.com/tsukhani/jclaw/blob/main/app/agents/CompressionPipeline.java"
click node_provider "https://github.com/tsukhani/jclaw/blob/main/app/llm/LlmProvider.java"
click node_router "https://github.com/tsukhani/jclaw/blob/main/app/llm/routing/ModelRouter.java"
click node_memory "https://github.com/tsukhani/jclaw/blob/main/app/memory/JpaMemoryStore.java"
click node_tools "https://github.com/tsukhani/jclaw/blob/main/app/agents/ToolRegistry.java"
click node_mcp "https://github.com/tsukhani/jclaw/blob/main/app/mcp/McpConnectionManager.java"
click node_scraping "https://github.com/tsukhani/jclaw/blob/main/app/services/scrape/ScrapeJobService.java"
click node_tasks "https://github.com/tsukhani/jclaw/blob/main/app/services/TaskSchedulingService.java"
click node_taskrun "https://github.com/tsukhani/jclaw/blob/main/app/services/TaskExecutor.java"
click node_models "https://github.com/tsukhani/jclaw/blob/main/app/models/Conversation.java"
click node_config "https://github.com/tsukhani/jclaw/blob/main/app/services/ConfigService.java"
click node_events "https://github.com/tsukhani/jclaw/blob/main/app/services/EventLogger.java"
click node_search "https://github.com/tsukhani/jclaw/blob/main/app/services/search/LuceneIndexer.java"

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_api,node_channels,node_user toneBlue
class node_conversation,node_runner,node_context,node_compression toneAmber
class node_provider,node_router,node_memory,node_tools,node_mcp toneMint
class node_scraping,node_tasks,node_taskrun toneRose
class node_models,node_config,node_events,node_search toneIndigo
```

## Components

### User Interaction

- [Web Frontend](https://github.com/tsukhani/jclaw/tree/main/frontend): `frontend`
- [HTTP API](https://github.com/tsukhani/jclaw/tree/main/app/controllers): `app/controllers`
- [Chat Channels](https://github.com/tsukhani/jclaw/tree/main/app/channels): `app/channels`

### Agent Runtime

- [Conversation Handling](https://github.com/tsukhani/jclaw/blob/main/app/controllers/ApiConversationsController.java): `app/controllers/ApiConversationsController.java`
- [Agent Execution](https://github.com/tsukhani/jclaw/blob/main/app/agents/AgentRunner.java): `app/agents/AgentRunner.java`
- [Context Management](https://github.com/tsukhani/jclaw/blob/main/app/agents/ContextWindowManager.java): `app/agents/ContextWindowManager.java`
- [Context Compression](https://github.com/tsukhani/jclaw/blob/main/app/agents/CompressionPipeline.java): `app/agents/CompressionPipeline.java`

### AI Capabilities

- [LLM Providers](https://github.com/tsukhani/jclaw/blob/main/app/llm/LlmProvider.java): `app/llm/LlmProvider.java`
- [Model Router](https://github.com/tsukhani/jclaw/blob/main/app/llm/routing/ModelRouter.java): `app/llm/routing/ModelRouter.java`
- [Agent Memory](https://github.com/tsukhani/jclaw/blob/main/app/memory/JpaMemoryStore.java): `app/memory/JpaMemoryStore.java`
- [Agent Tools](https://github.com/tsukhani/jclaw/blob/main/app/agents/ToolRegistry.java): `app/agents/ToolRegistry.java`
- [MCP Integration](https://github.com/tsukhani/jclaw/blob/main/app/mcp/McpConnectionManager.java): `app/mcp/McpConnectionManager.java`

### Automation

- [Browser And Scraping](https://github.com/tsukhani/jclaw/blob/main/app/services/scrape/ScrapeJobService.java): `app/services/scrape/ScrapeJobService.java`
- [Scheduled Tasks](https://github.com/tsukhani/jclaw/blob/main/app/services/TaskSchedulingService.java): `app/services/TaskSchedulingService.java`
- [Task Execution](https://github.com/tsukhani/jclaw/blob/main/app/services/TaskExecutor.java): `app/services/TaskExecutor.java`

### Platform State

- [Domain Records](https://github.com/tsukhani/jclaw/blob/main/app/models/Conversation.java): `app/models/Conversation.java`
- [Configuration](https://github.com/tsukhani/jclaw/blob/main/app/services/ConfigService.java): `app/services/ConfigService.java`
- [Event Logging](https://github.com/tsukhani/jclaw/blob/main/app/services/EventLogger.java): `app/services/EventLogger.java`
- [Message Search](https://github.com/tsukhani/jclaw/blob/main/app/services/search/LuceneIndexer.java): `app/services/search/LuceneIndexer.java`

### Other components

- **User**

## Connections

- User → Web Frontend: uses chat (evidence: `README.md`)
- User → Chat Channels: messages through (evidence: `README.md`)
- Web Frontend → HTTP API: requests
- HTTP API → Conversation Handling: routes conversations (evidence: `app/controllers/ApiConversationsController.java`)
- Conversation Handling → Agent Execution: queues turns (evidence: `app/controllers/ApiConversationsController.java`)
- Chat Channels → Agent Execution: delivers turns
- Agent Execution → Context Management: prepares context
- Context Management → Context Compression: compresses messages
- Agent Execution → LLM Providers: calls model (evidence: `README.md`)
- Agent Execution → Agent Tools: executes tools (evidence: `README.md`)
- Agent Execution → Agent Memory: uses memory (evidence: `README.md`)
- Model Router → LLM Providers: selects model (evidence: `README.md`)
- Agent Tools → MCP Integration: exposes MCP tools (evidence: `app/mcp/McpConnectionManager.java`)
- Agent Tools → Browser And Scraping: runs scrape jobs (evidence: `app/services/scrape/ScrapeJobService.java`)
- Scheduled Tasks → Task Execution: dispatches work
- Conversation Handling → Domain Records: reads and writes (evidence: `app/controllers/ApiConversationsController.java`)
- Conversation Handling → Message Search: uses message search (evidence: `app/controllers/ApiConversationsController.java`)
- Context Management → Configuration: reads settings (evidence: `app/agents/ContextWindowManager.java`)
- Context Compression → Configuration: reads settings (evidence: `app/agents/CompressionPipeline.java`)
- Browser And Scraping → Domain Records: persists jobs (evidence: `app/services/scrape/ScrapeJobService.java`)
- Browser And Scraping → Agent Execution: invokes agent (evidence: `app/services/scrape/ScrapeJobService.java`)
- Event Logging → Domain Records: persists event logs (evidence: `app/services/EventLogger.java`)
