How thesysdev/crayon works
Project Type and Purpose
• Crayon is an open-source monorepo SDK/framework for building “generative UI” React applications.
• It exposes two primary JavaScript/TypeScript libraries—react-core and react-ui—plus a streaming integration library (JS) and a parallel Python streaming package.
• It includes a Docusaurus‐based documentation site and GitHub Actions workflows for building, testing, publishing to npm/PyPI, and deploying docs.
File‐Structure and Architectural Overview
├─ .github/workflows/… (CI/CD pipelines: build, test, deploy, publish)
├─ docs/ (Docusaurus site)
├─ js/
│ ├─ packages/
│ │ ├─ react-core/ (state management, hooks, context, streaming processors)
│ │ ├─ react-ui/ (over 100 modular UI components & theming, Storybook config)
│ │ └─ stream/ (JS adapters for OpenAI, Anthropic, JSON schema helpers)
│ └─ pnpm workspace & tsconfigs
├─ py/
│ └─ stream/ (Python streaming library for Crayon, adapters, SSE, protocol)
└─ top-level: README, CONTRIBUTING, LICENSE, SECURITY, CODE_OF_CONDUCT
Key Components
a. Monorepo Root & CI/CD
• GitHub Actions workflows: build-js, build-py, deploy docs, publish npm/PyPI.
• Package registry targets: npmjs.org (JS), pypi.org (Python), GitHub Pages (docs).
b. Documentation Site (docs/)
• Docusaurus serverless site: markdown files, custom plugins, React pages.
c. JS Packages
• react-core:
• ChatContext & stores (threadManager, threadListManager)
• Hooks (useThreadManager, useMessage, processStreamedMessage)
• Stream processors (processStreamedMessage → transformer → APIs)
• react-ui:
• UI Layer: atomic components (Button, Input, Shell, Chat, CodeBlock, Charts, etc.)
• Storybook (development/testing of components)
• Theming & Tailwind plugin generator
• stream (JS):
• External AI adapters (OpenAI, Anthropic)
• JSON schema helpers, textSchema, transformer, utils
d. Python Package (py/stream)
• crayonai_stream: best-effort JSON parser, SSE, OpenAI integration, protocol, logger
• Exposes nearly the same streaming interface for Python consumers
Relationships & Data Flow
• Consumer App → imports @crayonai/react-ui & @crayonai/react-core
• react-ui components invoke react-core hooks to manage state & dispatch events
• react-core → uses stream package (JS) to open streaming connection to OpenAI/Anthropic
• stream package → HTTP/XHR/SSE to AI providers → processes chunks via transformer → back to react-core
• Python users → import crayonai_stream to connect and process streams in Python environments
• Docusaurus site reads markdown and TSX references from js/packages/react-core + ui for live examples
Architectural Patterns & Principles
• Monorepo modularity: clear separation of concerns by package
• Layered architecture:
• UI layer (presentational React components)
• Core layer (state & business logic via hooks & context)
• Integration layer (streaming adapters to AI backends)
• Extensibility: plugin hooks in docs, theme presets in UI, custom ResponseTemplate in core
• CI/CD driven publish: reproducible builds, automated tests, multi-language packaging