# gembacore/gemba-core architecture

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

- Interactive diagram: https://gitdiagram.com/gembacore/gemba-core
- Repository: https://github.com/gembacore/gemba-core

## Overview

1. **Product shape: one Go binary plus an embedded SPA.**  
   Gemba is delivered as a single server executable (`cmd/gemba`) that serves a React/Vite frontend from embedded assets and exposes the application API. The browser UI is not a separate backend: it is the presentation layer on top of the Go control plane.

2. **Two-plane architecture is the main boundary.**  
   The core abstraction is split into a required **WorkPlane** and an optional **OrchestrationPlane**.  
   - The **WorkPlane** provides the actual work data: beads/work items, milestones, evidence, state, and history.  
   - The **OrchestrationPlane** provides agent/session execution: starting sessions, dispatching work, handling escalations, and surfacing human-in-the-loop prompts.  
   A deployment can run with WorkPlane only, but it cannot run without one.

3. **Server layer is the coordination hub.**  
   `internal/server` owns the HTTP router, route handlers, OpenAPI surface, and cross-cutting concerns like auth, quotas, readiness/health, SSE streams, and workspace/project management. It is the main integration point between the frontend and all adaptors.

4. **Advisory vs execution data flows are kept separate.**  
   The UI and API contain both planning and execution surfaces, but the system treats them differently:  
   - **Selection** is runtime dispatch scoring for ready beads.  
   - **epic_order** is planning-time ranking used by the PM persona to compose sprint recommendations.  
   This distinction matters in the architecture because one feeds session dispatch, while the other feeds higher-level planning workflows.

5. **Adapter implementations are the real backend variation point.**  
   `internal/adapter/*` contains concrete backends for each plane. The important ones are:  
   - **`bd`**: Beads-backed WorkPlane, including CLI and direct Dolt SQL modes.  
   - **`native`**: default OrchestrationPlane, using local terminal backends such as tmux, iTerm2, or Terminal.app.  
   - **`gt`**: Gas Town orchestration integration.  
   - **`mock`/`noop`**: test and reference implementations.  
   These adapters isolate vendor/runtime-specific behavior from the shared product logic.

6. **The native execution path is a full session lifecycle pipeline.**  
   In native mode, a bead moved into active work can trigger: worktree provisioning, bridge installation, terminal session spawn, prompt/preamble injection, and live prompt/approval feedback back into the SPA. The `gemba-bridge`, `gemba-state`, `gemba-ask`, and `gemba-mcp` CLIs are part of this execution loop, not just tooling.

7. **Real-time updates are event-driven.**  
   `internal/events` provides the SSE hub, schema translation, and tracing/logging support. The frontend subscribes to these streams to show live session state, escalations, work-item changes, and other state transitions without polling as the primary mechanism.

8. **State is spread across several bounded stores.**  
   Persistent state is not centralized in one database model. Instead it is divided by concern:  
   - WorkPlane data in Beads/Dolt-backed storage  
   - planner state under `internal/planner`  
   - sessions and walks under `internal/walk`  
   - auth/tokens under `internal/auth`  
   - workspace/project metadata under `internal/workspaces` and related server packages  
   This separation is important for diagrams because the product’s runtime reads from multiple stores with different ownership and lifecycles.

9. **Planning and refinement are first-class subsystems.**  
   `internal/planner`, `internal/concepts`, `internal/spec`, and `internal/skills` implement the product’s higher-level workflow: project bootstrap, spec parsing, drift analysis, dispatch policy, pool sizing, retro/health logic, and spec reconciliation. These systems sit above the raw work tracker and decide how intent becomes bead structure and execution order.

10. **Spec-driven development is integrated, not external.**  
   The repo includes a full spec workflow: scaffold, lint, diff, snapshot, apply, reconcile, and hook enforcement. Spec Kit integration is treated as a product feature, with guards that prevent unmanaged edits and routes planning intent into the bead-backed work plane.

11. **The frontend is organized around task-centric pages, not generic CRUD.**  
   The SPA is split into surfaces such as Board, Refine, Sessions, Sprints, Agent Groups, Insights, Walk, and Project Config. Components are further segmented by workflow: board cards and hierarchy, right-hand detail panels, session and escalation views, project picker/setup, pool editor, and walk/coach experiences. Capability gating is used so the UI only exposes features supported by the current adaptor set.

12. **Transport is multi-protocol, but API is primary.**  
   `internal/transport` provides hosts for API, JSONL, and MCP-style access. The API surface is the main contract for the SPA and external tools; the other transports are for adaptor integrations and agent tooling.

13. **Security and deployment are wrapper concerns around the core app.**  
   Authentication supports cookies, tokens, OIDC-style flows, TLS, and bootstrap/login paths. Deployment targets include local binary, Docker, systemd, and a VM image. These are important operational layers, but they do not change the central runtime architecture: server + adaptors + SPA.

14. **Testing is architecture-representative.**  
   The repo includes extensive unit, integration, and Playwright E2E coverage, plus a reusable `testing/` harness for adaptor conformance and workflow regression. That indicates the boundaries are intentionally enforced at the plane/adaptor level, not only at the UI or API level.

15. **A diagram should center on three flows.**  
   The main diagrammatic story is:  
   - **User/browser → Go server/API/SSE → frontend state surfaces**  
   - **Go server → WorkPlane adaptor → persistent work data**  
   - **Go server → OrchestrationPlane adaptor → agent sessions / terminal runtimes**  
   Around those, the planner/spec/auth/eventing subsystems provide policy, lifecycle, and observability.

Main entry points: [`internal/server/doc.go`](https://github.com/gembacore/gemba-core/blob/main/internal/server/doc.go) (Server), [`internal/planner/doc.go`](https://github.com/gembacore/gemba-core/blob/main/internal/planner/doc.go) (Planner), [`internal/adapter/registry/registry.go`](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/registry/registry.go) (Adapters), [`internal/adapter/native/orchestration.go`](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/native/orchestration.go) (Native adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_cmd_gemba["gemba<br/>server binary<br/>[main.go]"]
end

subgraph group_backend["Backend"]
  node_server["Server<br/>http control plane<br/>[doc.go]"]
  node_events(("Events<br/>sse hub<br/>[hub.go]"))
  node_adapters["Adapters<br/>backend registry<br/>[registry.go]"]
  node_bd_adapter[("BD adapter<br/>workplane adapter<br/>[workplane.go]")]
  node_native_adapter["Native adapter<br/>orchestration adapter<br/>[orchestration.go]"]
  node_gt_adapter["GT adapter<br/>orchestration adapter<br/>[sessions.go]"]
  node_auth["Auth<br/>security layer<br/>[doc.go]"]
  node_core["Core<br/>shared domain<br/>[doc.go]"]
end

subgraph group_product["Product logic"]
  node_planner["Planner<br/>workflow policy<br/>[doc.go]"]
  node_selection{{"Selection<br/>runtime scoring<br/>[selection.go]"}}
  node_epic_order{{"Epic order<br/>planning ranking<br/>[skill.go]"}}
  node_spec["Spec<br/>[apply.go]"]
  node_walk["Walk<br/>session model<br/>[doc.go]"]
  node_workspaces[("Workspaces<br/>workspace metadata<br/>[registry.go]")]
  node_skills["Skills<br/>[doc.go]"]
  node_concepts["Concepts<br/>bootstrap + drift<br/>[doc.go]"]
end

subgraph group_frontend["Frontend"]
  node_web_spa["SPA<br/>embedded frontend<br/>[main.tsx]"]
end

subgraph group_tooling["Tooling"]
  node_transport["Transport<br/>multi-protocol host<br/>[doc.go]"]
  node_cli["CLI<br/>user tooling<br/>[doc.go]"]
end

node_cmd_gemba -->|"starts"| node_server
node_cmd_gemba -->|"embeds"| node_web_spa
node_server -->|"secures"| node_auth
node_server -->|"streams"| node_events
node_server -->|"exports"| node_transport
node_server -->|"selects"| node_adapters
node_server -->|"manages"| node_workspaces
node_server -->|"coordinates"| node_planner
node_server -->|"serves"| node_spec
node_server -->|"serves"| node_walk
node_server -->|"uses"| node_core
node_web_spa -->|"calls API"| node_server
node_web_spa -->|"subscribes"| node_events
node_adapters -->|"includes"| node_bd_adapter
node_adapters -->|"includes"| node_native_adapter
node_adapters -->|"includes"| node_gt_adapter
node_planner -->|"scores"| node_selection
node_planner -->|"ranks"| node_epic_order
node_planner -->|"refines"| node_concepts
node_planner -->|"applies"| node_skills
node_spec -->|"writes beads"| node_bd_adapter
node_spec -->|"guards intent"| node_planner
node_walk -->|"drives sessions"| node_native_adapter
node_native_adapter -->|"emits"| node_events
node_native_adapter -->|"activates work"| node_bd_adapter
node_native_adapter -->|"implements"| node_core
node_transport -->|"hosts"| node_server
node_cli -->|"operates"| node_server
node_cli -->|"runs"| node_spec
node_cli -->|"inspects"| node_planner
node_cli -->|"conforms to"| node_adapters

click node_cmd_gemba "https://github.com/gembacore/gemba-core/blob/main/cmd/gemba/main.go"
click node_web_spa "https://github.com/gembacore/gemba-core/blob/main/web/src/main.tsx"
click node_server "https://github.com/gembacore/gemba-core/blob/main/internal/server/doc.go"
click node_events "https://github.com/gembacore/gemba-core/blob/main/internal/events/hub.go"
click node_adapters "https://github.com/gembacore/gemba-core/blob/main/internal/adapter/registry/registry.go"
click node_bd_adapter "https://github.com/gembacore/gemba-core/blob/main/internal/adapter/bd/workplane.go"
click node_native_adapter "https://github.com/gembacore/gemba-core/blob/main/internal/adapter/native/orchestration.go"
click node_gt_adapter "https://github.com/gembacore/gemba-core/blob/main/internal/adapter/gt/sessions.go"
click node_planner "https://github.com/gembacore/gemba-core/blob/main/internal/planner/doc.go"
click node_selection "https://github.com/gembacore/gemba-core/blob/main/internal/planner/selection/selection.go"
click node_epic_order "https://github.com/gembacore/gemba-core/blob/main/internal/skills/epic_order/skill.go"
click node_spec "https://github.com/gembacore/gemba-core/blob/main/internal/spec/apply/apply.go"
click node_walk "https://github.com/gembacore/gemba-core/blob/main/internal/walk/doc.go"
click node_workspaces "https://github.com/gembacore/gemba-core/blob/main/internal/workspaces/registry.go"
click node_auth "https://github.com/gembacore/gemba-core/blob/main/internal/auth/doc.go"
click node_transport "https://github.com/gembacore/gemba-core/blob/main/internal/transport/doc.go"
click node_core "https://github.com/gembacore/gemba-core/blob/main/core/doc.go"
click node_skills "https://github.com/gembacore/gemba-core/blob/main/internal/skills/epic_order/doc.go"
click node_concepts "https://github.com/gembacore/gemba-core/blob/main/internal/concepts/doc.go"
click node_cli "https://github.com/gembacore/gemba-core/blob/main/internal/cli/doc.go"

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_cmd_gemba toneBlue
class node_server,node_events,node_adapters,node_bd_adapter,node_native_adapter,node_gt_adapter,node_auth,node_core toneAmber
class node_planner,node_selection,node_epic_order,node_spec,node_walk,node_workspaces,node_skills,node_concepts toneMint
class node_web_spa toneRose
class node_transport,node_cli toneIndigo
```

## Components

### Runtime

Executable entrypoints and embedded UI

- [gemba](https://github.com/gembacore/gemba-core/blob/main/cmd/gemba/main.go): server binary · Single Go server executable that hosts the app and serves embedded assets. · `cmd/gemba/main.go`

### Backend

Server, planes, adapters, and shared control logic

- [Server](https://github.com/gembacore/gemba-core/blob/main/internal/server/doc.go): http control plane · Main coordination hub for routing, auth, quotas, health, SSE, and workspace/project APIs. · `internal/server/doc.go`
- [Events](https://github.com/gembacore/gemba-core/blob/main/internal/events/hub.go): sse hub · Real-time event hub, schema translation, and tracing/logging for live UI updates. · `internal/events/hub.go`
- [Adapters](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/registry/registry.go): backend registry · Registry and family of concrete WorkPlane and OrchestrationPlane implementations. · `internal/adapter/registry/registry.go`
- [BD adapter](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/bd/workplane.go): workplane adapter · Beads/Dolt-backed WorkPlane implementation, including direct SQL and CLI modes. · `internal/adapter/bd/workplane.go`
- [Native adapter](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/native/orchestration.go): orchestration adapter · Local execution plane for terminal-backed sessions, bridges, prompts, and worktrees. · `internal/adapter/native/orchestration.go`
- [GT adapter](https://github.com/gembacore/gemba-core/blob/main/internal/adapter/gt/sessions.go): orchestration adapter · Gas Town integration for orchestration/session workflows. · `internal/adapter/gt/sessions.go`
- [Auth](https://github.com/gembacore/gemba-core/blob/main/internal/auth/doc.go): security layer · Cookies, tokens, bootstrap/login, OIDC-style flows, TLS, and verifier logic. · `internal/auth/doc.go`
- [Core](https://github.com/gembacore/gemba-core/blob/main/core/doc.go): shared domain · Common types and abstractions for workplane, orchestration, sessions, and capability guards. · `core/doc.go`

### Product logic

Planning, spec, walks, and workflow subsystems

- [Planner](https://github.com/gembacore/gemba-core/blob/main/internal/planner/doc.go): workflow policy · Dispatch, scoring, health, retro, sizing, and planning state for intent-to-execution flow. · `internal/planner/doc.go`
- [Selection](https://github.com/gembacore/gemba-core/blob/main/internal/planner/selection/selection.go): runtime scoring · Dispatch scoring used to choose ready work for sessions. · `internal/planner/selection/selection.go`
- [Epic order](https://github.com/gembacore/gemba-core/blob/main/internal/skills/epic_order/skill.go): planning ranking · Planning-time ranking used to compose higher-level sprint recommendations. · `internal/skills/epic_order/skill.go`
- [Spec](https://github.com/gembacore/gemba-core/blob/main/internal/spec/apply/apply.go): spec workflow · Spec parsing, linting, scaffold, snapshot, apply, reconcile, and hook enforcement. · `internal/spec/apply/apply.go`
- [Walk](https://github.com/gembacore/gemba-core/blob/main/internal/walk/doc.go): session model · Session and walk state, agendas, resume flow, and source aggregation. · `internal/walk/doc.go`
- [Workspaces](https://github.com/gembacore/gemba-core/blob/main/internal/workspaces/registry.go): workspace metadata · Workspace and project registry used across server, planner, and execution flows. · `internal/workspaces/registry.go`
- [Skills](https://github.com/gembacore/gemba-core/blob/main/internal/skills/epic_order/doc.go): workflow skills · First-class PM and coaching skills used by planning, walk, and escalation flows. · `internal/skills/epic_order/doc.go`
- [Concepts](https://github.com/gembacore/gemba-core/blob/main/internal/concepts/doc.go): bootstrap + drift · Project bootstrap, drift analysis, review/rewrite, and vocabulary management. · `internal/concepts/doc.go`

### Frontend

Embedded SPA and its task-centric surfaces

- [SPA](https://github.com/gembacore/gemba-core/blob/main/web/src/main.tsx): embedded frontend · React/Vite browser application embedded into the server build. · `web/src/main.tsx`

### Tooling

CLI commands, transports, and harnesses

- [Transport](https://github.com/gembacore/gemba-core/blob/main/internal/transport/doc.go): multi-protocol host · API, JSONL, and MCP hosts that expose the core app to clients and tools. · `internal/transport/doc.go`
- [CLI](https://github.com/gembacore/gemba-core/blob/main/internal/cli/doc.go): user tooling · User-facing command suite for dispatch, spec, auth, planning, and server control. · `internal/cli/doc.go`

## Connections

- gemba → Server: starts · The main binary boots the HTTP control plane.
- gemba → SPA: embeds · The server binary serves the compiled SPA assets.
- Server → Auth: secures · Authentication and bootstrap/login gates wrap server routes.
- Server → Events: streams · SSE endpoints publish live state and transitions.
- Server → Transport: exports · The server exposes API-style and auxiliary transport hosts.
- Server → Adapters: selects · Routes and workflows bind to the active adaptor set.
- Server → Workspaces: manages · Project and workspace lifecycle APIs go through the server.
- Server → Planner: coordinates · Planning, dispatch, and health workflows are orchestrated here.
- Server → Spec: serves · Spec workflows and guards are surfaced through the API.
- Server → Walk: serves · Session and walk state are exposed for the UI and tools.
- Server → Core: uses · Shared domain abstractions underpin route and workflow logic.
- SPA → Server: calls API · The SPA consumes the Go server as its primary backend.
- SPA → Events: subscribes · The UI listens to SSE updates for live session and work-item state.
- Adapters → BD adapter: includes · Beads-backed WorkPlane implementation is one backend variant.
- Adapters → Native adapter: includes · Native local execution is the default orchestration variant.
- Adapters → GT adapter: includes · Gas Town orchestration is another implementation path.
- Planner → Selection: scores · Dispatch policy chooses ready work via runtime selection scoring.
- Planner → Epic order: ranks · Planning workflows use epic ordering to rank recommendations.
- Planner → Concepts: refines · Bootstrap, drift, and review loops feed planning intent.
- Planner → Skills: applies · Planner and PM-facing workflows use embedded skills.
- Spec → BD adapter: writes beads · Spec reconciliation and apply flow route intent into the WorkPlane.
- Spec → Planner: guards intent · Spec lifecycle influences planning, drift, and reconciliation decisions.
- Walk → Native adapter: drives sessions · Walk/session state is executed through native orchestration.
- Native adapter → Events: emits · Session lifecycle events are translated into live updates.
- Native adapter → BD adapter: activates work · Active work items in the WorkPlane trigger orchestration.
- Native adapter → Core: implements · Native execution relies on shared session and orchestration types.
- Transport → Server: hosts · Transport hosts are boundary layers around the core server logic.
- CLI → Server: operates · CLI commands can start and administer the server process.
- CLI → Spec: runs · Command suite includes spec lint/apply/snapshot/reconcile flows.
- CLI → Planner: inspects · CLI surfaces planning, dispatch, retro, and health utilities.
- CLI → Adapters: conforms to · CLI tools exercise adaptor conformance and control paths.
