​

Architecture Overview

​

Core Concepts

​

Project

• Firestore collection: tenants/{tenantId}/projects/{projectId}
• Managed by domains/dashboard/ (project list, creation, member management)
• DashboardProject entity carries workshop count, agent count, Beads connection settings, and member list
• UI: /projects list and /projects/[projectId] detail routes

​

Workshop

• Firestore collection: tenants/{tenantId}/projects/{projectId}/workshops/{workshopId}
• Managed by domains/workshop/ (repositories, hooks, types)
• Core entities: Workshop, Agent, WorkflowNode, WorkflowEdge
• UI: /workshops, /workshops/[workshopId]/overview, /workshops/[workshopId]/agents, /workshops/[workshopId]/workflow, /workshops/[workshopId]/agent-control, /workshops/[workshopId]/settings
• Domain hooks: useWorkshop, useAgents, useWorkflow (in domains/workshop/hooks/)

​

Agent Control Panel

• Provisioning: POST /api/workshops/[workshopId]/provision — idempotency-safe; writes status=queued to Firestore and enqueues a Cloud Tasks job for the Shokunin Provisioner. Returns 200 (no-op) when already queued/running, 202 when newly queued.
• Live session status: streams SSE events from the workshop container via AgentRuntimeProvider (domains/agent-runtime/)
• Health indicator: polls the shokunin-agent /status endpoint via ContainerHealthIndicator
• Deep links: per-session links to OpenCode web UI

​

Agent

• Firestore collection: .../workshops/{workshopId}/agents/{agentId}
• Repository: domains/workshop/repositories/agent-repository.ts
• Agents are created through the workshop’s agent management UI
• Specializations: Architect, Developer, DBA, DevOps, QA, Security, Tech Lead, Product Owner
• Plan limits enforced in UI (disabled button + upgrade banner when at limit)

​

Shokunin Agent (Autonomous Service)

• Replaces the agent-loop.sh bash script
• Built on Fastify with structured logging (pino), listening on port 8090
• Talks to OpenCode (port 4096, same pod) via @opencode-ai/sdk
• Listens for session.idle / session.error SSE events from client.global.event() as completion signals
• Exposes a control REST API (POST /loop/start, POST /loop/stop, GET /status) authenticated via X-Agent-Key
• Proxies /opencode/* requests to OpenCode including SSE streaming (piped without buffering)
• Can be scoped to a specific Beads epic (epicId) to work on a subset of tasks
• Persists runtime state (AgentRuntimeState, SessionMapping) to Firestore at agents/{agentId}/runtime/state
• Externally reachable via a shared GKE Gateway at agent.<tenant>.<domain>

​

Forge Agent

​

Workflow

• Firestore collections: .../workflowNodes/{nodeId} and .../workflowEdges/{edgeId}
• Repositories: domains/workshop/repositories/workflow-node-repository.ts, workflow-edge-repository.ts
• Node types (from packages/shokunin-flow): StartNode, StepNode, ConditionNode, LoopNode, ParallelNode, EndNode
• Edge types: FlowEdge, ConditionalEdge, LoopbackEdge
• Each StepNode can have an assigned agent from the workshop’s agent pool
• Mock data: SDLC workflow (Plan → Design → Implement → Review → Test → Deploy) seeded on creation

​

System Architecture

​

Domain Model

​

Firestore Collection Hierarchy

tenants/{tenantId}/
  projects/{projectId}           ← DashboardProject
  workshops/{workshopId}         ← Workshop  (agentUrl field set at provision time)
    agents/{agentId}             ← Agent
      runtime/state              ← AgentRuntimeState (written by shokunin-agent)
    workflowNodes/{nodeId}       ← WorkflowNode
    workflowEdges/{edgeId}       ← WorkflowEdge
    provisioning/state           ← ProvisioningRecord (queued → running → succeeded/failed)

​

Agent Runtime domain

• AgentRuntimeProvider interface (types.ts) — factory-based, not class-based; structural compatibility over inheritance
• createOpenCodeProvider (providers/opencode-provider.ts) — connects to <agentBaseUrl>/opencode/event SSE stream, reconnects automatically on disconnect
• Pure utilities: event-parser.ts (parses raw SSE strings into typed SessionEvent objects), health-mapper.ts (mapStatusResponseToHealth maps HTTP health check responses to HealthState)
• Used by: ContainerHealthIndicator, AgentControlPanel

​

Infrastructure Status domain

• GcpStatusRepository interface + createHttpGcpStatusRepository() HTTP implementation (calls /api/infrastructure/status)
• useInfrastructureStatus(env) hook — fetches and auto-refreshes every 60 seconds; manages loading/error state
• environment-resolver.ts — pure function that resolves EnvironmentContext from process.env (reads NEXT_PUBLIC_FIREBASE_DATABASE_ID)
• manifest-parser.ts — pure stateless functions for querying GcpInfraManifest declarations

​

Package Architecture

​

Infrastructure

​

Data Flow: From Task to Code

​

External routing (Vercel → Workshop)

Vercel (platform UI)
  │  HTTPS
  ▼
GKE Gateway (shared, TLS termination)
  │  hostname-based routing
  ├──► agent.<tenant>.<domain> → Workshop Service :8090 (shokunin-agent REST + proxy)
  └──► opencode.<tenant>.<domain> → Workshop Service :4096 (OpenCode web API)

Workshop Pod (GKE Autopilot)
  ├── shokunin-agent (port 8090)  ←── task polling, session control, Firestore state
  └── opencode       (port 4096)  ←── code execution sessions (SSE events)

​

Task execution flow

1. User creates a project, workshop, configures agents and a workflow in the platform UI.
2. Beads tracks the task graph for the project.
3. Shokunin Agent (POST /loop/start) polls Beads for ready tasks (bd ready).
4. For each ready task, the agent creates an isolated git worktree (<repo>/.worktrees/task-<id>, branch agent/task-<id>).
5. The agent spawns an OpenCode session scoped to that worktree directory via client.session.create({ query: { directory } }).
6. OpenCode works autonomously; the agent listens for session.idle / session.error SSE events on client.global.event().
7. On session.idle (completion): the agent runs bd sync, cleans up the worktree, and updates Firestore state.
8. On session.error (failure): the agent cleans up the worktree and records the error in Firestore.
9. A Forge Agent (planned) reviews the produced branch and merges it.
10. The platform UI reflects the updated task status in real time via Firestore.

​

Key Design Decisions

​

Repository Pattern

​

Domain Hooks

​

Server vs Client Components

​

Worktree Isolation