Project Structure

Project Structure

Cosella is organized as a pnpm workspace monorepo managed by Turborepo. This structure enables code sharing, consistent tooling, and fast builds.

Directory Overview

cosella/
├── apps/                    # Runnable applications (6)
│   ├── dashboard/           # Sales rep daily driver (React + Vite + TanStack Router)
│   ├── admin/               # Internal admin panel (React + Vite + TanStack Router)
│   ├── desktop/             # Electron desktop copilot (Electron + React + Vite)
│   ├── docs/                # This documentation site (Astro + Starlight)
│   ├── marketing/           # Public landing page (Astro + React)
│   └── storybook/           # UI component stories (Storybook 9 + Vite)
├── packages/                # Shared libraries (13)
│   ├── ui/                  # React component library (25+ components)
│   ├── tokens/              # Design tokens (CSS + JS)
│   ├── domain/              # Zod schemas + TypeScript types
│   ├── api-client/          # Generated OpenAPI types + TanStack Query hooks
│   ├── realtime/            # Typed WebSocket client with reconnect
│   ├── auth/                # Auth provider, session store
│   ├── permissions/         # Capability-based permission helpers
│   ├── testing/             # MSW server + handlers + fixtures
│   ├── observability/       # Error boundaries, Sentry integration
│   ├── app-shell/           # Shared app shell layout (Sidebar, TopBar)
│   ├── forms/               # React Hook Form + Zod integration
│   ├── audio-capture/       # Audio capture (Web + Electron)
│   └── audio-engine/        # Audio pipeline, VAD, Opus encoding
├── tooling/                 # Internal build config (3)
│   ├── eslint-config/       # Shared ESLint configs (base, react, boundaries)
│   ├── ts-config/           # Shared TypeScript configs (base, react, node)
│   └── plop-templates/      # Handlebars templates for code generation
├── docs/                    # Design specs, review standards
├── .github/                 # CI/CD workflows
├── .husky/                  # Git hooks (pre-commit, commit-msg, pre-push)
└── .claude/                 # Claude Code local settings

Package Dependency Graph

apps ──────> packages (one direction only, never reverse)

tokens ─────> (nothing internal)
domain ─────> (nothing internal)
ui ─────────> tokens ONLY
api-client ─> domain
realtime ───> domain
auth ───────> domain
permissions > domain + auth (declared exception)
testing ───> domain
observability > ui + domain (NEVER auth)
app-shell ──> auth + tokens + ui
forms ──────> ui
audio-capture > domain
audio-engine > domain

Enforced by: eslint-plugin-boundaries at lint time.

Key Packages

UI Components (@cosella/ui)

Radix-based component library with 25+ components:

import { Button, Card, Input, Alert, Modal, DataTable } from '@cosella/ui';

<Button variant="primary" size="lg">
  Get Started
</Button>

Components: Alert, Badge, Button, Card, Checkbox, CrashPage, FullScreenLoader, Input, Label, Logo, Menu, Modal, MultiSelect, NotFoundPage, Radio, Select, Skeleton, Switch, Tabs, TablePagination, DataTable, Textarea, Toast, Tooltip

Design Tokens (@cosella/tokens)

CSS-first design tokens using Tailwind v4 @theme {} blocks:

@import "tailwindcss";
@import "@cosella/tokens/theme.css";
@import "@cosella/tokens/components.css";

Token categories: Brand palette, neutral palette, semantic colors, status colors, typography, spacing, motion, shadows, z-index, glassmorphic overlay tokens.

Domain Models (@cosella/domain)

Zod schemas with inferred TypeScript types:

import { UserSchema, type User } from '@cosella/domain';

const user: User = UserSchema.parse(data);

API Client (@cosella/api-client)

Generated from OpenAPI spec with TanStack Query hooks:

import { useQuery } from '@tanstack/react-query';
import { api } from '@cosella/api-client';

const { data } = useQuery({
  queryKey: ['users'],
  queryFn: () => api.users.list(),
});

Observability (@cosella/observability)

Error boundaries, Sentry integration, and data redaction:

import { ErrorBoundary, useSentryErrorReporter } from '@cosella/observability';

App Shell (@cosella/app-shell)

Shared layout with Sidebar, TopBar, and CommandPalette:

import { AppShell, Sidebar, TopBar } from '@cosella/app-shell';

Build System

Turborepo

Manages builds, tests, and linting across the monorepo:

# Build all packages and apps
pnpm build

# Run tests
pnpm test

# Typecheck
pnpm typecheck

# Lint
pnpm lint

# Start all apps
pnpm dev

Code Generation

# Generate a new UI component
pnpm gen component

# Generate a new package
pnpm gen package

# Regenerate API client from OpenAPI spec
pnpm gen:api

Testing Strategy

Unit Tests

• Framework: Vitest 3.2.4
• DOM: jsdom 26.1.0
• Mocking: MSW v2 for API mocking
• Coverage: @vitest/coverage-v8

Component Tests

• Framework: @testing-library/react 16.3.0
• Interaction: @testing-library/user-event 14.6.1
• Visual: Storybook 9 with play interactions

E2E Tests

• Framework: Playwright 1.52.0
• Browsers: Chromium, Firefox, Safari

CI/CD Pipeline

Pre-commit Hooks (Husky)

• pre-commit: pnpm lint-staged (ESLint + Prettier on staged files)
• commit-msg: pnpm commitlint --edit (enforce Conventional Commits)
• pre-push: pnpm typecheck && pnpm turbo run build --filter='./apps/*'

GitHub Actions

• ci.yml: Type check, lint, test, build
• deploy-do-dev.yml: DigitalOcean dev deployment

Next Steps

• Development Guide - Contribution workflow
• Vibecoder UI Guide - Safe UI-only contributions
• AI Agent Guide - Rules for AI coding agents
• Architecture Decisions - Technical decisions