System Architecture

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

​

Architecture Diagram

​

Core Components

​

Agent Loop

pub struct Agent {
    config: AgentConfig,
    deps: AgentDeps,
    channels: Arc<ChannelManager>,
    context_manager: Arc<ContextManager>,
    scheduler: Arc<Scheduler>,
    router: Router,
    session_manager: Arc<SessionManager>,
}

• Route incoming messages from channels
• Classify user intent (command vs query vs task)
• Delegate to appropriate handlers
• Coordinate session and thread management
• Trigger background systems (heartbeat, routines, self-repair)

​

Router

pub enum MessageIntent {
    Command,      // System commands (/help, /status)
    Query,        // Information requests
    Task,         // Work requiring tools/planning
    Conversation, // Chat, general interaction
}

• Commands: Direct system operations (/quit, /undo, /status)
• Queries: Information retrieval from memory or knowledge
• Tasks: Complex work requiring planning and tool execution
• Conversation: General chat and interaction

​

Scheduler

pub struct Scheduler {
    config: AgentConfig,
    context_manager: Arc<ContextManager>,
    jobs: Arc<RwLock<HashMap<Uuid, ScheduledJob>>>,
    subtasks: Arc<RwLock<HashMap<Uuid, ScheduledSubtask>>>,
}

• Parallel job execution (configurable limit)
• Per-job worker isolation
• Subtask spawning for parallel tool execution
• Automatic cleanup on completion
• Job state tracking (pending, in_progress, completed, failed, stuck)

​

Worker

pub struct Worker {
    job_id: Uuid,
    deps: WorkerDeps,
}

1. Planning (optional): Generate action plan with LLM
2. Tool Selection: Choose tools based on context
3. Parallel Execution: Run independent tools concurrently
4. Result Processing: Sanitize output, update context
5. Iteration: Loop until job complete or max iterations
6. Completion: Mark job as completed/failed/stuck

​

Routines Engine

pub enum Trigger {
    Cron(String),              // Schedule: "0 9 * * MON"
    Event { pattern: String }, // Regex: "deploy.*failed"
    Webhook { path: String },  // HTTP: /webhook/deploy
}

• Cron: Time-based schedules (daily reports, periodic checks)
• Event: Message pattern matching (alert on errors)
• Webhook: HTTP endpoint triggers (CI/CD integration)

• Daily standup summaries
• Alert monitoring and triage
• Periodic health checks
• Automated reporting

​

Orchestrator

pub struct ContainerJobManager {
    // Container lifecycle management
    // Per-job authentication tokens
    // LLM proxy for worker containers
    // Credential injection boundary
}

• Per-job bearer tokens (ephemeral, in-memory only)
• Network-isolated containers
• Resource limits (CPU, memory, timeout)
• Credential injection at orchestrator boundary
• No direct database access from containers

┌─────────────────────────────────────────────────────────┐
│                     Orchestrator                        │
│  - HTTP API (:50051)                                    │
│  - Token validation                                     │
│  - LLM proxy                                            │
│  - Credential injection                                 │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP + Bearer Token
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Docker Container (Worker)                  │
│  - Isolated filesystem                                  │
│  - Limited tools (shell, file ops)                      │
│  - No direct secrets access                             │
└─────────────────────────────────────────────────────────┘

​

Data Flow

​

Message Processing

​

Job Lifecycle

​

Self-Repair System

• Jobs stuck in InProgress beyond threshold
• Tools with high failure rates
• Unresponsive worker processes

​

Context Management

pub struct JobContext {
    pub id: Uuid,
    pub title: String,
    pub description: String,
    pub user_id: String,
    pub state: JobState,
    pub created_at: DateTime<Utc>,
    pub metadata: serde_json::Value,
}

• Each job has independent memory
• No shared mutable state between jobs
• Tool execution scoped to job context
• LLM history isolated per job

1. Detect: Monitor token count per thread
2. Summarize: Use LLM to summarize old turns
3. Preserve: Keep recent turns intact
4. Replace: Swap old turns with summary
5. Continue: Resume conversation with more tokens

​

Session Management

• Multiple concurrent threads per user
• Turn-based checkpointing
• Undo/redo with state restoration
• Session persistence to database
• Automatic pruning of stale sessions

pub struct Turn {
    pub user_input: String,
    pub assistant_response: String,
    pub tool_calls: Vec<ToolCall>,
    pub state: TurnState,
    pub created_at: DateTime<Utc>,
}

​

Performance Characteristics

​

Parallel Tool Execution

// Sequential (slow)
let result1 = execute_tool("api_call_1").await;
let result2 = execute_tool("api_call_2").await;
let result3 = execute_tool("api_call_3").await;
// Total: ~600ms

// Parallel (fast)
let results = execute_tools_parallel([
    "api_call_1",
    "api_call_2", 
    "api_call_3"
]).await;
// Total: ~200ms

​

Resource Limits

​

Next Steps