# Architecture

> Foundry V2 is a parallel, safety-first industrial control plane. It enforces strict role separation: no module may cross responsibilities.

Source: https://bifrost5.com/foundry/docs/architecture/

# System Architecture

Information

Connect your own AI tool to this core through a bridge, and steer it from more places than the dashboard.

[See editions](/foundry/docs/editions)

Foundry V2 is a **parallel, safety-first industrial control plane**. It enforces strict role separation: no module may cross responsibilities.

### 1. Operator Interface

Where the human injects initial goals, tasks, and issues HALT / RESUME commands. Also available via the **UI Dashboard**. (`src/infrastructure/tooling/project-cli/cli.ts`)

### 2. Foundry Core (Scheduler + Worker Pool)

The brain. In V2, the monolithic control loop splits into two components:

- **Scheduler** (`src/application/services/scheduler/index.ts`): Orchestrates the task dependency graph (DAG). Promotes tasks from *waiting* to *ready* when dependencies are met.

- **Worker Pool** (`src/application/workers/workerPool.ts`): Pre-spawns configurable workers (default: 3) that poll the ready queue. Each worker gets its own isolated context via **git worktree** to prevent file conflicts.

### 3. Tool Dispatcher

Constructs task prompts and dispatches them to external Agents/Providers (Gemini, Copilot, Cursor, Claude). Provider selection via ProviderStrategy with circuit breaker and automatic fallback. (`src/domain/agents/promptBuilder.ts`, `src/infrastructure/connectors/agents/providers/*`)

### 4. Persistence Layer

Uses **DragonflyDB** (Redis-compatible) for read/write. State is fully overwritten on every loop, making crash recovery seamless. (`src/application/services/persistence.ts`)

### 5. Dual-Queue Adapter

V2 replaces the single FIFO queue with a **dual-queue system**:

- **Ready Queue**: Tasks with all dependencies met: polled by the Worker Pool.

- **Waiting Queue**: Tasks with unmet dependencies: checked when a task completes and auto-promoted when deps are satisfied.

### 6. Deterministic Validator

Fast, non-AI pre-checks. Uses regex, semver, and safety caps (file size, byte limits). If confidence is high, it skips expensive AI validation entirely. (`src/application/services/validator.ts`)

### 7. Safety Layer

A deterministic middleware between agents and tool execution. Includes command sanitization (blocks destructive operations like `rm -rf`, `dd`), path confinement (enforces sandbox boundaries), and read-only command whitelisting.

### 8. Helper Agent Pipeline

Only invoked on validation gaps. Helper sessions are isolated per project to save context tokens.

### Provider Strategy

Two adapters per strategy: **primary** (TaskExecutor, GoalChecker, Retry) and **secondary** (Validation helpers). Each `ProviderEntry` carries `{ provider, agentMode }`. Three built-in strategies:

- **Strategy 1** (claude-primary): Claude → Cursor → Gemini

- **Strategy 2** (cursor-primary): Cursor → Gemini → Claude

- **Strategy 3** (gemini-primary): Gemini → Claude → Cursor

Custom strategies can be created via the UI Settings page. Circuit breaker + automatic fallback per adapter independently.