# littensy/charm architecture

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

- Interactive diagram: https://gitdiagram.com/littensy/charm
- Repository: https://github.com/littensy/charm

## Overview

##### Project type and purpose
- This repo is a multi-package monorepo for Roblox-TS libraries (using pnpm + wally).
- Its core package “charm” provides atomic state management primitives (atom, computed, subscribe, effect, etc.).
- Three companion packages extend charm:
- “charm-sync” (server-client synchronization via remote events)
- “react-charm” (React hooks for charm: useAtom)
- “vide-charm” (Vide data sources for charm: useAtom)
- There are build scripts (bin/*.sh), CI workflows (.github/workflows), tests under tests/, and configuration for ESLint, Prettier, Selene, stylua.

##### File structure
- Top level: repo-wide config (.eslintrc, .prettierrc, tsconfig.json, wally/rokit/testez configs), pnpm workspace config.
- packages/ folder: four sibling packages, each with:
- default.project.json + wally.toml (Luau packaging)
- package.json (npm metadata)
- src/ (Luau code + .d.ts definitions)
- modules/: holds external (wally-installed) dependencies.
- bin/: shell scripts orchestrating build, test, install.
- tests/: per-package unit tests (testez), benchmarks, utils.
- .github/workflows/: CI for build/test and release.

##### README for additional insights
- Detailed API reference for core functions (atom, subscribe, effect, computed, observe, mapped, peek, batch).
- Sections on React and Vide bindings show how charm integrates with UI.
- “Charm Sync” section describes server/client sync flows: patches, hydration, remote events.
- Emphasizes Luau (Roblox scripting language) and Roblox-TS ecosystem.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Monorepo Root
    subgraph "Monorepo Root" 
        MR1["pnpm-workspace.yaml"]:::infra
        MR2[".eslintrc/.prettierrc/selene.toml/stylua.toml/tsconfig.json/rokit.toml/testez.yml/testez-companion.toml"]:::infra
        MR_CI[".github/workflows"]:::infra
    end

    %% Build Scripts
    subgraph "Build & Install Scripts" 
        BS1["build.sh"]:::infra
        BS2["check.sh"]:::infra
        BS3["install.sh"]:::infra
        BS4["testez.d.luau"]:::infra
    end

    %% CI/CD Node
    CI1["CI Workflow"]:::infra
    CI2["Release Workflow"]:::infra

    %% Core Charm Package
    subgraph "Core Charm Package" 
        CP_pkg["package.json"]:::package
        CP_wally["wally.toml"]:::package
        CP_atom["atom.luau"]:::package
        CP_computed["computed.luau"]:::package
        CP_effect["effect.luau"]:::package
        CP_mapped["mapped.luau"]:::package
        CP_observe["observe.luau"]:::package
        CP_subscribe["subscribe.luau"]:::package
        CP_store["store.luau"]:::package
        CP_init["init.luau"]:::package
        CP_types_src["index.d.ts"]:::package
    end

    %% Extensions
    subgraph "Charm-Sync Extension" 
        CS_pkg["package.json"]:::package
        CS_wally["wally.toml"]:::package
        CS_server["server.luau"]:::package
        CS_client["client.luau"]:::package
        CS_patch["patch.luau"]:::package
        CS_flatten["flatten.luau"]:::package
        CS_validate["validate.luau"]:::package
        CS_interval["interval.luau"]:::package
        CS_init["init.luau"]:::package
        CS_types["index.d.ts"]:::package
    end

    subgraph "React-Charm Extension" 
        RC_pkg["package.json"]:::package
        RC_wally["wally.toml"]:::package
        RC_init["init.luau"]:::package
        RC_types["index.d.ts"]:::package
    end

    subgraph "Vide-Charm Extension" 
        VC_pkg["package.json"]:::package
        VC_wally["wally.toml"]:::package
        VC_init["init.luau"]:::package
        VC_types["index.d.ts"]:::package
    end

    %% Test Runner
    subgraph "Test Runner & Suites" 
        TR_root["tests/"]:::infra
    end

    %% External Dependencies
    subgraph "Wally Modules" 
        WD_conf["wally.toml"]:::external
        WD_lock["wally.lock"]:::external
    end

    %% Roblox Runtime
    subgraph "Roblox Runtime" 
        RR_server["Server (charm-sync.server)"]:::runtime
        RR_client["Client (charm & charm-sync.client)"]:::runtime
    end

    %% npm Registry
    NPM["npm Registry"]:::external

    %% Developer and flows
    Dev["Developer"]:::external
    Dev -->|runs| BS1
    Dev -->|runs| BS2
    Dev -->|runs| BS3
    Dev -->|runs| BS4

    BS1 -->|builds| CP_pkg
    BS1 -->|builds| CS_pkg
    BS1 -->|builds| RC_pkg
    BS1 -->|builds| VC_pkg

    MR_CI -->|triggers| CI1
    MR_CI -->|triggers| CI2
    CI1 -->|runs scripts| BS1
    CI1 -->|runs tests| TR_root
    CI2 -->|publishes| NPM

    %% Package publishing
    CP_pkg -->|publish| NPM
    CS_pkg -->|publish| NPM
    RC_pkg -->|publish| NPM
    VC_pkg -->|publish| NPM

    %% Roblox flows
    RR_server -->|hydrates & patches| RR_client
    RR_server -->|uses| CS_server
    RR_client -->|uses| CP_pkg
    RR_client -->|uses| CS_client

    %% Extensions using core
    CS_server -->|depends on| CP_pkg
    CS_client -->|depends on| CP_pkg
    RC_init -->|uses| CP_pkg
    VC_init -->|uses| CP_pkg

    %% Tests
    TR_root -->|tests| CP_pkg
    TR_root -->|tests| CS_pkg
    TR_root -->|tests| RC_pkg
    TR_root -->|tests| VC_pkg

    %% External dependencies
    CP_pkg -->|imports| WD_conf
    CP_pkg -->|imports| WD_lock

    %% npm registry external
    WD_conf -->|sync| NPM

    %% Click Events
    click MR1 "https://github.com/littensy/charm/blob/main/pnpm-workspace.yaml"
    click MR2 "https://github.com/littensy/charm/blob/main/.eslintrc"
    click MR2 "https://github.com/littensy/charm/blob/main/.prettierrc"
    click MR2 "https://github.com/littensy/charm/blob/main/selene.toml"
    click MR2 "https://github.com/littensy/charm/blob/main/stylua.toml"
    click MR2 "https://github.com/littensy/charm/blob/main/tsconfig.json"
    click MR2 "https://github.com/littensy/charm/blob/main/rokit.toml"
    click MR2 "https://github.com/littensy/charm/blob/main/testez.yml"
    click MR2 "https://github.com/littensy/charm/blob/main/testez-companion.toml"
    click MR_CI "https://github.com/littensy/charm/blob/main/.github/workflows/ci.yml"
    click CI2 "https://github.com/littensy/charm/blob/main/.github/workflows/release.yml"
    click BS1 "https://github.com/littensy/charm/blob/main/bin/build.sh"
    click BS2 "https://github.com/littensy/charm/blob/main/bin/check.sh"
    click BS3 "https://github.com/littensy/charm/blob/main/bin/install.sh"
    click BS4 "https://github.com/littensy/charm/blob/main/bin/testez.d.luau"
    click CP_pkg "https://github.com/littensy/charm/blob/main/packages/charm/package.json"
    click CP_wally "https://github.com/littensy/charm/blob/main/packages/charm/wally.toml"
    click CP_atom "https://github.com/littensy/charm/blob/main/packages/charm/src/atom.luau"
    click CP_computed "https://github.com/littensy/charm/blob/main/packages/charm/src/computed.luau"
    click CP_effect "https://github.com/littensy/charm/blob/main/packages/charm/src/effect.luau"
    click CP_mapped "https://github.com/littensy/charm/blob/main/packages/charm/src/mapped.luau"
    click CP_observe "https://github.com/littensy/charm/blob/main/packages/charm/src/observe.luau"
    click CP_subscribe "https://github.com/littensy/charm/blob/main/packages/charm/src/subscribe.luau"
    click CP_store "https://github.com/littensy/charm/blob/main/packages/charm/src/store.luau"
    click CP_init "https://github.com/littensy/charm/blob/main/packages/charm/src/init.luau"
    click CP_types_src "https://github.com/littensy/charm/blob/main/packages/charm/src/index.d.ts"
    click CS_pkg "https://github.com/littensy/charm/blob/main/packages/charm-sync/package.json"
    click CS_wally "https://github.com/littensy/charm/blob/main/packages/charm-sync/wally.toml"
    click CS_server "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/server.luau"
    click CS_client "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/client.luau"
    click CS_patch "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/patch.luau"
    click CS_flatten "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/flatten.luau"
    click CS_validate "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/validate.luau"
    click CS_interval "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/interval.luau"
    click CS_init "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/init.luau"
    click CS_types "https://github.com/littensy/charm/blob/main/packages/charm-sync/src/index.d.ts"
    click RC_pkg "https://github.com/littensy/charm/blob/main/packages/react/package.json"
    click RC_wally "https://github.com/littensy/charm/blob/main/packages/react/wally.toml"
    click RC_init "https://github.com/littensy/charm/blob/main/packages/react/src/init.luau"
    click RC_types "https://github.com/littensy/charm/blob/main/packages/react/src/index.d.ts"
    click VC_pkg "https://github.com/littensy/charm/blob/main/packages/vide/package.json"
    click VC_wally "https://github.com/littensy/charm/blob/main/packages/vide/wally.toml"
    click VC_init "https://github.com/littensy/charm/blob/main/packages/vide/src/init.luau"
    click VC_types "https://github.com/littensy/charm/blob/main/packages/vide/src/index.d.ts"
    click TR_root "https://github.com/littensy/charm/tree/main/tests/"
    click WD_conf "https://github.com/littensy/charm/blob/main/modules/wally.toml"
    click WD_lock "https://github.com/littensy/charm/blob/main/modules/wally.lock"

    %% Styles
    classDef package fill:#cfe2f3,stroke:#6fa8dc,stroke-width:1px
    classDef infra fill:#d9ead3,stroke:#6aa84f,stroke-width:1px
    classDef runtime fill:#f9cb9c,stroke:#e69138,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#aaaaaa,stroke-width:1px
```
