> ## Documentation Index > Fetch the complete documentation index at: https://docs.shokunin.app/llms.txt > Use this file to discover all available pages before exploring further. # Repo Map > Directory structure, responsibilities, and key entry points of the Shokunin monorepo # 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//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` |