boardkit-architecture

Boardkit monorepo architecture: package boundaries, module system, registries, stores.Use when planning refactors, adding features, or understanding system boundaries.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive technical blueprint of the Boardkit monorepo architecture, detailing package boundaries, module systems, registries, and Pinia stores. It serves as an essential guide for developers to navigate system boundaries, plan large-scale refactors, and ensure architectural consistency when adding new features or modules.

Use Cases

  • Architectural Refactoring: Use the strict boundary rules and package structure map to safely move logic between core, UI, and platform layers without introducing circular dependencies.
  • Module Development: Leverage the ModuleRegistry and defineModule templates to create and register new interactive widgets or tools within the Boardkit ecosystem.
  • State Management Implementation: Reference the boardStore and toolStore definitions to manage complex document schemas, viewport states, and user interactions using Pinia.
  • System Onboarding: Provide new developers with a clear overview of the monorepo's 'Key Files' and 'Registries' to accelerate their understanding of the codebase's mental model.
nameboardkit-architecture
description|
Boardkit monorepo architecturepackage boundaries, module system, registries, stores.
allowed-toolsRead, Grep, Glob

Boardkit Architecture

Package Structure

packages/
├── core/          @boardkit/core
│   ├── src/types/           → Document, Module, Action, DataContract
│   ├── src/stores/          → boardStore, toolStore (Pinia)
│   ├── src/actions/         → coreActions, ActionRegistry
│   ├── src/modules/         → ModuleRegistry, defineModule
│   └── src/migrations/      → Document migrations (v0→v1→v2)
│
├── ui/            @boardkit/ui
│   ├── src/components/      → 28 reusable components
│   ├── DESIGN_SYSTEM.md     → Complete DS spec
│   └── uno.config.ts        → UnoCSS tokens
│
├── platform/      @boardkit/platform
│   └── src/storage/         → IndexedDB adapter, Tauri FS adapter
│
└── app-common/    @boardkit/app-common
    ├── src/modules/         → Shared modules (Text, Todo, TaskRadar, FocusLens)
    └── src/composables/     → Shared composables

apps/
├── web/           → PWA (Vite + Vue 3)
└── desktop/       → Tauri macOS app

Boundaries (STRICT)

Package Can import Cannot import
core Nothing ui, platform, apps
ui core (types only) platform, apps
platform core (types only) ui, apps
app-common core, ui platform, apps
apps Everything Each other

Registries (Singletons)

// ModuleRegistry - widget definitions
ModuleRegistry.register(todoModule)
ModuleRegistry.get('todo') // → ModuleDefinition

// ActionRegistry - user actions
ActionRegistry.register({ id: 'duplicate', ... })
ActionRegistry.execute('duplicate')

// DataContractRegistry - data sharing contracts
DataContractRegistry.register('boardkit.todo.v1', schema)

// DataBus - runtime pub/sub
DataBus.publish('boardkit.todo.v1', data)
DataBus.subscribe('boardkit.todo.v1', callback)

Stores (Pinia)

// boardStore - document state
boardStore.widgets        // Widget[]
boardStore.elements       // CanvasElement[]
boardStore.selectedIds    // Set<string>
boardStore.viewport       // { x, y, zoom }
boardStore.isDirty        // boolean
boardStore.addWidget(module, position)
boardStore.updateWidgetState(id, state)

// toolStore - tool state
toolStore.activeTool      // 'select' | 'hand' | 'rectangle' | ...
toolStore.isDrawing       // boolean
toolStore.setTool(tool)

Document Schema (v2)

interface BoardkitDocument {
  version: 2
  meta: { title, createdAt, updatedAt }
  board: {
    viewport: { x, y, zoom }
    widgets: Widget[]
    elements: CanvasElement[]
    background: BoardBackground
  }
  modules: Record<string, unknown>
  dataSharing?: { permissions[], links[] }
}

Module System

const myModule = defineModule<MyState>({
  id: 'my-module',
  displayName: 'My Module',
  icon: 'box',
  category: 'productivity',
  defaultWidth: 300,
  defaultHeight: 200,
  minWidth: 200,
  minHeight: 150,
  defaultState: () => ({ items: [] }),
  serialize: (state) => state,
  deserialize: (data) => data as MyState,
  component: () => import('./MyWidget.vue')
})

Key Files

Purpose Path
Document types packages/core/src/types/document.ts
Module types packages/core/src/types/module.ts
Action types packages/core/src/types/action.ts
Board store packages/core/src/stores/boardStore.ts
Migrations packages/core/src/migrations/index.ts
Tests packages/core/__tests__/