Skip to main content

​
Architecture Overview

The Shokunin Platform is a Next.js 15 monorepo backed by Firebase/Firestore and Google Cloud Platform. It is built around a hierarchy of four core concepts: projects → workshops → agents → workflows. This page explains what those concepts are, how they relate, and which parts of the system exist today versus what is planned.

​
Core Concepts

​
Project

A project is the top-level organizational unit. Every team starts by creating a project, which scopes all work: workshops, agents, task tracking (Beads), and infrastructure configuration. Status: Implemented
  • 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
Each project optionally connects to a Beads task-tracking database (MySQL-backed via infrastructure/beads-api or direct host config). This allows a project to track its own issue graph.

​
Workshop

A workshop is a managed workspace within a project where AI agents collaborate on tasks. Think of it as a room in which a team of AI agents work together, with shared context, a workflow canvas, and a knowledge base. Status: Implemented (schema, repositories, UI routes)
  • 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]/settings
  • Domain hooks: useWorkshop, useAgents, useWorkflow (in domains/workshop/hooks/)
Workshops have a lifecycle: created within a project, configured with agents, and executed by running workflows. A workshop belongs to exactly one project.

​
Agent

An agent is an AI participant in a workshop. Agents have specializations (e.g., Architect, Developer, DBA, QA), a model assignment, a system prompt, and a status (idle | working | error | active | disabled). Status: Implemented (schema, repository, agent management UI)
  • 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)
Agents appear in collaboration surfaces with the same presence semantics as human users — avatars, activity dots, and canvas ownership badges. There are two distinct agent concepts in the platform:

​
Shokunin Agent (Autonomous Service)

The Shokunin Agent (infrastructure/shokunin-agent — Planned) is an autonomous TypeScript service that runs inside a Workshop Container. It manages the full agent lifecycle: polling Beads for ready tasks, creating isolated git worktrees per task, spawning OpenCode sessions, and persisting state to Firestore.
  • Replaces the current agent-loop.sh bash script
  • Built on Fastify with structured logging (pino)
  • Talks to OpenCode via @opencode-ai/sdk (SSE events for completion)
  • Exposes a control REST API (POST /loop/start, POST /loop/stop, GET /status)
  • Can be scoped to a specific Beads epic (epicId) to work on a subset of tasks
Status: Planned — See tasks/prd-shokunin-agent-service.md for full specification.

​
Forge Agent

A Forge Agent is an agent specialized in code review and merge operations — designed to validate and integrate agent-produced changes into the main branch via a dedicated workflow. Forge agents operate on git worktrees produced by other sessions. Status: Planned — Referenced in Shokunin Agent Service PRD as future integration point.

​
Workflow

A workflow is a directed graph of steps that agents execute inside a workshop. Workflows are built visually using a React Flow canvas and persisted in Firestore. Status: Implemented (schema, repositories, canvas UI)
  • 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
Planned: Live agent execution — today, workflows define what should happen; the Shokunin Agent Service (planned) will be the runtime that actually executes steps by dispatching OpenCode sessions.

​
System Architecture

The diagram below shows the full system: the platform UI running in the browser backed by Firebase, and the planned Workshop Container where autonomous agents execute tasks using OpenCode and Beads. Shokunin Platform — System Architecture

​
Domain Model

The platform organizes Firestore data into four domain modules:
DomainLocationStatus
Dashboard (Projects)domains/dashboard/Implemented
Workshop, Agents, Workflowdomains/workshop/Implemented
Beads (Task Tracking)domains/beads/Implemented
(Shokunin Agent Runtime)infrastructure/shokunin-agent/Planned

​
Firestore Collection Hierarchy

tenants/{tenantId}/
  projects/{projectId}           ← DashboardProject
  workshops/{workshopId}         ← Workshop
    agents/{agentId}             ← Agent
    workflowNodes/{nodeId}       ← WorkflowNode
    workflowEdges/{edgeId}       ← WorkflowEdge
All Firestore documents carry versioning metadata (schemaVersion, createdAt, updatedAt, tenantId) and support on-read lazy migrations via a shared migrations framework.

​
Package Architecture

Internal packages under packages/ provide shared primitives:
PackagePurposeStatus
shokunin-typesShared TypeScript typesImplemented
shokunin-uiShared UI component libraryImplemented
shokunin-flowReact Flow workflow canvas nodes/edgesImplemented
shokunin-feature-flagsStatic feature flag providerImplemented
shokunin-authAuth provider and hooksImplemented
shokunin-aiAI provider interface (stub)Implemented (stub)
shokunin-collaborationCollaboration/presence adapter (stub)Implemented (stub)
shokunin-cmsCMS adapterImplemented

​
Infrastructure

ComponentTechnologyStatus
Web AppNext.js 15, VercelImplemented
DatabaseGoogle FirestoreImplemented
AuthFirebase AuthenticationImplemented
Task Tracking APIinfrastructure/beads-api (Fastify + MySQL)Implemented
OpenCode Webinfrastructure/opencode-web (Docker)Implemented (scaffold)
Workshop ContainerDocker (shokunin-agent + opencode)Planned
IaCTerraform on GCPImplemented

​
Data Flow: From Task to Code

This describes the intended end-to-end flow once the Shokunin Agent Service is implemented. Agent Workflow — Task to Code
  1. User creates a project, creates a workshop, configures agents and a workflow in the platform UI.
  2. Beads tracks the task graph for the project.
  3. Shokunin Agent (container) polls Beads for ready tasks (bd ready).
  4. For each ready task, the agent creates an isolated git worktree (agent/task-<id>).
  5. The agent spawns an OpenCode session in that worktree and sends the task prompt.
  6. OpenCode works autonomously; the agent listens for session.updated SSE events.
  7. On completion, the agent runs bd sync to push Beads state, then cleans up the worktree.
  8. A Forge Agent (planned) reviews the produced branch and merges it.
  9. The platform UI reflects the updated task status in real time.
Today (Implemented): Steps 1–2 (project, workshop, Beads setup in UI). The agent runtime (steps 3–9) is planned.

​
Key Design Decisions

​
Repository Pattern

Data access is encapsulated in repository classes under domains/<domain>/repositories/. Business logic never touches Firestore directly.

​
Domain Hooks

Custom React hooks (useWorkshop, useAgents, useWorkflow) consume repositories and expose reactive state. Context (tenantId, projectId) is injected explicitly, not read from global state.

​
Server vs Client Components

Server Components are used by default. 'use client' is added only when interactivity (state, events) is strictly required.

​
Worktree Isolation

The planned Shokunin Agent Service assigns one git worktree per task. This prevents file conflicts between concurrent agent sessions and enables parallel task execution as a future capability.