# mlanza/atomic architecture

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

- Interactive diagram: https://gitdiagram.com/mlanza/atomic
- Repository: https://github.com/mlanza/atomic

## Overview

##### Project type and purpose
- This is a JavaScript library (“Atomic”) that brings Clojure-style protocols and functional programming facilities to JavaScript without a transpilation step.
- Its purpose is to supply a “functional core / imperative shell” architecture, offering:
- a core of pure functions and protocols in `src/core`
- integrations with the DOM in `src/dom`
- a shell for side-effects, FRP signals, and command buses in `src/shell`
- optional immutable-data helpers in `src/immutables`
- a thin CLI/command registry in `agents` and `dist/cmd.js`
- The README shows how library consumers write application‐specific code on top of these pieces.

##### File structure
- Top-level:
- `src/` contains the module source broken into four sub-packages: core, dom, immutables, shell
- `dist/` holds production bundles: `atomic_/core.js`, `dom.js`, `shell.js`, plus `cmd.js` and `immutable.js`
- `agents/` and `docs/` provide supplemental guidance and examples of usage, testing, and advanced patterns
- build config: `rollup.config.js`, `.babelrc`, `package.json`
- `tests/` contains a minimal browser‐based smoke test
- Patterns & architectural cues:
- Layered modular design—foundation protocols/types → core behaviors → shell (effects) & dom (rendering)
- Protocol–based extension points (a microkernel style)
- Transducers, signals, atoms, command registry as core primitives
- No server, database, or network layer—pure library for front-end and CLI use

##### README for additional insights
- Emphasis on FCIS (Functional Core Imperative Shell) pattern
- Core modules are purely functional; shell modules orchestrate real‐world effects
- Consumers write a “domain” module (their own pure functions) and a “main” module (their shell)
- Shows how modules interconnect: import `core`, `shell`, `dom`, then wire up `$.atom`, `$.sub`, `$.on`

a. Main components
- Core Layer (src/core)
- Immutables Layer (src/immutables)
- Shell Layer (src/shell)
- DOM Layer (src/dom)
- Command Layer (`dist/cmd.js` + agents)
- Bundles (dist/atomic_/*, dist/immutable.js)
- Consumer Domain (illustrated in README as user code: sokoban.js, main.js)
b. Relationships & data flow
- Core defines protocols and pure behaviors → consumed by Immutables, DOM, and Shell
- Shell uses Core to create atoms, signals, event buses → exposes side-effects API
- DOM uses Core and Shell signals to render and patch the browser view
- Command layer (`cmd.js`) sits on top of Shell, wires domain code into the system
- Dist folder outputs are packaged ES modules for direct browser import
- Consumer code calls into these bundles, driving state and rendering
c. Architectural patterns & principles
- Layered abstraction: protocols/types → behaviors → effects → rendering
- Functional core / imperative shell (FCIS)
- Protocol‐based dynamic extension (microkernel/pluggable)
- Point-free pipelines and transducers as composition primitives
- Signal/atom/event bus as FRP backbone
d. Key technologies & libraries
- Native ES modules, Rollup for bundling
- No transpiler—relies on modern browsers’ module support
- Transducers (in Core)
- Clojure-inspired protocols API (custom implementation)
- DOM patching & event subscription primitives
- Immutable-data adapters but optional

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Layer"
        direction TB
        CoreIndex["Core Entry: index.js"]:::core
        CoreBehaviors["Behaviors & Utils"]:::core
        CoreProtocols["Core Protocols"]:::protocol
        CoreTypes["Core Types"]:::core
    end

    subgraph "Immutables Layer"
        direction TB
        ImmutIndex["Immutables Entry: index.js"]:::immut
        ImmutTypes["Immutables Types"]:::immut
    end

    subgraph "Shell Layer"
        direction TB
        ShellIndex["Shell Entry: index.js"]:::shell
        ShellBehaviors["Shell Behaviors & Effects"]:::shell
        ShellProtocols["Shell Protocols"]:::protocol
        ShellTypes["Shell Types"]:::shell
    end

    subgraph "DOM Layer"
        direction TB
        DOMIndex["DOM Entry: index.js"]:::dom
        DOMBehaviors["DOM Behaviors"]:::dom
        DOMProtocols["DOM Protocols"]:::protocol
        DOMTypes["DOM Types"]:::dom
    end

    subgraph "Command Layer"
        direction TB
        Agents["Agents/"]:::cmd
        CLIBundle["dist/cmd.js"]:::cmd
    end

    subgraph "Distribution Bundles"
        direction TB
        DistCore["dist/atomic_/core.js"]:::bundle
        DistDOM["dist/atomic_/dom.js"]:::bundle
        DistImmut["dist/atomic_/immutables.js"]:::bundle
        DistShell["dist/atomic_/shell.js"]:::bundle
        DistImmutableHelper["dist/immutable.js"]:::bundle
    end

    Consumer["Consumer Domain Code"]:::consumer

    BuildConfig["Build Config"]:::infra
    Tests["tests/"]:::infra
    Docs["docs/"]:::infra

    %% Relationships
    CoreIndex --> CoreBehaviors
    CoreBehaviors --> CoreProtocols
    CoreIndex --> CoreTypes

    CoreIndex --> ImmutIndex
    CoreIndex --> ShellIndex
    CoreIndex --> DOMIndex

    CoreProtocols --> ShellProtocols
    CoreProtocols --> DOMProtocols

    ShellIndex --> Agents
    Agents --> CLIBundle

    CoreIndex --> DistCore
    DOMIndex --> DistDOM
    ImmutIndex --> DistImmut
    ShellIndex --> DistShell
    ImmutIndex --> DistImmutableHelper

    Consumer --> ShellIndex
    Consumer --> DOMIndex

    BuildConfig --> DistCore
    BuildConfig --> DistDOM
    BuildConfig --> DistImmut
    BuildConfig --> DistShell
    BuildConfig --> DistImmutableHelper

    Tests -.-> CoreIndex
    Docs -.-> Consumer

    %% Click Events
    click CoreIndex "https://github.com/mlanza/atomic/blob/main/src/core/index.js"
    click CoreBehaviors "https://github.com/mlanza/atomic/blob/main/src/core/behaviors.js"
    click CoreProtocols "https://github.com/mlanza/atomic/tree/main/src/core/protocols/"
    click CoreTypes "https://github.com/mlanza/atomic/tree/main/src/core/types/"
    click ImmutIndex "https://github.com/mlanza/atomic/blob/main/src/immutables/index.js"
    click ImmutTypes "https://github.com/mlanza/atomic/blob/main/src/immutables/types.js"
    click ShellIndex "https://github.com/mlanza/atomic/blob/main/src/shell/index.js"
    click ShellBehaviors "https://github.com/mlanza/atomic/blob/main/src/shell/behaviors.js"
    click ShellProtocols "https://github.com/mlanza/atomic/tree/main/src/shell/protocols/"
    click ShellTypes "https://github.com/mlanza/atomic/tree/main/src/shell/types/"
    click DOMIndex "https://github.com/mlanza/atomic/blob/main/src/dom/index.js"
    click DOMBehaviors "https://github.com/mlanza/atomic/blob/main/src/dom/behaviors.js"
    click DOMProtocols "https://github.com/mlanza/atomic/tree/main/src/dom/protocols/"
    click DOMTypes "https://github.com/mlanza/atomic/tree/main/src/dom/types/"
    click Agents "https://github.com/mlanza/atomic/tree/main/agents/"
    click CLIBundle "https://github.com/mlanza/atomic/blob/main/dist/cmd.js"
    click DistCore "https://github.com/mlanza/atomic/blob/main/dist/atomic_/core.js"
    click DistDOM "https://github.com/mlanza/atomic/blob/main/dist/atomic_/dom.js"
    click DistImmut "https://github.com/mlanza/atomic/blob/main/dist/atomic_/immutables.js"
    click DistShell "https://github.com/mlanza/atomic/blob/main/dist/atomic_/shell.js"
    click DistImmutableHelper "https://github.com/mlanza/atomic/blob/main/dist/immutable.js"
    click BuildConfig "https://github.com/mlanza/atomic/blob/main/rollup.config.js"
    click Tests "https://github.com/mlanza/atomic/tree/main/tests/"

    %% Styles
    classDef core fill:#cce4f6,stroke:#0366d6
    classDef immut fill:#d4f1f4,stroke:#0aa
    classDef shell fill:#fde2c7,stroke:#f4a261
    classDef dom fill:#d8f3dc,stroke:#2a9d8f
    classDef cmd fill:#e0bbe4,stroke:#9c27b0
    classDef bundle fill:#e8e9eb,stroke:#6e6e6e
    classDef consumer stroke-dasharray:5 5,fill:none,stroke:#000
    classDef infra fill:#f0f0f0,stroke:#ccc
    classDef protocol fill:#ffe6f0,stroke:#ec407a,stroke-dasharray:5 5
```
