# thesysdev/crayon architecture

> Architecture diagram of the GitHub repository thesysdev/crayon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thesysdev/crayon
- Repository: https://github.com/thesysdev/crayon

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Application
    ConsumerApp["Consumer App"]:::external

    %% JS Monorepo Workspace Config
    subgraph "JS Workspace Config"
        WS1["pnpm-workspace.yaml"]:::config
        WS2["tsconfig.json"]:::config
    end

    %% React UI Package
    subgraph "react-ui Package" 
        UIIndex["index.ts\n(Entry Point)"]:::ui
        UIComp["Components & Theming"]:::ui
        UIStory["Storybook Config"]:::ui
    end

    %% React Core Package
    subgraph "react-core Package"
        CoreIndex["index.ts\n(Entry Point)"]:::core
        CoreCTX["ChatContext & Stores"]:::core
        CoreHooks["Hooks"]:::core
        CoreStreamProc["Stream Processor"]:::integration
        CoreTypes["Types & ResponseTemplate"]:::core
    end

    %% JS Stream Integration
    subgraph "js/packages/stream"
        StreamOpenAI["openai.ts"]:::integration
        StreamAnthropic["anthropic.ts"]:::integration
        StreamJSON["jsonSchemaHelpers.ts"]:::integration
        StreamTrans["transformer.ts"]:::integration
        StreamEntry["crayonStream.ts"]:::integration
    end

    %% Python Stream Package
    subgraph "py/stream Package"
        PyStreamCore["stream.py"]:::integration
        PySSE["sse.py"]:::integration
        PyOpenAI["integrations/openai/stream.py"]:::integration
        PyJSONParser["best_effort_json_parser.py"]:::integration
        PyProtocol["protocol.py"]:::integration
        PyLogger["logger.py"]:::integration
        PyConfig["setup.py & pyproject.toml"]:::config
    end

    %% Documentation Site
    Docs["Docusaurus Site"]:::docs

    %% CI/CD Workflows
    CICD[".github/workflows"]:::cicd

    %% Registries
    subgraph "Registries & Deploy Targets"
        NPM["npmjs.org"]:::cicd
        PYPI["pypi.org"]:::cicd
        GH_Pages["GitHub Pages"]:::cicd
    end

    %% Relationships
    ConsumerApp -->|"imports"| UIIndex
    ConsumerApp -->|"imports"| CoreIndex
    UIIndex -->|"uses hooks from"| CoreIndex
    CoreIndex -->|"calls"| CoreStreamProc
    CoreStreamProc -->|-- HTTP/SSE --| StreamOpenAI
    CoreStreamProc -->|-- HTTP/SSE --| StreamAnthropic
    CoreStreamProc -->|-- uses helpers --| StreamJSON
    CoreStreamProc -->|-- transforms --| StreamTrans
    CoreStreamProc -->|-- stream interface --| StreamEntry
    ConsumerApp -->|"Python consumers import"| PyStreamCore
    PyStreamCore -->|integrates| PyOpenAI
    PyStreamCore -->|parses| PyJSONParser
    PyStreamCore -->|protocol| PyProtocol
    PyStreamCore -->|logs| PyLogger
    Docs -->|"sources markdown/tsx from"| UIIndex
    Docs -->|"sources markdown/tsx from"| CoreIndex
    CICD -->|"build-js"| WS1
    CICD -->|"build-js"| WS2
    CICD -->|"publish JS"| NPM
    CICD -->|"publish Py"| PYPI
    CICD -->|"deploy docs"| GH_Pages

    %% Click Events
    click WS1 "https://github.com/thesysdev/crayon/blob/main/js/pnpm-workspace.yaml"
    click WS2 "https://github.com/thesysdev/crayon/blob/main/js/tsconfig.json"
    click UIIndex "https://github.com/thesysdev/crayon/blob/main/js/packages/react-ui/src/index.ts"
    click UIComp "https://github.com/thesysdev/crayon/tree/main/js/packages/react-ui/src/components/"
    click UIComp "https://github.com/thesysdev/crayon/blob/main/js/packages/react-ui/src/lib/tailwind/generateTailwindPlugin.ts"
    click UIStory "https://github.com/thesysdev/crayon/tree/main/js/packages/react-ui/.storybook/"
    click CoreIndex "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/index.ts"
    click CoreCTX "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/internal/ChatContext.ts"
    click CoreCTX "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/internal/useThreadManagerStore.ts"
    click CoreCTX "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/internal/useThreadListManagerStore.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadManager.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useMessage.tsx"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadListActions.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadActions.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadListState.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadManagerSelector.ts"
    click CoreHooks "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/hooks/useThreadState.ts"
    click CoreStreamProc "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/stream/processStreamedMessage.ts"
    click CoreTypes "https://github.com/thesysdev/crayon/blob/main/js/packages/react-core/src/types/responseTemplate.ts"
    click StreamOpenAI "https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/openai.ts"
    click StreamAnthropic "https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/anthropic.ts"
    click StreamJSON "https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/jsonSchemaHelpers.ts"
    click StreamTrans "https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/transformer.ts"
    click StreamEntry "https://github.com/thesysdev/crayon/blob/main/js/packages/stream/src/crayonStream.ts"
    click PyStreamCore "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/stream.py"
    click PySSE "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/sse.py"
    click PyOpenAI "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/integrations/openai/stream.py"
    click PyJSONParser "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/best_effort_json_parser.py"
    click PyProtocol "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/protocol.py"
    click PyLogger "https://github.com/thesysdev/crayon/blob/main/py/stream/src/crayonai_stream/logger.py"
    click PyConfig "https://github.com/thesysdev/crayon/blob/main/py/stream/setup.py"
    click PyConfig "https://github.com/thesysdev/crayon/blob/main/py/stream/pyproject.toml"
    click Docs "https://github.com/thesysdev/crayon/tree/main/docs/"
    click CICD "https://github.com/thesysdev/crayon/tree/main/.github/workflows/"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#000;
    classDef core fill:#d4edda,stroke:#000;
    classDef integration fill:#ffe5b4,stroke:#000;
    classDef docs fill:#e2e3e5,stroke:#000,stroke-dasharray: 5 5;
    classDef cicd fill:#f8d7da,stroke:#000;
    classDef config fill:#f1f1f1,stroke:#000;
    classDef external fill:#ffffff,stroke:#000,stroke-width:2px;
```
