# dazl-dev/engine architecture

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

- Interactive diagram: https://gitdiagram.com/dazl-dev/engine
- Repository: https://github.com/dazl-dev/engine

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo-style TypeScript toolkit (“Engine”) for building and running “features” across different environments.
- It provides three main npm packages:
- engine-core: the in-memory runtime and communication framework
- engine-cli: command-line interface for scaffolding, building, and launching
- runtime-node: a Node.js–specific host layer for engine-core
- The repo also contains guides, API documentation configs, example projects, and test-fixture apps.

##### File Structure Analysis
- Top-level: configuration files (.eslintrc, tsconfig.*, lerna.json), GitHub workflows, README, LICENSE.
- docs-conf & guides: documentation setup for publication.
- examples & test-fixtures: sample apps showing various engine use cases (iframe, React, Node, multi-feature, etc.).
- packages: three sub-packages with their own source (src), tests, build configs, and package.json.

a. Main Components
- Developer & CLI (engine-cli)
- Core Runtime (engine-core)
- Host implementations (runtime-node, iframe, webworker, WS server, socket)
- Feature modules (user code discovered at runtime)
- Build pipeline (esbuild, entrypoint generators)
- Dashboard server (dev-mode UI)
b. Relationships & Data Flow
1. Developer invokes CLI (`npx dazl-engine` or `yarn engine …`).
2. CLI loads user config and discovers feature files via engine-core APIs.
3. CLI generates entrypoints for each environment (web, node, iframe) using esbuild plugins.
4. On “run” or “start,” CLI spawns host processes or in-browser contexts (runtime-node, iframe, webworker) and wires them via engine-core communication.
5. engine-core orchestrates message passing between feature instances across hosts (via WS, RPC, postMessage).
6. Dashboard server displays live feature graph and logs by subscribing to engine-core events.
c. Architectural Patterns & Principles
- Modular monorepo with Lerna/yarn workspaces
- Plugin-style host initializers and communication adapters
- Single-entrypoint feature model (feature + multiple env configs)
- Separation of build (static generation) vs. runtime (dynamic wiring)
d. Key Technologies & Frameworks
- TypeScript & ts-configs per package
- esbuild (via CLI plugins) for bundling
- Node.js child processes, worker_threads, iframes, WebSockets
- API Extractor for docs generation
- Mocha/Jest for tests

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    Developer["Developer"]:::green -->|invoke CLI| CLI["engine-cli (CLI)"]:::green

    %% Build-Time Layer
    subgraph "Build-Time"
        CLI -->|loadConfig & discoverFeatures| Core["engine-core"]:::blue
        CLI -->|generateEntrypoints| BuildPipeline["Build Pipeline"]:::gray
        subgraph "Build Pipeline"
            EB1["esbuild-build-end-plugin"]:::gray
            EB2["esbuild-dynamic-entry-plugin"]:::gray
            EB3["esbuild-html-plugin"]:::gray
            EB1 & EB2 & EB3 --> CreateEP["create-entrypoints"]:::gray
            CreateEP -->|"create-web-entrypoint"| WebEntry["create-web-entrypoint"]:::gray
            CreateEP -->|"create-node-entrypoint"| NodeEntry["create-node-entrypoint"]:::gray
        end
    end

    %% Runtime Layer
    subgraph "Run-Time"
        Core -->|spawn| RN["runtime-node"]:::orange
        Core -->|spawn| Iframe["iframe initializer"]:::orange
        Core -->|spawn| WebWorker["webworker initializer"]:::orange
        Core -->|spawn| SocketSrv["socket-server initializer"]:::orange
        Core -->|spawn| UniWorker["universal-worker-host"]:::orange
        Core -->|spawn| WSClient["ws-client-host"]:::orange

        Core <-->|"postMessage / RPC / WebSocket"| RN
        Core <-->|"postMessage"| Iframe
        Core <-->|"postMessage"| WebWorker
        Core <-->|"WebSocket"| SocketSrv
        Core <-->|"WebSocket"| WSClient
    end

    %% Dev UI Layer
    subgraph "Dev UI"
        Dashboard["Dashboard Server"]:::green
        Core -->|emit events| Dashboard
    end

    %% Click Events
    click CLI "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/cli.ts"
    click CLI "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/bin/engine.js"
    click CLI "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/index.ts"

    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/index.ts"
    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/runtime-engine.ts"
    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/run-engine-app.ts"
    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/communication.ts"
    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/message-types.ts"
    click Core "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/communication-errors.ts"

    click RN "https://github.com/dazl-dev/engine/blob/main/packages/runtime-node/src/index.ts"
    click RN "https://github.com/dazl-dev/engine/blob/main/packages/runtime-node/src/ipc-host.ts"
    click RN "https://github.com/dazl-dev/engine/blob/main/packages/runtime-node/src/worker-thread-initializer2.ts"
    click RN "https://github.com/dazl-dev/engine/blob/main/packages/runtime-node/src/ws-node-host.ts"

    click EB1 "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/esbuild-build-end-plugin.ts"
    click EB2 "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/esbuild-dynamic-entry-plugin.ts"
    click EB3 "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/esbuild-html-plugin.ts"
    click CreateEP "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/create-entrypoints.ts"
    click WebEntry "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/entrypoint/create-web-entrypoint.ts"
    click NodeEntry "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/entrypoint/create-node-entrypoint.ts"

    click Dashboard "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/dashboard/dashboard.ts"
    click Dashboard "https://github.com/dazl-dev/engine/blob/main/packages/engine-cli/src/launch-dashboard-server.ts"
    click Dashboard "https://github.com/dazl-dev/engine/blob/main/build-dashboard.js"

    click Iframe "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/initializers/iframe.ts"
    click WebWorker "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/initializers/webworker.ts"
    click SocketSrv "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/initializers/socket-server.ts"
    click UniWorker "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/hosts/universal-worker-host.ts"
    click WSClient "https://github.com/dazl-dev/engine/blob/main/packages/core/src/com/hosts/ws-client-host.ts"

    %% Styles
    classDef green fill:#d4f8d4,stroke:#4caf50,color:#055;
    classDef blue fill:#d0e8ff,stroke:#2196f3,color:#034;
    classDef orange fill:#ffe0b2,stroke:#fb8c00,color:#663;
    classDef gray fill:#f5f5f5,stroke:#9e9e9e,color:#333;
```
