Skip to main content

Architecture Overview

inf-minds uses a layered architecture that separates concerns and enables extensibility at each level.

The Five Layers​

Layer Responsibilities​

Layer 2: Mind Runtime (@inf-minds/mindkit)​

The mind runtime handles single-agent execution:

  • LLM Integration - Connects to Claude, GPT-4, Gemini via Vercel AI SDK
  • Tool Execution - Runs tools with validated parameters
  • Event Streaming - Emits progress events (thinking, tool calls, completion)
  • Extensions - Composable capabilities (code review, security audit, etc.)
const mind = createMind({
  model: 'claude-sonnet-4-20250514',
  systemPrompt: 'You are a helpful assistant.',
  tools: [searchTool, readFileTool],
  extensions: [codeReviewExtension],
});

const output = await mind.run({
  task: 'Review this pull request',
  artifacts: [diffArtifact],
});

Layer 3: Coordination Patterns (@inf-minds/coordination-modes)​

Coordination modes define execution graphs:

  • Nodes - Which mind runs at each step
  • Edges - Transitions with optional conditions
  • Loops - Iteration with exit conditions
  • Routing - How artifacts flow between nodes
const pipeline = createPipelineMode({
  name: 'research-pipeline',
  steps: [
    { id: 'research', mind: { type: 'registered', mindType: 'researcher' } },
    { id: 'analyze', mind: { type: 'registered', mindType: 'analyst' } },
  ],
});

Layer 4: Orchestration (@inf-minds/kernel)​

The kernel orchestrates multi-mind workflows:

  • Sessions - Instances of coordination mode execution
  • Graph Execution - Evaluates conditions, advances nodes
  • Job Hierarchy - Parent session with child mind-execution jobs
  • Artifact Routing - Controls what each mind can see
const kernel = createKernel({ jobManager, eventAppender, artifactManager });

kernel.registerMind('researcher', { model: 'claude-sonnet-4-20250514', ... });
kernel.registerMode(pipeline);

const session = await kernel.createSession({
  mode: 'research-pipeline',
  input: { topic: 'AI trends' },
  accountId: 'user-123',
});

Layer 1: Execution Infrastructure​

The infrastructure layer provides persistence and distribution:

ComponentPurpose
@inf-minds/jobsJob CRUD, event sourcing, status tracking
@inf-minds/storageArtifact blob storage (PostgreSQL or R2)
@inf-minds/relay-clientWebSocket/SSE client for real-time events
workers/job-coordinatorDistributed job scheduling
workers/relayEvent streaming and worker discovery

Data Flow​

Request Flow​

1. Client creates a session via kernel
2. Kernel creates a parent job (type: kernel-session)
3. Kernel evaluates graph, creates child job for entry node
4. Job coordinator dispatches to worker
5. Worker executes mind, returns output via callback
6. Kernel advances graph, creates next child job
7. Repeat until exit node reached
8. Session completes, client receives final output

Event Flow​

Job Hierarchy​

Every session creates a hierarchy of jobs:

Deployment Architecture​

Production (Cloudflare Workers)​

Local Development​

Design Principles​

  1. Separation of Concerns - Minds handle AI logic, modes define coordination, kernel manages execution
  2. Persistence First - All state goes through PostgreSQL for reliability and observability
  3. Graph-Based Orchestration - Complex workflows as explicit, inspectable graphs
  4. Extensibility - Add new minds, modes, and routing strategies without core changes
  5. Edge-Ready - Built for Cloudflare Workers and serverless PostgreSQL

Next Steps​