# effect-ts/effect-smol architecture

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

- Interactive diagram: https://gitdiagram.com/effect-ts/effect-smol
- Repository: https://github.com/effect-ts/effect-smol

## Overview

##### Project Type and Purpose
- It is a library written in TypeScript that offers a broad range of utilities—ranging from basic types (BigDecimal, BigInt, Boolean, etc.) to more advanced functional programming constructs like Effect, Fiber, Deferred, and even streaming and concurrency frameworks.
- The existence of modules such as PubSub, Queue, Scheduler, and STM (Software Transactional Memory) suggests that it’s designed to support asynchronous, concurrent, and possibly fault-tolerant programming patterns. In short, it resembles a framework or set of libraries aimed at providing a robust effect system (similar to frameworks like ZIO in Scala).

##### Analysis of the File Structure
- Top-Level Directories:
- bundle: Contains bundled (pre-packaged) versions of various modules (e.g., basic, batching, logger, pubsub, etc.). This indicates preparation for distribution or easy consumption.
- src: Contains the primary source code for the library. Files here are organized by the functionality they provide (e.g., Effect.ts, Fiber.ts, Queue.ts, etc.). There is also an “internal” folder with modules handling implementation details (core, concurrency, encoding, errors, schema, etc.).
- scratchpad: Includes experimental or example code which might serve as proofs-of-concept or performance benchmarks. It contains example scenarios (like batching, channel, queue, etc.) that likely illustrate the library’s features.
- test: Where unit and integration tests are located, verifying components such as Channel, Deferred, Effect, Fiber, Layer, Logger, and more.
- Configuration and Build Files:
- Files such as package.json, tsconfig’s, rollup.config.js, and various GitHub workflow configurations (.github/...) indicate a well-established build/test/deployment pipeline.
- The presence of ESLint and other dev-tools ensures code quality and consistency.

a. Main Components:
- API/Library Interface (src files): Highlight externally exposed modules such as Effect, Fiber, Deferred, PubSub, Queue, Scheduler, etc. These represent the building blocks that users interact with.
- Core Engine & Internal Implementations (src/internal): Group together modules that implement the underlying functionalities such as concurrency control, error handling, schema processing, and low-level utilities.
- Bundling and Packaging (bundle): Indicate that the library is bundled for distribution, showing its relationship with the source.
- Example/Usage Code (scratchpad) and Testing (test): While not part of the runtime system, these directories illustrate how components are used and verified, and might be noted as separate “verification” or “usage” environments.

b. Relationships & Data Flow:
- The external API layers (in src) are built on top of the core engine found in src/internal. For example, user calls to Effect.ts will eventually result in interactions with Fiber (concurrency management) and Scheduler.
- Components such as Logger, PubSub, and Queue may interact with or depend on lower-level utilities like Deferred or internal concurrency modules.
- The bundled output in the bundle directory is derived from the modular source code, and it’s essential to indicate that these files are aggregated (using Rollup) before distribution.
- Testing modules in the test directory ensure that each component interacts correctly, serving as validators for the designed interactions.

c. Architectural Patterns and Design Principles:
- Separation of Concerns: The clear segmentation between external-facing API and internal implementations.
- Modularization: Each functionality (e.g., data types, concurrency, schema, etc.) is implemented in its dedicated, isolated module.
- Extensibility: The structure (with a clear separation between bundle, src, and scratchpad) indicates that the system is designed to be extensible and testable.

d. Relevant Technologies & Tools:
- Language: TypeScript.
- Bundler: Rollup (as seen in rollup.config.js).
- Development/CI: GitHub Actions workflows (in .github/workflows) and a configuration for pnpm (pnpm-lock.yaml).
- Testing: Vitest (vitest.config.ts) alongside a structured testing hierarchy.
- Tooling: ESLint, tsconfig configurations, and possibly Nix/NixOS (based on flake.nix) for reproducible builds.

##### Final Advice
- As you design, consider that while the library’s API is rich, the bulk of the logic is hidden in the internal modules—this separation should be clearly communicated.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External API/Library Modules (src)
    subgraph "External API/Library Modules (src)"
        A1["Effect (API)"]:::external
        A2["Fiber (API)"]:::external
        A3["Deferred (API)"]:::external
        A4["PubSub (API)"]:::external
        A5["Queue (API)"]:::external
        A6["Schedule (API)"]:::external
    end

    %% Core Engine/Internal Implementations (src/internal)
    subgraph "Core Engine/Internal Implementations (src/internal)"
        B1["Core"]:::internal
        B2["Concurrency"]:::internal
        B3["Errors"]:::internal
        B4["Schema"]:::internal
    end

    %% Bundling & Packaging (bundle)
    subgraph "Bundling & Packaging (bundle)"
        C1["Basic Bundle"]:::packaging
        C2["PubSub Bundle"]:::packaging
        C3["Queue Bundle"]:::packaging
    end

    %% Example/Usage Code (scratchpad)
    subgraph "Example/Usage Code (scratchpad)"
        D1["Examples"]:::example
    end

    %% Testing Environment (test)
    subgraph "Testing Environment (test)"
        E1["Effect Test"]:::test
        E2["Fiber Test"]:::test
        E3["Logger Test"]:::test
    end

    %% Relationships between layers (vertical flow)
    %% External API calls Internal implementations
    A1 -->|"uses"| B1
    A2 -->|"uses"| B2
    A3 -->|"triggers"| B3
    A4 -->|"maps to"| B4
    A5 -->|"leverages"| B2
    A6 -->|"coordinates"| B1

    %% Internal modules feed into Bundled outputs
    B1 -->|"bundled as"| C1
    B4 -->|"bundled as"| C2
    B2 -->|"bundled as"| C3

    %% External API used in Examples and Tests
    A1 -->|"example"| D1
    A1 -->|"tested by"| E1
    A2 -->|"tested by"| E2
    A4 -->|"tested by"| E3

    %% Click Events for External API/Library Modules
    click A1 "https://github.com/effect-ts/effect-smol/blob/main/src/Effect.ts"
    click A2 "https://github.com/effect-ts/effect-smol/blob/main/src/Fiber.ts"
    click A3 "https://github.com/effect-ts/effect-smol/blob/main/src/Deferred.ts"
    click A4 "https://github.com/effect-ts/effect-smol/blob/main/src/PubSub.ts"
    click A5 "https://github.com/effect-ts/effect-smol/blob/main/src/Queue.ts"
    click A6 "https://github.com/effect-ts/effect-smol/blob/main/src/Schedule.ts"

    %% Click Events for Core Engine & Internal Implementations
    click B1 "https://github.com/effect-ts/effect-smol/blob/main/src/internal/core.ts"
    click B2 "https://github.com/effect-ts/effect-smol/blob/main/src/internal/concurrency.ts"
    click B3 "https://github.com/effect-ts/effect-smol/blob/main/src/internal/errors.ts"
    click B4 "https://github.com/effect-ts/effect-smol/tree/main/src/internal/schema/"

    %% Click Events for Bundling & Packaging
    click C1 "https://github.com/effect-ts/effect-smol/blob/main/bundle/basic.ts"
    click C2 "https://github.com/effect-ts/effect-smol/blob/main/bundle/pubsub.ts"
    click C3 "https://github.com/effect-ts/effect-smol/blob/main/bundle/queue.ts"

    %% Click Event for Example/Usage Code
    click D1 "https://github.com/effect-ts/effect-smol/tree/main/scratchpad"

    %% Click Events for Testing Environment
    click E1 "https://github.com/effect-ts/effect-smol/blob/main/test/Effect.test.ts"
    click E2 "https://github.com/effect-ts/effect-smol/blob/main/test/Fiber.test.ts"
    click E3 "https://github.com/effect-ts/effect-smol/blob/main/test/Logger.test.ts"

    %% Style Definitions
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef internal fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef packaging fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef example fill:#FFDAB9,stroke:#333,stroke-width:2px;
    classDef test fill:#FFFFE0,stroke:#333,stroke-width:2px;
```
