Repo Map

The Shokunin Platform is organized as a monorepo. This page is a reference map to help contributors find where to make changes.

Top-Level Structure

v0-shokunin-ai-platform/
├── app/                    # Next.js App Router pages and layouts
├── apps/                   # Micro-frontend applications
│   └── mfe-docs/           # This docs site (Mintlify v4)
├── components/             # Shared React components
│   ├── beads/              # Beads task tracking UI views
│   ├── marketing/          # Public marketing page components
│   ├── platform/           # Platform shell (sidebar, topbar)
│   └── ui/                 # Shadcn UI primitives (auto-generated)
├── domains/                # Domain repositories and hooks
│   ├── agent-runtime/      # Agent runtime SSE provider interface
│   ├── beads/              # Beads issue data access
│   ├── dashboard/          # Dashboard data access
│   ├── infrastructure/     # GCP infrastructure status repository and hooks
│   ├── project/            # Project data access
│   └── workshop/           # Workshop and agent data access
├── hooks/                  # Global React hooks
├── infrastructure/         # Local and cloud backend service configs
│   ├── beads-api/          # Beads HTTP API (Go)
│   ├── beads-backend/      # Dolt SQL Server config
│   ├── shokunin-agent/     # Workshop container service (Fastify, GKE)
│   └── shokunin-provisioner/ # Workshop provisioner (Fastify, Cloud Run)
├── lib/                    # Utility functions and shared logic
├── packages/               # Internal shared packages
│   ├── shokunin-ai/        # AI provider adapter
│   ├── shokunin-auth/      # Authentication adapter
│   ├── shokunin-cms/       # CMS adapter (BaseHub)
│   ├── shokunin-collaboration/ # Real-time collaboration (Liveblocks)
│   ├── shokunin-feature-flags/ # Feature flag provider
│   ├── shokunin-flow/      # Flow canvas / visual workflow
│   ├── shokunin-types/     # Shared TypeScript types
│   └── shokunin-ui/        # Extended design system components
├── plugins/                # OpenCode agent plugins
│   ├── agent/              # Shokunin agent plugin (@horizon-ai-dev/shokunin)
│   └── observability/      # Observability plugin (planned)
├── tasks/                  # PRDs and planning documents
└── terraform/              # GCP infrastructure as code

Directory Reference

`app/`

Next.js 15 App Router. Route groups organize the application:

Path	Description
`app/(auth)/`	Authentication pages (sign in, sign up)
`app/(platform)/`	Authenticated platform routes — requires login
`app/(platform)/dashboard/`	User dashboard
`app/(platform)/projects/`	Project listing and management
`app/(platform)/workshops/`	Workshop workspace (the primary work surface)
`app/(platform)/workshops/[workshopId]/agent-control/`	Agent Control Panel — provisioning, SSE session status, container health
`app/(platform)/docs/`	Documentation route — embeds this Mintlify site
`app/(platform)/profile/`	User profile settings
`app/(platform)/admin/`	Administrative controls
`app/(platform)/admin/infrastructure/`	Infrastructure health dashboard (Cloud Run, GKE, tenant workloads, IAM, Cloud Tasks)
`app/(platform)/knowledge/`	Knowledge library
`app/api/`	Next.js API route handlers
`app/globals.css`	Tailwind CSS v4 theme variables and design tokens
`app/layout.tsx`	Root layout with providers

Key entry point: /docs route is at app/(platform)/docs/page.tsx.

`components/`

Reusable React components organized by concern:

Subdirectory	Description
`components/ui/`	Shadcn UI primitives — do not edit directly. Use `bunx shadcn@latest add` to add/update.
`components/platform/`	Platform shell: `sidebar-nav.tsx`, `topbar.tsx`, `collaboration-shell.tsx`
`components/beads/`	Beads task tracking views: kanban board, list view, dependency graph, detail sheet
`components/marketing/`	Public marketing components: `landing-page.tsx`, `landing-header.tsx`, `landing-footer.tsx`
`components/auth-wrapper.tsx`	Client-side auth context provider wrapper (required in root layout)
`components/ai-panel.tsx`	AI chat panel component
`components/comment-thread.tsx`	Inline comment thread component
`components/theme-provider.tsx`	Theme context provider

Key entry point: Platform navigation is in components/platform/sidebar-nav.tsx.

`domains/`

Domain-driven data access layer. Each domain encapsulates Firestore read/write logic for a specific business entity. This separates business logic from UI components.

Domain	Contents	Description
`domains/workshop/`	`repositories/`, `hooks/`	Workshop and agent session data access
`domains/project/`	`repositories/`	Project CRUD operations
`domains/beads/`	`repositories/`, `hooks/`	Beads issues and dependency graph data
`domains/dashboard/`	`hooks/`, `index.ts`, `types.ts`	Dashboard aggregation hooks
`domains/agent-runtime/`	`providers/`, `utils/`, `types.ts`	Provider-agnostic SSE interface for agent events; OpenCode SSE provider; event parser and health mapper utilities
`domains/infrastructure/`	`repositories/`, `hooks/`, `utils/`, `types.ts`	GCP infrastructure status: `GcpStatusRepository` interface, HTTP implementation, `useInfrastructureStatus` hook, environment resolver, manifest parser

Pattern: Each domain exports custom hooks (e.g., useWorkshop, useAgents) that consume repositories and manage React state. Hooks receive tenantId and projectId from a parent context.

`hooks/`

Global custom React hooks shared across the app (not tied to a specific domain):

File	Description
`hooks/use-mobile.ts`	Responsive breakpoint detection
`hooks/use-toast.ts`	Toast notification hook (Sonner)

`lib/`

Utility functions and shared logic:

File / Directory	Description
`lib/utils.ts`	`cn()` utility for Tailwind class merging — use in every component
`lib/env.ts`	Type-safe environment variable access
`lib/beads-db.ts`	Beads local database access utilities
`lib/beads-filters.ts`	Beads issue filtering logic
`lib/beads-dagre-layout.ts`	DAG layout algorithm for Beads dependency graph
`lib/beads-issue-type.ts`	Beads issue type helpers
`lib/firestore/`	Firestore client initialization, migrations, seed data
`lib/federation/`	Module federation: `remote-registry.ts`, error boundary, fallback
`lib/mock-data/`	Mock data for development and testing

`packages/`

Internal shared packages. These are TypeScript modules used across the monorepo.

Package	Description
`packages/shokunin-ai/`	AI provider adapter — wraps AI APIs with a unified interface. Contains `adapters/`, `hooks.ts`, `provider.tsx`, `types.ts`
`packages/shokunin-auth/`	Authentication adapter — wraps Firebase Auth. Contains `adapters/`, `provider.tsx`, `types.ts`
`packages/shokunin-cms/`	CMS adapter — wraps BaseHub. Contains `adapters/`, `image.ts`, `provider.tsx`, `pump.tsx`, `types.ts`
`packages/shokunin-collaboration/`	Real-time collaboration adapter — wraps Liveblocks. Contains `adapters/`, `provider.tsx`, `room-id.ts`, `types.ts`
`packages/shokunin-feature-flags/`	Feature flag provider with static mock adapter. Defines all platform feature flags (including `docs-site`, `ai-chat`, `collaboration`).
`packages/shokunin-flow/`	Visual flow canvas built on React Flow. Contains agent canvas, workflow nodes/edges, collaboration cursors
`packages/shokunin-types/`	Shared TypeScript type definitions used across the monorepo
`packages/shokunin-ui/`	Extended design system beyond Shadcn: `s-button.tsx`, `s-card.tsx`, `notification-bell.tsx`, `loading-spinner.tsx`, `logo.tsx`, etc.

`plugins/`

OpenCode agent plugins that extend the AI coding agent’s capabilities:

Plugin	Description
`plugins/agent/`	Shokunin agent plugin (`@horizon-ai-dev/shokunin`) — the primary agent plugin. Contains specialized agents, commands, tools, and bundled skills for AI-assisted development workflows. Published to npm.
`plugins/observability/`	Observability plugin — planned

Key entry point: plugins/agent/README.md explains how to install and use the Shokunin agent plugin.

`apps/`

Micro-frontend applications:

App	Description
`apps/mfe-docs/`	This Mintlify v4 documentation site. Config: `docs.json`. Content: MDX pages organized by nav section.

`infrastructure/`

Local backend service configurations (see also docker-compose.yml at the root):

Directory	Description
`infrastructure/beads-backend/`	Dockerfile and config for the local Dolt SQL Server (Beads data backend)
`infrastructure/beads-api/`	Dockerfile and config for the Beads HTTP API
`infrastructure/opencode-web/`	Dockerfile for the OpenCode web interface (currently commented out in docker-compose)
`infrastructure/shokunin-agent/`	Workshop container service: Fastify API (port 8090) managing agent lifecycle — task polling, OpenCode session spawning, Firestore state persistence. Runs alongside OpenCode via supervisord in a GKE pod.
`infrastructure/shokunin-provisioner/`	Workshop provisioner: Cloud Run service (port 8091) triggered by Cloud Tasks. Dynamically creates K8s Deployment and Service in a tenant namespace when a workshop is first provisioned.

`terraform/`

GCP infrastructure as code. Provisions all cloud resources for the Shokunin Platform:

platform/environments/dev-shared/ — VPC, Artifact Registry, GKE Autopilot, GKE Gateway, Workshop Provisioner
platform/environments/staging/ and production/ — full Beads stack (Dolt VM, Filestore, Cloud Run)
platform/environments/dev/ — per-developer Firestore database and Secret Manager access
platform/modules/ — reusable single-purpose modules
terraform/tenants/ — per-tenant GKE namespace, HTTPRoutes, Workshop workload
terraform/config/ — environment and tenant .tfvars configuration files

See terraform/README.md for the conceptual infrastructure diagram and GCP component list.

`tasks/`

Product Requirements Documents (PRDs) and planning files. Source of truth for feature planning:

File	Description
`tasks/prd-platform-documentation.md`	This documentation epic PRD
`tasks/prd-workshop-agents-workflow.md`	Workshop + agent workflow planning
`tasks/prd-shokunin-agent-service.md`	Shokunin agent service planning
`tasks/prd-workshop-agent-control-panel.md`	Workshop Agent Control Panel planning
`tasks/prd-auth-identity-access.md`	Auth and identity access planning
`tasks/prd-audit-logging.md`	Audit logging planning
`tasks/prd-admin-tenant-ops.md`	Admin tenant operations planning

Key Entry Points

What you want to change	Where to look
Platform navigation (sidebar)	`components/platform/sidebar-nav.tsx`
`/docs` route and embed logic	`app/(platform)/docs/page.tsx`
Feature flags	`packages/shokunin-feature-flags/index.tsx`
Authentication flow	`packages/shokunin-auth/`, `components/auth-wrapper.tsx`
Design tokens / Tailwind theme	`app/globals.css` (`@theme inline` block)
Firestore data access	`domains/<domain>/repositories/`
AI agent plugin	`plugins/agent/src/`
Documentation content	`apps/mfe-docs/`
Infrastructure (GCP)	`terraform/`
Local dev infrastructure	`infrastructure/`, `docker-compose.yml`
Infrastructure Dashboard	`app/(platform)/admin/infrastructure/`, `domains/infrastructure/`, `app/api/infrastructure/status/route.ts`
Workshop provisioning	`app/api/workshops/[workshopId]/provision/route.ts`, `domains/workshop/services/provisioning-service.ts`
Agent Control Panel	`app/(platform)/workshops/[workshopId]/agent-control/`, `components/workshops/agent-control-panel.tsx`

Naming Conventions

Type	Convention	Example
Files	`kebab-case.tsx`	`user-profile.tsx`, `sidebar-nav.tsx`
Components	`PascalCase`	`UserProfile`, `SidebarNav`
Functions/variables	`camelCase`	`fetchUserData`, `isLoading`
Hooks	`use` prefix	`useWorkshop`, `useAuth`
Constants	`UPPER_SNAKE_CASE`	`MAX_AGENTS`, `API_BASE_URL`
Props interfaces	`PascalCase` + `Props` suffix	`ButtonProps`, `WorkshopCardProps`
Domain repositories	`PascalCase` + `Repository` suffix	`WorkshopRepository`

Overview

Architecture

Getting Started

Repo Map

Infrastructure

Repo Map

Repo Map

Top-Level Structure

Directory Reference

`app/`

`components/`

`domains/`

`hooks/`

`lib/`

`packages/`

`plugins/`

`apps/`

`infrastructure/`

`terraform/`

`tasks/`

Key Entry Points

Naming Conventions

​Repo Map

​Top-Level Structure

​Directory Reference

​app/

​components/

​domains/

​hooks/

​lib/

​packages/

​plugins/

​apps/

​infrastructure/

​terraform/

​tasks/

​Key Entry Points

​Naming Conventions

Repo Map

Top-Level Structure

Directory Reference

`app/`

`components/`

`domains/`

`hooks/`

`lib/`

`packages/`

`plugins/`

`apps/`

`infrastructure/`

`terraform/`

`tasks/`

Key Entry Points

Naming Conventions