# newcat/baklavajs architecture

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

- Interactive diagram: https://gitdiagram.com/newcat/baklavajs
- Repository: https://github.com/newcat/baklavajs

## Overview

##### Project Type and Purpose
- BaklavaJS is a modular, plugin-based graph/node editor ecosystem for the browser, written in TypeScript and published as multiple npm packages (monorepo managed with Yarn, Lerna, and Nx).
- Core functionality lives in `@baklavajs/core`, with optional plugins (`engine`, `events`, `interface-types`, `renderer-vue`, `themes`) that extend or render the editor.

##### File Structure
- Top-level:
- Configuration & CI: `.github/workflows/*`, `lerna.json`, `nx.json`, `package.json`, `tsconfig.json`, `typedoc.json`
- Documentation: `docs/` (VitePress site with guides, API docs, examples)
- Packages: `packages/` – each subfolder is an npm package:
– `core` – graph API, nodes, events, editor model
– `engine` – execution engines (dependency, forward)
– `events` – event system & hooks
– `interface-types` – type-safe node interface definitions & converters
– `renderer-vue` – Vue components to display and interact with the graph editor
– `themes` – Sass/CSS theme bundles
– `full` – bundle combining core + all plugins
- Build/Test configurations per package: `tsconfig.json`, `jest.config.js`, `build scripts`.

##### README Insights
- Describes high-level architecture: core + plug-and-play plugins.
- Emphasizes extensibility and type safety.
- Lists available plugins and their roles.

##### Main Components
a. Monorepo Management Layer
- Yarn Workspaces / Lerna / Nx – orchestrates builds, versioning, publishing.
b. Core Package (`@baklavajs/core`)
- Graph model, node definitions, connection logic, event hooks API.
c. Plugin Packages
- Engine Plugin (`@baklavajs/engine`) – computation strategies, topological sort.
- Event System (`@baklavajs/events`) – subscribable hooks, proxies.
- Interface Types (`@baklavajs/interface-types`) – typed interfaces, converters.
- Vue Renderer (`@baklavajs/renderer-vue`) – UI layer (components, commands, context menus).
- Themes (`@baklavajs/themes`) – styling engine for renderer.
- Full Bundle (`baklavajs` / `packages/full`) – pre-bundled core + all plugins.
d. Documentation Site (VitePress)
- Pulls TS doc comments, Markdown guides.
e. CI/CD Pipelines
- Build, test, bundle and npm publish workflows.

##### Relationships and Interactions
- Core is the foundation: every plugin imports and extends core APIs.
- Engine plugin consumes core’s graph & node definitions to execute computations.
- Events plugin provides hook system used by core and engine for lifecycle events.
- Interface-types plugin attaches metadata to core’s node interfaces and integrates with engine’s converters.
- Renderer-vue plugin renders core’s graph model in the browser; depends on core, events, interface-types, and themes.
- Themes plugin supplies CSS/SCSS styling imported by renderer-vue.
- Full bundle re-exports core and all plugins in one package for easy installation.
- Documentation site is a separate consumer of the packages for examples and API docs.
- CI/CD orchestrates builds and publishing for all packages.

##### Architectural Patterns & Principles
- Monorepo with isolated, versioned packages (Lerna + Yarn Workspaces + Nx).
- Plugin architecture: core defines interfaces; plugins add cross-cutting concerns (engine, types, UI, styles).
- Separation of concerns: model (core), execution (engine), typing (interface-types), UI (renderer-vue), styling (themes), docs.
- Dependency inversion: core defines abstractions, plugins implement or extend them.
- Type safety enforced via TypeScript across all layers.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Boundary
    subgraph "Monorepo (BaklavaJS)" 
        direction TB
        %% Management Layer
        subgraph "Management & CI" 
            direction TB
            Lerna["Lerna (lerna.json)"]:::tooling
            Nx["Nx (nx.json)"]:::tooling
            Yarn["Yarn ( .yarnrc.yml / .yarn )"]:::tooling
            Workflows["CI Workflows (.github/workflows/)"]:::tooling
        end

        %% Core Package
        Core["@baklavajs/core"]:::foundation

        %% Plugin Packages
        subgraph "Plugins" 
            direction TB
            Engine["@baklavajs/engine"]:::plugin
            Events["@baklavajs/events"]:::plugin
            Types["@baklavajs/interface-types"]:::plugin
            Renderer["@baklavajs/renderer-vue"]:::ui
            Themes["@baklavajs/themes"]:::plugin
            Full["Full Bundle (baklavajs)"]:::plugin
        end
    end

    %% External Consumer
    Docs["Documentation Site (docs/)"]:::docs

    %% CI/CD orchestrates
    CI["CI/CD Pipeline"]:::tooling

    %% Dependencies
    Engine -->|imports| Core
    Events -->|hooks into| Core
    Types -->|extends| Core
    Renderer -->|renders| Core
    Renderer -->|uses| Events
    Renderer -->|uses| Types
    Renderer -->|styles from| Themes
    Full -->|re-exports| Core
    Full -->|re-exports| Engine
    Full -->|re-exports| Events
    Full -->|re-exports| Types
    Full -->|re-exports| Renderer
    Full -->|re-exports| Themes
    Docs -->|consumes| Core
    Docs -->|consumes| Engine
    Docs -->|consumes| Events
    Docs -->|consumes| Types
    Docs -->|consumes| Renderer
    Docs -->|consumes| Themes
    CI -->|builds/tests/publishes| Core
    CI -->|builds/tests/publishes| Engine
    CI -->|builds/tests/publishes| Events
    CI -->|builds/tests/publishes| Types
    CI -->|builds/tests/publishes| Renderer
    CI -->|builds/tests/publishes| Themes
    CI -->|builds/tests/publishes| Full

    %% Click Events
    click Lerna "https://github.com/newcat/baklavajs/blob/master/lerna.json"
    click Nx "https://github.com/newcat/baklavajs/blob/master/nx.json"
    click Yarn "https://github.com/newcat/baklavajs/blob/master/.yarnrc.yml"
    click Workflows "https://github.com/newcat/baklavajs/tree/master/.github/workflows/"
    click Core "https://github.com/newcat/baklavajs/tree/master/packages/core/"
    click Engine "https://github.com/newcat/baklavajs/tree/master/packages/engine/"
    click Events "https://github.com/newcat/baklavajs/tree/master/packages/events/"
    click Types "https://github.com/newcat/baklavajs/tree/master/packages/interface-types/"
    click Renderer "https://github.com/newcat/baklavajs/tree/master/packages/renderer-vue/"
    click Themes "https://github.com/newcat/baklavajs/tree/master/packages/themes/"
    click Full "https://github.com/newcat/baklavajs/tree/master/packages/full/"
    click Docs "https://github.com/newcat/baklavajs/tree/master/docs/"

    %% Styles
    classDef foundation fill:#e0f7fa,stroke:#006064,stroke-width:1px
    classDef plugin fill:#e8f5e9,stroke:#2e7d32,stroke-width:1px
    classDef ui fill:#fff3e0,stroke:#ef6c00,stroke-width:1px
    classDef tooling fill:#eceff1,stroke:#455a64,stroke-width:1px
    classDef docs fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px
```
