Package Structure

Klaxon is a pnpm monorepo with Rust and TypeScript packages.

klaxon/
├── crates/
│   └── klaxon-server/          # Rust cloud server
├── packages/
│   ├── protocol/               # @ottercoders/klaxon-protocol — Zod schemas
│   ├── common/                 # @ottercoders/klaxon-common — shared UI library
│   ├── ui/                     # @klaxon/ui — desktop client entry point
│   └── web/                    # @klaxon/web — browser web app
├── apps/
│   └── klaxon-mobile/          # Expo React Native mobile app
├── deploy/
│   └── helm/klaxon/            # Kubernetes Helm chart
└── docs/                       # VitePress documentation

Package Dependency Graph

@ottercoders/klaxon-protocol  (Zod schemas — no deps)
        ↑
@ottercoders/klaxon-common    (components, hooks, api, utils)
        ↑
   ┌────┼────┐
   ↑    ↑    ↑
@klaxon/ui  @klaxon/web  klaxon-mobile
(desktop)   (browser)    (Expo app)

Package Details

@ottercoders/klaxon-protocol (packages/protocol/)

The TypeScript contract between server and clients. Contains only Zod schemas — no React, no DOM, no side effects.

• KlaxonItemSchema — 28 fields
• FormFieldSchema — discriminated union of 18 field types
• AppSettingsSchema — settings with defaults
• OrgIdSchema, UserIdSchema, AgentIdSchema, ActorTypeSchema — cloud identity types

No build step. main and types point at src/index.ts directly.

@ottercoders/klaxon-common (packages/common/)

Shared component library used by all client apps. Contains:

• API transport (api.ts): invoke() maps command names to REST calls, listen() emits WebSocket events
• Components: FormField (15 types), FormWizard, HistoryCard, ContextMenu, SnoozePicker, DateRangeChips, KeyboardHelp, UndoToast
• Widgets: MainWidget (full sidebar/list/detail), SettingsWidget, TemplatesTab
• Hooks: useEvent, useEvents, useInvoke, useRefreshOnVisible, useKeyboardShortcuts
• Utils: relTime, levelColor, priorityLabel, deadlineLabel
• Styles: CSS variables with theme support (dark/light/dracula/nord)

No build step. Consumers resolve TS source directly via moduleResolution: "Bundler".

@klaxon/ui (packages/ui/)

Desktop client — a thin Vite entry point that renders <MainWidget /> from common. One file: src/main.tsx.

@klaxon/web (packages/web/)

Browser web app — same as desktop but runs on port 5173. Identical <MainWidget /> render.

klaxon-mobile (apps/klaxon-mobile/)

Expo React Native app with its own component set (form renderers adapted for React Native). Shares @ottercoders/klaxon-protocol types but does not use @ottercoders/klaxon-common (which depends on react-dom).

klaxon-server (crates/klaxon-server/)

Rust binary. Not a workspace package visible to pnpm — built with Cargo separately.

Adding a New Component

1. Create it in packages/common/src/components/
2. Export it from packages/common/src/index.ts
3. Import it from @ottercoders/klaxon-common in any client app
4. Add tests in packages/common/src/__tests__/