# stackblitz/alien-signals architecture

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

- Interactive diagram: https://gitdiagram.com/stackblitz/alien-signals
- Repository: https://github.com/stackblitz/alien-signals

## Overview

##### Project Type and Purpose
- This is an open-source, language-agnostic reactivity library (“alien-signals”) implemented in TypeScript. It provides a push-pull signal algorithm (inspired by Vue, Preact, Svelte, Reactively) for building reactive data flows without using arrays, sets, maps, or recursion. Its goal is to be extremely fast and form the core of higher-level tools (e.g., Vue language tools, React bindings).

##### File Structure Analysis
- Top level:
- src/ – the TypeScript source
- benchs/ – benchmark scripts (complex.mjs, memoryUsage.mjs, propagate.mjs)
- tests/ – unit tests for each reactive feature
- build.js, package.json, tsconfig.json – build and packaging
- Key modules in src/:
- system.ts – the core reactive graph, link / node definitions, propagation & dirty checking
- index.ts – public API (signal, computed, effect, effectScope) that wraps createReactiveSystem()
- Utility/config: GitHub workflows, lint/config files, assets/logo.

##### Main Components
1. Public API Layer
- Exports signal(), computed(), effect(), effectScope()
- Wraps and invokes the core engine
2. Core Reactive Engine
- ReactiveNode, Link structures
- propagate() and checkDirty() algorithms
- Dependency graph management
3. Build & Packaging
- build.js → transpiles TS to JS targets
- package.json / pnpm-lock.yaml → versioning and dependencies
4. Test Harness
- tests/*.spec.ts → validates API behavior and edge cases
5. Benchmark Suite
- benchs/*.mjs → measures performance against other implementations
6. External Integrations (optional context)
- Vue core, React bindings, language tools using createReactiveSystem

##### Component Relationships and Interactions
- User Code → calls Public API →
- API invokes Core Engine → updates ReactiveNode graph →
- Engine uses propagate()/checkDirty() to schedule updates →
- Effects are triggered back in the API layer → user callbacks run
- Tests and benchmarks are separate flows that import the API layer to exercise both correctness and performance
- Build process sits orthogonally, reading src/ to output dist/ for NPM consumers

##### Architectural Patterns & Principles
- Modular layering: clear separation between public API and engine
- Graph-based scheduling: nodes and doubly linked lists for dependency tracking
- No recursion + constant-time operations: performance-focused constraint
- Single responsibility: system.ts only handles graph logic; index.ts only handles API façade

##### Technologies & Frameworks
- TypeScript for source and typings
- Node.js / ESM (benchmarks in .mjs)
- Jest (or similar) for unit tests (build.spec.ts, computed.spec.ts, etc.)
- Custom build script (build.js) over ts-node or tsc directly
- CI via GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Code"]:::external

    subgraph "Public API Layer"
        API["Public API\n(signal, computed, effect, effectScope)"]:::api
    end

    subgraph "Core Reactive Engine"
        SN["ReactiveNode"]:::engine
        LK["Link"]:::engine
        PG["propagate()"]:::engine
        CD["checkDirty()"]:::engine
    end

    subgraph "Build & Packaging"
        Build["build.js"]:::tools
        PKG["package.json\npnpm-lock.yaml"]:::tools
        TSC["tsconfig.json\ntslint.config.ts"]:::tools
    end

    subgraph "Test Harness"
        Test["tests/*.spec.ts"]:::tools
    end

    subgraph "Benchmark Suite"
        Bench["benchs/*.mjs"]:::tools
    end

    subgraph "CI Workflow"
        CI[".github/workflows/test.yml"]:::tools
    end

    subgraph "External Integrations"
        Ext["Vue, React, Language Tools"]:::external
    end

    %% Connections
    User -->|"import & call"| API
    API -->|"manage graph"| SN
    SN -->|"relates to"| LK
    API -->|"calls propagate()/checkDirty()"| PG
    PG -->|"updates graph"| SN
    CD -->|"checks graph"| SN
    PG -->|"triggers effects"| API
    CD -->|"triggers effects"| API

    Test -->|"runs tests"| API
    Bench -->|"benchmarks performance"| API

    Build -->|"transpiles src → dist"| PKG
    TSC -->|"configures build"| Build

    CI -->|"triggers"| Test

    Ext -.->|"optional import"| API

    %% Click Events
    click API "https://github.com/stackblitz/alien-signals/blob/master/src/index.ts"
    click SN "https://github.com/stackblitz/alien-signals/blob/master/src/system.ts"
    click Build "https://github.com/stackblitz/alien-signals/blob/master/build.js"
    click PKG "https://github.com/stackblitz/alien-signals/blob/master/package.json"
    click PKG "https://github.com/stackblitz/alien-signals/blob/master/pnpm-lock.yaml"
    click TSC "https://github.com/stackblitz/alien-signals/blob/master/tsconfig.json"
    click TSC "https://github.com/stackblitz/alien-signals/blob/master/tslint.config.ts"
    click Test "https://github.com/stackblitz/alien-signals/blob/master/tests/*.spec.ts"
    click Bench "https://github.com/stackblitz/alien-signals/blob/master/benchs/*.mjs"
    click CI "https://github.com/stackblitz/alien-signals/blob/master/.github/workflows/test.yml"

    %% Styles
    classDef engine fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#90EE90,stroke:#333,stroke-width:1px
    classDef tools fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
