Typescript React

apps/client/src/
├── components/
│   ├── atoms/          # Small, single-purpose (Avatar, SpaceIcon)
│   ├── molecules/      # Compound components (markdown, editors)
│   ├── surfaces/       # Page/tab views (MessageSurface, DocumentChannel)
│   ├── modals/         # Modal dialogs
│   ├── sidebars/       # Sidebar components
│   ├── tabs/           # Tab UI components
│   ├── ui/             # Chakra UI component re-exports
│   ├── icons/          # Custom FontAwesome icons
│   └── design/         # Design system components
├── views/              # Top-level views (MainView, AuthView)
├── hooks/              # Custom React hooks
├── store/              # Jotai atoms, LocalDB
└── functions/          # Utility functions (fileUpload, notify)

packages/
├── mikoto.js/          # Core API client library
│   ├── managers/       # Resource managers (SpaceManager, ChannelManager)
│   ├── WebsocketApi.ts # WebSocket connection
│   ├── MikotoClient.ts # Main client class
│   ├── AuthClient.ts   # Authentication
│   └── api.gen.ts      # Auto-generated types from OpenAPI
├── mikoto-ui/          # UI component library
├── permcheck/          # Permission checking utilities
├── lexical-markdown/   # Markdown editing plugin
└── tsconfig/           # Shared TypeScript config

export const Avatar = (
  props: {
    src?: string | null;
    userId?: string;
    size?: number;
  } & React.HTMLAttributes<HTMLImageElement>,
) => {
  const { src, userId, size, ...rest } = props;

  // implementation

  return <img src={src} size={size} {...rest} />;
};

import { chakra } from '@chakra-ui/react';

// Chakra factory
const Card = chakra('div', {
  base: { p: '4', bg: 'bg.panel' },
});

const surfaceMap = {
  textChannel: MessageSurface,
  voiceChannel: lazy(() => import('./Voice')),
  documentChannel: lazy(() => import('./Documents')),
  search: SearchSurface,
  spaceSettings: SpaceSettingsSurface,
  // ...
};

// Modals use useModalKit() hook
// State managed through modalState atom
// Content rendered in Chakra DialogRoot

// useContextMenu() hook
// Position-aware with auto-flip near viewport edge
// Dismisses on outside click or Escape

import { atom, useAtom, useAtomValue, useSetAtom } from 'jotai';
import { atomWithStorage } from 'jotai/utils';

// Simple atom
const rightBarOpenState = atom(false);

// Persisted atom
const themeState = atomWithStorage('theme', 'dark');

// Atom family (parameterized)
const tabNameFamily = atomFamily((id: string) => atom(''));

// Usage
const [value, setValue] = useAtom(rightBarOpenState);
const value = useAtomValue(rightBarOpenState);
const setValue = useSetAtom(rightBarOpenState);

import { proxy, useSnapshot } from 'valtio';
import { proxyMap } from 'valtio/utils';

// CachedManager uses proxyMap for collections
// useMaybeSnapshot() for conditional proxy observation

// QueryClient configured with structuralSharing: false
// (due to Mikoto.js class objects)

import { LocalDB } from '@/store/LocalDB';

// Runtime type-safe wrapper using Zod
const db = new LocalDB('key', schema, initFunction);
db.get(); // typed
db.set(value); // validated

import { useMikoto } from '@/hooks';

function MyComponent() {
  const mikoto = useMikoto();

  // REST calls use bracket notation
  const space = await mikoto.rest['spaces.get'](undefined, {
    params: { spaceId: id },
  });

  // WebSocket operations
  mikoto.ws.send('typing.start', { channelId });
}

// SpaceManager, ChannelManager, UserManager, etc.
// Extend CachedManager<T> for cached resources
// Methods: _get(), _insert(), _delete(), values()
// Auto-subscribe to WebSocket events for real-time updates

export function useMikoto(): MikotoClient; // Main client
export function useAuthClient(): AuthClient; // Auth client

/                                          → MainView (shell)
/spaces, /friends, /discover, /settings    → Top-level views
/space/:spaceRef                           → Space view
/space/:spaceRef/channel/:channelId        → Channel view
/space/:spaceRef/settings                  → Space settings
/login, /register, /forgotpassword         → Auth views
/invite/:inviteCode                        → Invite handler

// Context access
useMikoto(); // MikotoClient instance
useAuthClient(); // AuthClient instance

// Data fetching
useFetchMember(space); // Load space members

// UI utilities
useContextMenu(fn); // Right-click menus
useContextMenuX(); // Extended context menu
useModalKit(); // Modal management
useTabkit(); // Tab operations
useInterval(cb, ms); // setInterval wrapper
useIsMobile(); // Mobile detection
useErrorElement(); // Error boundary helper

// Props: always interface
interface ButtonProps {
  variant?: 'solid' | 'outline';
  size?: 'sm' | 'md' | 'lg';
}

// Unions/mapped types: use type
type ConnectionState = 'connecting' | 'reconnecting' | 'disconnected';

// Zod for runtime validation
import { z } from 'zod';
const schema = z.object({ name: z.string() });

// Generic constraints
class CachedManager<T extends { id: string }> { ... }