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
│   ├── beads/              # Beads issue data access
│   ├── dashboard/          # Dashboard data access
│   ├── project/            # Project data access
│   └── workshop/           # Workshop and agent data access
├── hooks/                  # Global React hooks
├── infrastructure/         # Local backend infrastructure configs
│   ├── beads-api/          # Beads HTTP API (Go)
│   └── beads-backend/      # Dolt SQL Server config
├── 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)/docs/`	Documentation route — embeds this Mintlify site
`app/(platform)/profile/`	User profile settings
`app/(platform)/admin/`	Administrative controls
`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

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)

`terraform/`

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

GCP project, networking, Cloud Run services
Firestore database, Firebase config
Cloud Storage buckets, IAM roles

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-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`

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

Overview

Architecture

Getting Started

Repo Map

Infrastructure

​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