How behzad62/aiboard works
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: engine.ts Client engine · build-runtime.ts Build runtime · layout.tsx App shell · provider-registry.ts Provider registry
Components 27
Browser App
Static Next.js client application.
- Next.js routes · Discussion, settings, and Build entry routes.
app/page.tsx - App shell
app/layout.tsx - Discussion UI
app/discussion/discussion-client.tsx - Settings UI
app/settings/settings-client.tsx - Client engine · Coordinates discussions, settings, attachments, and folders.
lib/client/engine.ts - Local data store · Optional client encryption protects local data.
lib/client/storage-adapter.ts - Client state
lib/client/store.ts - Build UI · Task board and Runner activity view.
app/build-mode/page.tsx - Native build client · Connects the browser to loopback Runner V2.
lib/client/native-build-engine.ts - Build contracts & gates · Plans, budgets, policies, progress, and evidence gates.
lib/orchestrator/build-plan-contract.ts
Model Providers
Normalized client-side model access.
- Provider registry · Normalizes transports and model capabilities.
lib/providers/provider-registry.ts - Provider contract
lib/providers/base.ts - Capabilities · Reasoning, tools, pricing, context, and output support.
lib/providers/capabilities.ts
Runner V2
Local native coding-agent runtime.
- Runner CLI · Launches Runner with project, state directory, port, and token.
runner-v2/src/cli.ts - Loopback control server · Accepts browser control requests only on localhost.
runner-v2/src/control-server.ts - Build runtime · Owns durable build lifecycle and recovery.
runner-v2/src/build-runtime.ts - Runner SQLite state · Stores events, sessions, specs, budgets, evidence, and memory.
runner-v2/src/sqlite-event-store.ts - Architect · Builds repository context, skills, and execution graph.
runner-v2/src/native-architect-runtime.ts - Scheduler & workers · Dispatches permissioned, budgeted model and tool loops.
runner-v2/src/task-scheduler.ts - Git workspaces · Establishes safety baseline and isolated workspaces.
runner-v2/src/workspace-manager.ts - User-controlled integration · Applies reviewed artifacts only on explicit user action.
runner-v2/src/integration-manager.ts
Evaluation & Games
Benchmarks, scoring, and deterministic games.
- Certified benchmark runner · Runs persisted model evaluation suites.
lib/benchmark/certified/run-engine.ts - Benchmark store
lib/benchmark/store.ts - Benchmark scoring
lib/benchmark/scoring/aggregate.ts - Games platform · Supports playable games and game benchmarks.
lib/games/index.ts
Other components
- Provider APIs · Hosted, account-backed, custom, and compatible model endpoints.
- Static deployment · Serves the exported browser application.
deploy/nginx/aiboard.me.conf
Connections 29
- 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