How gembacore/gemba-core works
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: server/doc.go Server · planner/doc.go Planner · registry.go Adapters · orchestration.go Native adapter
Components 20
Runtime
Executable entrypoints and embedded UI
- gemba · 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 · Main coordination hub for routing, auth, quotas, health, SSE, and workspace/project APIs.
internal/server/doc.go - Events · Real-time event hub, schema translation, and tracing/logging for live UI updates.
internal/events/hub.go - Adapters · Registry and family of concrete WorkPlane and OrchestrationPlane implementations.
internal/adapter/registry/registry.go - BD adapter · Beads/Dolt-backed WorkPlane implementation, including direct SQL and CLI modes.
internal/adapter/bd/workplane.go - Native adapter · Local execution plane for terminal-backed sessions, bridges, prompts, and worktrees.
internal/adapter/native/orchestration.go - GT adapter · Gas Town integration for orchestration/session workflows.
internal/adapter/gt/sessions.go - Auth · Cookies, tokens, bootstrap/login, OIDC-style flows, TLS, and verifier logic.
internal/auth/doc.go - Core · Common types and abstractions for workplane, orchestration, sessions, and capability guards.
core/doc.go
Product logic
Planning, spec, walks, and workflow subsystems
- Planner · Dispatch, scoring, health, retro, sizing, and planning state for intent-to-execution flow.
internal/planner/doc.go - Selection · Dispatch scoring used to choose ready work for sessions.
internal/planner/selection/selection.go - Epic order · Planning-time ranking used to compose higher-level sprint recommendations.
internal/skills/epic_order/skill.go - Spec · Spec parsing, linting, scaffold, snapshot, apply, reconcile, and hook enforcement.
internal/spec/apply/apply.go - Walk · Session and walk state, agendas, resume flow, and source aggregation.
internal/walk/doc.go - Workspaces · Workspace and project registry used across server, planner, and execution flows.
internal/workspaces/registry.go - Skills · First-class PM and coaching skills used by planning, walk, and escalation flows.
internal/skills/epic_order/doc.go - Concepts · Project bootstrap, drift analysis, review/rewrite, and vocabulary management.
internal/concepts/doc.go
Frontend
Embedded SPA and its task-centric surfaces
- SPA · React/Vite browser application embedded into the server build.
web/src/main.tsx
Connections 31
- 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.