Project Structure

This is a pnpm monorepo. Everything is TypeScript, ESM-only, and requires Node >= 20.

Top-level layout

packages/gecx-chat/         The SDK source. Framework-neutral core + React adapter.
packages/gecx-chat-ccaas/   CCaaS handoff adapters (Salesforce, Zendesk, ServiceNow, Genesys, Five9, Google CCAI).
packages/gecx-chat-cockpit/ Agent-side cockpit package (useAgentSession, CockpitSurface).
packages/create-gecx-chat/  Zero-config app generator (`pnpm create gecx-chat`).
apps/showcase/              Feature showcase (Next.js, port 3000).
apps/agi-coolaid-stand/     Branded storefront demo (Next.js, port 3001).
apps/applied-ai-retail/     Premium retail demo (Next.js, port 3002).
apps/proxy-reference/       Reference proxy server (plain Node, port 8080).
apps/start-studio/          Onboarding wizard at start.gecx.chat (Next.js, port 3003).
schemas/                    JSON Schema files mirroring the public TypeScript surface.
docs/                       Documentation and runbooks.
templates/                  Customer-facing templates (CLAUDE.md, agent-pack).

The SDK is the only publishable package. The apps are private workspace members that import it via gecx-chat: workspace:*.

Inside packages/gecx-chat/

Source (src/)

The source is organized by domain:

src/
  index.ts              Main entry point (re-exports public surface)
  core/                 Session state machine, event emitter, store
  messages/             Message types, normalization, turn cursor
  transport/            HTTP and WebSocket transports, proxy transport
  auth/                 Token broker, chat token handler
  tools/                Tool registry, client tools, server tools, validation
  react/                React adapter (hooks, components, A2UI bridge)
  a2ui/                 A2UI (generative UI) core logic
  rich-content/         Rich-content registry and downgrade negotiation
  errors/               Error codes, error metadata, debug bundles
  analytics/            Product analytics and journey metrics
  telemetry/            Trace timeline and observability
  handoff/              Human agent handoff protocol
  identity/             Identity manager, multi-tab coordination
  storage/              Storage abstraction for session persistence
  upload/               File upload contract and validation
  governance/           Governance policies
  cli/                  Doctor CLI and scaffold commands
  server/               Server-side utilities (token handler, server tools)
  testing/              Mock transport, scenarios, test helpers
  compat/               Legacy widget compatibility bridge

The react/ directory is isolated from the core. If you are not using React, the core entry point (gecx-chat) has zero React dependencies.

Tests (test/)

Vitest unit tests live in packages/gecx-chat/test/. Playwright e2e tests live in each app (apps/showcase/tests/, apps/agi-coolaid-stand/tests/).

Build output (dist/)

Built with tsup. Output is ESM with .d.ts type declarations. The dist/ directory mirrors the src/ structure.

Package exports

The SDK ships 8 entry points so you only import what you need:

React is an optional peer dependency. The core, server, testing, rich-content, a2ui, and compat entry points work without it.

What's next

• Installation -- install the SDK and set up your project.
• Quickstart -- send your first message with React.
• Start Studio -- skip installation entirely. Open the wizard and download a runnable repo in under three minutes.
• Showcase App -- explore every feature interactively.