{
  "id": "page:docs-user-guide-features-architecture-overview",
  "_kind": "Page",
  "_file": "wiki/docs/user-guide/features/architecture-overview.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/user-guide/features/architecture-overview.md",
    "sourceKind": "repo-docs",
    "title": "Architecture Overview",
    "displayName": "Architecture Overview",
    "slug": "docs/user-guide/features/architecture-overview",
    "articlePath": "wiki/docs/user-guide/features/architecture-overview.md",
    "article": "\n# Architecture Overview\n\n**Version:** 1.0\n**Last Updated:** 2026-01-31\n**Category:** Feature Guide\n\n---\n\n## In Plain English\n\n**Babysitter is built in layers, like a well-organized office.**\n\nThink of it like this:\n- **The Plugin** is the receptionist - it takes your requests and routes them to the right department\n- **The SDK** is the operations team - it actually does the work\n- **The Journal** is the filing cabinet - it keeps a record of everything\n- **The AskUserQuestion Tool** is the approval desk - it pauses for human review when needed\n\n**Tip for beginners:** You don't need to understand the architecture to use Babysitter. This document is for those who want to understand how it works under the hood, or who are building custom processes.\n\n**Related:** For the conceptual model of how orchestration and AI work together, see [Two-Loops Architecture](./two-loops-architecture.md).\n\n---\n\n## Overview\n\nBabysitter uses a modular architecture designed for reliability, debuggability, and extensibility. The system combines a deterministic orchestration engine with adaptive AI capabilities, all backed by an event-sourced persistence layer.\n\n---\n\n## High-Level Architecture\n\n```\n+-----------------------------------------------------------------+\n|  Claude Code Session                                             |\n|  +-----------------------------------------------------------+  |\n|  |  Babysitter Skill (orchestrates via CLI)                  |  |\n|  +-----------------------------------------------------------+  |\n|                           |                                      |\n|                           v                                      |\n|  +-----------------------------------------------------------+  |\n|  |  .a5c/runs/<runId>/                                       |  |\n|  |  +-- run.json        (run metadata)                       |  |\n|  |  +-- inputs.json     (run inputs)                         |  |\n|  |  +-- code/           (process code)                       |  |\n|  |  +-- artifacts/      (output artifacts)                   |  |\n|  |  +-- journal/        (event log, individual JSON files)   |  |\n|  |  +-- state/state.json (current state)                     |  |\n|  |  +-- tasks/<effectId>/ (task artifacts)                   |  |\n|  +-----------------------------------------------------------+  |\n|                           |                                      |\n|                           v                                      |\n|  +-----------------------------------------------------------+  |\n|  |  AskUserQuestion Tool (human approval)                     |  |\n|  +-----------------------------------------------------------+  |\n+-----------------------------------------------------------------+\n```\n\n---\n\n## Core Components\n\n### 1. Babysitter Skill Plugin\n\n**Location:** `plugins/babysitter-unified/skills/babysit/`\n\n**Responsibilities:**\n- Parses natural language commands into process inputs\n- Orchestrates the run loop via SDK CLI\n- Manages iteration lifecycle\n- Handles resumption from saved state\n- Reports progress to Claude Code\n\n**Technology:** Claude Code Plugin System (JavaScript)\n\n---\n\n### 2. Babysitter SDK\n\n**Package:** `@a5c-ai/babysitter-sdk`\n\n**Core Modules:**\n\n| Module | Purpose | Key Functions |\n|--------|---------|--------------|\n| **Process Engine** | Executes process definitions | `runProcess()`, `iterate()` |\n| **Journal Manager** | Event-sourced persistence | `append()`, `replay()`, `getState()` |\n| **Task Executor** | Runs tasks (agent, skill, node) | `executeTask()`, `parallel.all()` |\n| **State Manager** | Maintains run state cache | `saveState()`, `loadState()` |\n| **Hook System** | Extensibility points | `registerHook()`, `trigger()` |\n\n**Technology:** Node.js, TypeScript\n\n---\n\n### 3. Event-Sourced Journal\n\n**Format:** Individual JSON files in `journal/` directory, one per event, named `{SEQ}.{ULID}.json` (e.g. `000001.01ARZ3NDEKTSV4RRFFQ69G5FAV.json`)\n\n**Event Types:**\n\n```typescript\ntype JournalEvent =\n  | { type: 'RUN_CREATED', recordedAt: string, data: { runId: string, inputs: any }, checksum: string }\n  | { type: 'EFFECT_REQUESTED', recordedAt: string, data: { effectId: string, kind: string, args: any }, checksum: string }\n  | { type: 'EFFECT_RESOLVED', recordedAt: string, data: { effectId: string, result: any }, checksum: string }\n  | { type: 'RUN_COMPLETED', recordedAt: string, data: { status: string }, checksum: string }\n  | { type: 'RUN_FAILED', recordedAt: string, data: { error: string }, checksum: string }\n\n// Note: seq is derived from the filename, not stored in the event body.\n// Breakpoints use EFFECT_REQUESTED with kind: 'breakpoint' and EFFECT_RESOLVED.\n```\n\n**Benefits:**\n- **Deterministic replay**: Reconstruct exact state at any point\n- **Audit trail**: Complete history of all actions\n- **Debugging**: Trace execution flow and identify issues\n- **Resumability**: Continue from last event after interruption\n\n**Implementation:**\n```javascript\n// Write individual JSON file per event\nfunction appendEvent(event, seq) {\n  const filename = `${String(seq).padStart(6, '0')}.${ulid()}.json`;\n  fs.writeFileSync(path.join(journalDir, filename), JSON.stringify(event, null, 2));\n}\n\n// Replay by reading all JSON files from journal/ directory\nfunction replayJournal() {\n  const files = fs.readdirSync(journalDir)\n    .filter(f => f.endsWith('.json'))\n    .sort(); // lexicographic sort preserves sequence order\n\n  const events = files.map(f =>\n    JSON.parse(fs.readFileSync(path.join(journalDir, f), 'utf-8'))\n  );\n\n  return events.reduce(applyEvent, initialState);\n}\n```\n\nFor more details on the journal system, see [Journal System](./journal-system.md).\n\n---\n\n### 4. Process Definitions\n\n**Format:** JavaScript/TypeScript functions\n\n**Execution Model:**\n\n```\n+----------------------------------------------------------+\n| Process Definition (JavaScript)                          |\n|                                                          |\n|  export async function process(inputs, ctx) {           |\n|    // User-defined orchestration logic                  |\n|    const result = await ctx.task(someTask, args);       |\n|    await ctx.breakpoint({ question: '...' });           |\n|    return result;                                        |\n|  }                                                       |\n+----------------------------------------------------------+\n                          |\n                          v\n+----------------------------------------------------------+\n| Context API (ctx)                                        |\n|                                                          |\n|  - ctx.task(task, args, opts)       Execute task        |\n|  - ctx.breakpoint(opts)             Wait for approval   |\n|    Returns BreakpointResult: { approved, feedback, ... }|\n|  - ctx.parallel.all([...])          Run in parallel     |\n|  - ctx.hook(name, data)             Trigger hooks       |\n|  - ctx.log(msg, data)               Log to journal      |\n|  - ctx.getState(key)                Access state        |\n|  - ctx.setState(key, value)         Update state        |\n+----------------------------------------------------------+\n```\n\n**Process Lifecycle:**\n\n1. **Load**: Process definition loaded from file or default\n2. **Initialize**: Context created with state and journal access\n3. **Execute**: Process function called with inputs and context\n4. **Iterate**: Process may loop internally or be called multiple times\n5. **Complete**: Process returns final result\n\nFor more details on creating processes, see [Process Definitions](./process-definitions.md).\n\n---\n\n### 5. Task Execution System\n\n**Task Types:**\n\n| Type | Executor | Use Case | Example |\n|------|----------|----------|---------|\n| **Agent** | LLM API | Planning, analysis, scoring | GPT-4, Claude |\n| **Skill** | Claude Code | Code operations | Refactoring, search |\n| **Node** | Node.js | Scripts and tools | Build, test, deploy |\n| **Shell** | System shell | Commands | git, npm, docker |\n\n**Execution Flow:**\n\n```\n+---------------------------------------------------------+\n| Task Request                                            |\n| ctx.task(taskDef, args, opts)                           |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Task Validation                                         |\n| - Validate arguments                                    |\n| - Check dependencies                                    |\n| - Generate task ID                                      |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Journal Event: EFFECT_REQUESTED                         |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Execute Task                                            |\n| - Agent: Call LLM API                                   |\n| - Skill: Invoke Claude Code skill                       |\n| - Node: Run JavaScript function                         |\n| - Shell: Execute command                                |\n| - Breakpoint: Wait for approval (kind: breakpoint)      |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Journal Event: EFFECT_RESOLVED                          |\n+-----------------+---------------------------------------+\n                  |\n                  v\n+---------------------------------------------------------+\n| Return Result                                           |\n| - Success: Return task output                           |\n| - Failure: Throw error or return error object           |\n+---------------------------------------------------------+\n```\n\n**Parallel Execution:**\n\n```javascript\n// Tasks run concurrently with Promise.all\nawait ctx.parallel.all([\n  () => ctx.task(task1, args1),\n  () => ctx.task(task2, args2),\n  () => ctx.task(task3, args3)\n]);\n\n// All results returned when all complete\n// If any fails, entire parallel group fails\n```\n\nFor more details on parallel execution, see [Parallel Execution](./parallel-execution.md).\n\n---\n\n## Data Flow\n\n**Complete Request Flow:**\n\n```\n1. User Command\n   |\n   +--> Claude Code\n        |\n        +--> Babysitter Skill\n             |\n             +-- Parse intent\n             +-- Load/create run\n             +--> CLI: npx -y @a5c-ai/babysitter@latest run:iterate\n                  |\n                  +--> SDK Process Engine\n                       |\n                       +-- Load process definition\n                       +-- Replay journal -> restore state\n                       +-- Execute process function\n                       |    |\n                       |    +-- ctx.task() -> Execute tasks\n                       |    |    |\n                       |    |    +-- Append EFFECT_REQUESTED\n                       |    |    +-- Run executor (agent/skill/node/shell)\n                       |    |    +-- Append EFFECT_RESOLVED\n                       |    |\n                       |    +--> ctx.breakpoint() -> Wait for approval\n                       |         |\n                       |         +-- Append EFFECT_REQUESTED (kind: breakpoint)\n                       |         +-- Poll for response\n                       |         +-- Append EFFECT_RESOLVED\n                       |\n                       +-- Append iteration events to journal\n                       +-- Save state cache\n                       +--> Return results to skill\n                            |\n                            +--> Report to Claude Code\n                                 |\n                                 +--> Display to user\n```\n\n---\n\n## State Management\n\n**Two-Layer State System:**\n\n1. **Journal (source of truth)**:\n   - Append-only event log\n   - Immutable history\n   - Replayed to reconstruct state\n\n2. **State Cache (performance)**:\n   - Snapshot of current state\n   - Rebuilt from journal if missing\n   - Fast access without replay\n\n**State Structure:**\n\n```typescript\ninterface RunState {\n  runId: string;\n  status: 'running' | 'paused' | 'completed' | 'failed';\n  iteration: number;\n  inputs: any;\n  outputs?: any;\n  processState: Map<string, any>;  // Process-specific state\n  taskResults: Map<string, any>;    // Cached task results\n  metrics: {\n    startTime: number;\n    endTime?: number;\n    iterations: number;\n    qualityScores: number[];\n  };\n}\n```\n\n---\n\n## Extensibility\n\n**Hook System:**\n\n```javascript\n// Register custom hooks\nctx.hook('task:completed', async (taskResult) => {\n  await sendMetricsToDatadog(taskResult);\n});\n\nctx.hook('quality:score', async (score) => {\n  if (score < 70) {\n    await sendAlert('Low quality score');\n  }\n});\n\n// Built-in hook points\n- 'run:started'\n- 'run:completed'\n- 'iteration:started'\n- 'iteration:completed'\n- 'task:started'\n- 'task:completed'\n- 'breakpoint:requested'\n- 'breakpoint:resolved'\n- 'quality:score'\n```\n\n**Custom Task Types:**\n\n```javascript\n// Define custom task executor\nfunction registerCustomTask(type, executor) {\n  taskExecutors.set(type, executor);\n}\n\n// Use custom task\nawait ctx.task({ type: 'custom', fn: myExecutor }, args);\n```\n\nFor more details on hooks, see [Hooks](./hooks.md).\n\n---\n\n## Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|-----------|---------|\n| **Plugin** | JavaScript | Claude Code integration |\n| **SDK** | TypeScript + Node.js | Core orchestration engine |\n| **Process Definitions** | JavaScript/TypeScript | User workflow logic |\n| **Journal** | Individual JSON files | Event persistence |\n| **CLI** | Commander.js | Command-line interface |\n\n---\n\n## Design Patterns\n\n**Event Sourcing:**\n- All state changes recorded as events\n- State derived from event replay\n- Time-travel debugging possible\n\n**Command Query Responsibility Segregation (CQRS):**\n- Write: Append events to journal\n- Read: Query state cache or replay\n\n**Saga Pattern:**\n- Long-running workflows with compensation\n- Breakpoints as decision points\n- Resumable across sessions\n\n**Plugin Architecture:**\n- Extensible via hooks\n- Custom task types\n- Process definitions as plugins\n\n---\n\n## Related Documentation\n\n- [Two-Loops Architecture](./two-loops-architecture.md) - Conceptual model of orchestration and AI loops\n- [Process Definitions](./process-definitions.md) - Creating custom processes\n- [Journal System](./journal-system.md) - Event sourcing and replay\n- [Breakpoints](./breakpoints.md) - Human-in-the-loop approval\n- [Parallel Execution](./parallel-execution.md) - Running tasks concurrently\n- [Hooks](./hooks.md) - Extensibility and custom integrations\n\n---\n\n## Summary\n\nBabysitter's architecture is built on these key principles:\n\n- **Modular Design**: Each component has a clear, single responsibility\n- **Event Sourcing**: The journal provides a complete, replayable audit trail\n- **Two-Layer State**: Journal for truth, cache for performance\n- **Extensibility**: Hooks and custom tasks enable integration with any system\n- **Human-in-the-Loop**: Breakpoints enables approval workflows\n\nThis architecture enables reliable, debuggable, and auditable AI-powered workflows that can be paused, resumed, and replayed at any point.\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-user-guide-features",
      "to": "page:docs-user-guide-features-architecture-overview",
      "kind": "contains_page"
    }
  ]
}