# behzad62/aiboard architecture

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

- Interactive diagram: https://gitdiagram.com/behzad62/aiboard
- Repository: https://github.com/behzad62/aiboard

## Overview

#### Purpose and Runtime Split
AI Board is a local-first, static Next.js application for multi-model AI discussions, benchmarks, games, and a native coding-agent Build mode. Browser features run without a backend; Build mode requires the local Runner V2 process. Web entry routes start at `app/page.tsx`, are wrapped by `app/layout.tsx`, and expose Build at `app/build-mode/page.tsx`.

#### Browser Application and Local Persistence
Client-side discussion, settings, provider setup, attachments, and project-folder access are coordinated through the browser client layer. Data stays in IndexedDB or a user-selected folder, with optional client encryption; provider calls are direct from the client to configured services. Key boundaries: `lib/client/store.ts`, `lib/client/engine.ts`, `lib/client/storage-adapter.ts`; UI entry points include `app/discussion/discussion-client.tsx` and `app/settings/settings-client.tsx`.

#### Provider Abstraction
A provider registry normalizes hosted, account-backed, custom, and OpenAI-compatible model transports, plus capabilities such as reasoning, structured output, web search, pricing, and context formats. UI/model workflows should depend on this layer rather than vendor implementations. Core paths: `lib/providers/provider-registry.ts`, `lib/providers/base.ts`, `lib/providers/capabilities.ts`; concrete integrations include `lib/providers/anthropic.ts`, `lib/providers/openai.ts`, and `lib/providers/google.ts`.

#### Build Mode Control Plane
The browser Build UI connects to Runner V2 over a loopback control endpoint, sending configuration and receiving durable activity, usage, and build state. The legacy/browser orchestration interfaces are separate from the native path. Relevant integration paths: `lib/client/runner-v2.ts`, `lib/client/native-build-engine.ts`, `components/RunnerV2ObservabilityPanel.tsx`, and `components/BuildTaskBoard.tsx`.

#### Runner V2: Durable Native Agent Kernel
Runner V2 is a separate Node runtime, launched by its CLI with a project, external state directory, localhost port, and control token. Its control server authenticates browser requests; persistent stores retain events, sessions, build specs, budgets, evidence, scheduling, and project memory, principally in SQLite. Primary entry and boundaries: `runner-v2/src/cli.ts`, `runner-v2/src/control-server.ts`, `runner-v2/src/build-runtime.ts`, `runner-v2/src/sqlite-event-store.ts`.

#### Native Build Execution Pipeline
A build initializes Git safety/baseline and isolated workspaces, assembles repository context and skills, then runs an Architect that derives a task graph. The scheduler dispatches workers; their model/tool loops are constrained by permissions, budgets, tool ledgers, and access policy. Evidence and artifacts support review and recovery; integration/handoff is explicitly user-controlled. Core paths: `runner-v2/src/native-architect-runtime.ts`, `runner-v2/src/task-scheduler.ts`, `runner-v2/src/worker-runtime.ts`, `runner-v2/src/workspace-manager.ts`, `runner-v2/src/integration-manager.ts`.

#### Orchestration Contracts and Evidence Gates
Shared app-side orchestration defines plan contracts, task phases, worker/architect budgets, policies, progress, quality/evidence gates, stop diagnostics, and tool review reports. This is the policy/model boundary consumed by Build UI and native execution design. Paths: `lib/orchestrator/build-plan-contract.ts`, `lib/orchestrator/build-policy.ts`, `lib/orchestrator/build-evidence-gates.ts`, `lib/orchestrator/build-quality-gates.ts`.

#### Evaluation and Game Platforms
The benchmark subsystem runs and persists certified model evaluations across build/workbench, tool reliability, TeamIQ, GameIQ, and Fireworks suites, then aggregates reports and scoring for the benchmark UI. Separately, deterministic game engines and AI adapters support playable games and game benchmarks. Paths: `lib/benchmark/certified/run-engine.ts`, `lib/benchmark/store.ts`, `lib/benchmark/scoring/aggregate.ts`; game boundaries: `lib/games/index.ts`, `lib/games/core/session-store.ts`, `components/games/benchmark/useGamesBenchmarkRunner.ts`.

#### Deployment and External Dependencies
The web app is statically exported to `out/` and can be served by Nginx (`deploy/nginx/aiboard.me.conf`). It requires Node.js 24.18+, while Build mode additionally requires Git. External services are model-provider APIs and optional account-provider transports; Runner V2 only binds to `127.0.0.1` and encrypts its provider configuration with the control token.

Main entry points: [`lib/client/engine.ts`](https://github.com/behzad62/aiboard/blob/main/lib/client/engine.ts) (Client engine), [`runner-v2/src/build-runtime.ts`](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/build-runtime.ts) (Build runtime), [`app/layout.tsx`](https://github.com/behzad62/aiboard/blob/main/app/layout.tsx) (App shell), [`lib/providers/provider-registry.ts`](https://github.com/behzad62/aiboard/blob/main/lib/providers/provider-registry.ts) (Provider registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser App"]
  node_next_routes["Next.js routes<br/>web entry<br/>[page.tsx]"]
  node_app_shell["App shell<br/>layout<br/>[layout.tsx]"]
  node_discussion_ui["Discussion UI<br/>client UI"]
  node_settings_ui["Settings UI<br/>client UI"]
  node_browser_engine["Client engine<br/>browser orchestration<br/>[engine.ts]"]
  node_local_store[("Local data store<br/>IndexedDB/folder storage<br/>[storage-adapter.ts]")]
  node_client_state["Client state<br/>state store<br/>[store.ts]"]
  node_build_ui["Build UI<br/>client UI<br/>[page.tsx]"]
  node_native_build_client["Native build client<br/>Runner control client"]
  node_build_contracts["Build contracts &amp; gates<br/>shared policy model"]
end

subgraph group_providers["Model Providers"]
  node_provider_registry{{"Provider registry<br/>provider abstraction"}}
  node_provider_contract["Provider contract<br/>provider interface<br/>[base.ts]"]
  node_provider_capabilities["Capabilities<br/>model metadata<br/>[capabilities.ts]"]
end

subgraph group_runner["Runner V2"]
  node_runner_cli["Runner CLI<br/>native entrypoint<br/>[cli.ts]"]
  node_control_server{{"Loopback control server<br/>authenticated API<br/>[control-server.ts]"}}
  node_build_runtime["Build runtime<br/>agent kernel<br/>[build-runtime.ts]"]
  node_runner_sqlite[("Runner SQLite state<br/>durable event store")]
  node_architect["Architect<br/>task graph planner"]
  node_scheduler_workers["Scheduler &amp; workers<br/>native execution<br/>[task-scheduler.ts]"]
  node_workspaces["Git workspaces<br/>isolated workspace manager"]
  node_integration["User-controlled integration<br/>handoff manager"]
end

subgraph group_evaluation["Evaluation &amp; Games"]
  node_benchmark_engine["Certified benchmark runner<br/>evaluation engine<br/>[run-engine.ts]"]
  node_benchmark_store[("Benchmark store<br/>evaluation persistence<br/>[store.ts]")]
  node_benchmark_scoring["Benchmark scoring<br/>report aggregation<br/>[aggregate.ts]"]
  node_games["Games platform<br/>deterministic game engine<br/>[index.ts]"]
end

node_provider_apis(("Provider APIs<br/>external services"))
node_static_deploy["Static deployment<br/>Nginx-served export<br/>[aiboard.me.conf]"]

node_next_routes -->|"wrapped by"| node_app_shell
node_app_shell -->|"renders"| node_discussion_ui
node_app_shell -->|"renders"| node_settings_ui
node_app_shell -->|"renders"| node_build_ui
node_discussion_ui -->|"uses"| node_browser_engine
node_settings_ui -->|"uses"| node_browser_engine
node_browser_engine -->|"updates"| node_client_state
node_browser_engine -->|"persists locally"| node_local_store
node_browser_engine -->|"requests models through"| node_provider_registry
node_provider_registry -->|"implements"| node_provider_contract
node_provider_registry -->|"exposes"| node_provider_capabilities
node_provider_registry -->|"calls directly"| node_provider_apis
node_build_ui -->|"controls"| node_native_build_client
node_build_ui -->|"uses plans and gates"| node_build_contracts
node_native_build_client -->|"loopback control"| node_control_server
node_runner_cli -->|"starts"| node_control_server
node_control_server -->|"commands and activity"| node_build_runtime
node_build_runtime -->|"persists"| node_runner_sqlite
node_build_runtime -->|"prepares baseline"| node_workspaces
node_build_runtime -->|"plans build"| node_architect
node_architect -->|"produces task graph"| node_scheduler_workers
node_scheduler_workers -->|"executes in"| node_workspaces
node_scheduler_workers -->|"records evidence"| node_runner_sqlite
node_scheduler_workers -->|"produces handoff"| node_integration
node_build_contracts -.->|"policy boundary"| node_build_runtime
node_benchmark_engine -->|"persists runs"| node_benchmark_store
node_benchmark_store -->|"feeds reports"| node_benchmark_scoring
node_games -->|"supplies game benchmarks"| node_benchmark_engine
node_next_routes -->|"exported and served"| node_static_deploy

click node_next_routes "https://github.com/behzad62/aiboard/blob/main/app/page.tsx"
click node_app_shell "https://github.com/behzad62/aiboard/blob/main/app/layout.tsx"
click node_discussion_ui "https://github.com/behzad62/aiboard/blob/main/app/discussion/discussion-client.tsx"
click node_settings_ui "https://github.com/behzad62/aiboard/blob/main/app/settings/settings-client.tsx"
click node_browser_engine "https://github.com/behzad62/aiboard/blob/main/lib/client/engine.ts"
click node_local_store "https://github.com/behzad62/aiboard/blob/main/lib/client/storage-adapter.ts"
click node_client_state "https://github.com/behzad62/aiboard/blob/main/lib/client/store.ts"
click node_build_ui "https://github.com/behzad62/aiboard/blob/main/app/build-mode/page.tsx"
click node_native_build_client "https://github.com/behzad62/aiboard/blob/main/lib/client/native-build-engine.ts"
click node_provider_registry "https://github.com/behzad62/aiboard/blob/main/lib/providers/provider-registry.ts"
click node_provider_contract "https://github.com/behzad62/aiboard/blob/main/lib/providers/base.ts"
click node_provider_capabilities "https://github.com/behzad62/aiboard/blob/main/lib/providers/capabilities.ts"
click node_build_contracts "https://github.com/behzad62/aiboard/blob/main/lib/orchestrator/build-plan-contract.ts"
click node_runner_cli "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/cli.ts"
click node_control_server "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/control-server.ts"
click node_build_runtime "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/build-runtime.ts"
click node_runner_sqlite "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/sqlite-event-store.ts"
click node_architect "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/native-architect-runtime.ts"
click node_scheduler_workers "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/task-scheduler.ts"
click node_workspaces "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/workspace-manager.ts"
click node_integration "https://github.com/behzad62/aiboard/blob/main/runner-v2/src/integration-manager.ts"
click node_benchmark_engine "https://github.com/behzad62/aiboard/blob/main/lib/benchmark/certified/run-engine.ts"
click node_benchmark_store "https://github.com/behzad62/aiboard/blob/main/lib/benchmark/store.ts"
click node_benchmark_scoring "https://github.com/behzad62/aiboard/blob/main/lib/benchmark/scoring/aggregate.ts"
click node_games "https://github.com/behzad62/aiboard/blob/main/lib/games/index.ts"
click node_static_deploy "https://github.com/behzad62/aiboard/blob/main/deploy/nginx/aiboard.me.conf"

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_next_routes,node_app_shell,node_discussion_ui,node_settings_ui,node_browser_engine,node_local_store,node_client_state,node_build_ui,node_native_build_client,node_build_contracts toneBlue
class node_provider_registry,node_provider_contract,node_provider_capabilities toneAmber
class node_runner_cli,node_control_server,node_build_runtime,node_runner_sqlite,node_architect,node_scheduler_workers,node_workspaces,node_integration toneMint
class node_benchmark_engine,node_benchmark_store,node_benchmark_scoring,node_games toneRose
class node_provider_apis,node_static_deploy toneNeutral
```

## Components

### Browser App

Static Next.js client application.

- [Next.js routes](https://github.com/behzad62/aiboard/blob/main/app/page.tsx): web entry · Discussion, settings, and Build entry routes. · `app/page.tsx`
- [App shell](https://github.com/behzad62/aiboard/blob/main/app/layout.tsx): layout · `app/layout.tsx`
- [Discussion UI](https://github.com/behzad62/aiboard/blob/main/app/discussion/discussion-client.tsx): client UI · `app/discussion/discussion-client.tsx`
- [Settings UI](https://github.com/behzad62/aiboard/blob/main/app/settings/settings-client.tsx): client UI · `app/settings/settings-client.tsx`
- [Client engine](https://github.com/behzad62/aiboard/blob/main/lib/client/engine.ts): browser orchestration · Coordinates discussions, settings, attachments, and folders. · `lib/client/engine.ts`
- [Local data store](https://github.com/behzad62/aiboard/blob/main/lib/client/storage-adapter.ts): IndexedDB/folder storage · Optional client encryption protects local data. · `lib/client/storage-adapter.ts`
- [Client state](https://github.com/behzad62/aiboard/blob/main/lib/client/store.ts): state store · `lib/client/store.ts`
- [Build UI](https://github.com/behzad62/aiboard/blob/main/app/build-mode/page.tsx): client UI · Task board and Runner activity view. · `app/build-mode/page.tsx`
- [Native build client](https://github.com/behzad62/aiboard/blob/main/lib/client/native-build-engine.ts): Runner control client · Connects the browser to loopback Runner V2. · `lib/client/native-build-engine.ts`
- [Build contracts & gates](https://github.com/behzad62/aiboard/blob/main/lib/orchestrator/build-plan-contract.ts): shared policy model · Plans, budgets, policies, progress, and evidence gates. · `lib/orchestrator/build-plan-contract.ts`

### Model Providers

Normalized client-side model access.

- [Provider registry](https://github.com/behzad62/aiboard/blob/main/lib/providers/provider-registry.ts): provider abstraction · Normalizes transports and model capabilities. · `lib/providers/provider-registry.ts`
- [Provider contract](https://github.com/behzad62/aiboard/blob/main/lib/providers/base.ts): provider interface · `lib/providers/base.ts`
- [Capabilities](https://github.com/behzad62/aiboard/blob/main/lib/providers/capabilities.ts): model metadata · Reasoning, tools, pricing, context, and output support. · `lib/providers/capabilities.ts`

### Runner V2

Local native coding-agent runtime.

- [Runner CLI](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/cli.ts): native entrypoint · Launches Runner with project, state directory, port, and token. · `runner-v2/src/cli.ts`
- [Loopback control server](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/control-server.ts): authenticated API · Accepts browser control requests only on localhost. · `runner-v2/src/control-server.ts`
- [Build runtime](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/build-runtime.ts): agent kernel · Owns durable build lifecycle and recovery. · `runner-v2/src/build-runtime.ts`
- [Runner SQLite state](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/sqlite-event-store.ts): durable event store · Stores events, sessions, specs, budgets, evidence, and memory. · `runner-v2/src/sqlite-event-store.ts`
- [Architect](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/native-architect-runtime.ts): task graph planner · Builds repository context, skills, and execution graph. · `runner-v2/src/native-architect-runtime.ts`
- [Scheduler & workers](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/task-scheduler.ts): native execution · Dispatches permissioned, budgeted model and tool loops. · `runner-v2/src/task-scheduler.ts`
- [Git workspaces](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/workspace-manager.ts): isolated workspace manager · Establishes safety baseline and isolated workspaces. · `runner-v2/src/workspace-manager.ts`
- [User-controlled integration](https://github.com/behzad62/aiboard/blob/main/runner-v2/src/integration-manager.ts): handoff manager · Applies reviewed artifacts only on explicit user action. · `runner-v2/src/integration-manager.ts`

### Evaluation & Games

Benchmarks, scoring, and deterministic games.

- [Certified benchmark runner](https://github.com/behzad62/aiboard/blob/main/lib/benchmark/certified/run-engine.ts): evaluation engine · Runs persisted model evaluation suites. · `lib/benchmark/certified/run-engine.ts`
- [Benchmark store](https://github.com/behzad62/aiboard/blob/main/lib/benchmark/store.ts): evaluation persistence · `lib/benchmark/store.ts`
- [Benchmark scoring](https://github.com/behzad62/aiboard/blob/main/lib/benchmark/scoring/aggregate.ts): report aggregation · `lib/benchmark/scoring/aggregate.ts`
- [Games platform](https://github.com/behzad62/aiboard/blob/main/lib/games/index.ts): deterministic game engine · Supports playable games and game benchmarks. · `lib/games/index.ts`

### Other components

- **Provider APIs**: external services · Hosted, account-backed, custom, and compatible model endpoints.
- [Static deployment](https://github.com/behzad62/aiboard/blob/main/deploy/nginx/aiboard.me.conf): Nginx-served export · Serves the exported browser application. · `deploy/nginx/aiboard.me.conf`

## Connections

- Next.js routes → App shell: wrapped by
- App shell → Discussion UI: renders
- App shell → Settings UI: renders
- App shell → Build UI: renders
- Discussion UI → Client engine: uses
- Settings UI → Client engine: uses
- Client engine → Client state: updates
- Client engine → Local data store: persists locally
- Client engine → Provider registry: requests models through
- Provider registry → Provider contract: implements
- Provider registry → Capabilities: exposes
- Provider registry → Provider APIs: calls directly
- Build UI → Native build client: controls
- Build UI → Build contracts & gates: uses plans and gates
- Native build client → Loopback control server: loopback control
- Runner CLI → Loopback control server: starts
- Loopback control server → Build runtime: commands and activity
- Build runtime → Runner SQLite state: persists
- Build runtime → Git workspaces: prepares baseline
- Build runtime → Architect: plans build
- Architect → Scheduler & workers: produces task graph
- Scheduler & workers → Git workspaces: executes in
- Scheduler & workers → Runner SQLite state: records evidence
- Scheduler & workers → User-controlled integration: produces handoff
- Build contracts & gates → Build runtime: policy boundary
- Certified benchmark runner → Benchmark store: persists runs
- Benchmark store → Benchmark scoring: feeds reports
- Games platform → Certified benchmark runner: supplies game benchmarks
- Next.js routes → Static deployment: exported and served