# bluefishjs/bluefish architecture

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

- Interactive diagram: https://gitdiagram.com/bluefishjs/bluefish
- Repository: https://github.com/bluefishjs/bluefish

## Overview

Based on our analysis of the file tree and README, this project is a monorepo that hosts a set of related packages under the “Bluefish” umbrella. In particular, there are two main packages – one for plain JavaScript (bluefish‑js) and one for Solid (bluefish‑solid) – which are tightly coupled: the js version depends on the Solid package. The project also includes a robust documentation site (built using VitePress), CI/CD configuration (GitHub Workflows), and a modern build system using Turbo and PNPM. The codebase is organized into clearly defined areas for source code, examples, experiments, and design reference, which suggests that the primary purpose is to provide a set of tools or libraries for building and visualizing diagrammatic or graphical UI components (as evidenced by many files related to marks, relations, layouts, and even a “chemistry” folder).

##### Main Components of the System
- Monorepo Container – Represent the top-level repository, indicating that it houses multiple packages and shared configurations (e.g., Turbo config, PNPM workspace, GitHub workflows, etc.).
- Packages:
- bluefish‑solid: This package is the more feature-rich one with many UI components (e.g., circle, ellipse, path, and layout components) and even specialized domains like “chemistry” and “graphLayered”. Indicate its internal structure (src, public, examples, experiments, stories) as sub-components.
- Documentation Site:
- A dedicated “docs” directory that contains not only markdown files but also the VitePress configuration and theming (with Tailwind). This should be shown as a distinct component that serves as both user guide and API reference.
- Build & Development Tools:
- Turbo Build System: Indicate the use of Turbo (via turbo.json) as the orchestrator for building the packages.
- Package Manager (PNPM) and Workspace: Represent how dependencies are managed across the monorepo.
- CI/CD and Automation:

##### Relationships and Interactions Between Components
- How documentation is built using files in the “docs” folder and depends on configuration (e.g., VitePress’s config file, tailwind config).
- Build process flow: Developer makes changes → uses Turbo (or pnpm dev) → packages are built (bluefish‑solid first, then bluefish‑js) → CI pipelines are triggered via GitHub Actions.

##### Architectural Patterns and Design Principles
- Modularity: The project separates concerns by splitting the core libraries into distinct packages and isolating documentation into its own directory.
- Dependency and Reusability: The bluefish‑js package relies on bluefish‑solid. Capture this interdependency clearly.
- Extensibility: The extensive folder structure in bluefish‑solid (with dedicated examples, experiments, and stories) suggests it’s designed to be experimented with and extended.
- Modern Build and Deployment: Relying on Turbo and GitHub Actions underscores an emphasis on automated builds and testing.

##### Technologies and Frameworks
- VitePress (docs engine) with custom theming and Tailwind CSS.
- Turbo (for orchestrating the build).
- PNPM (package manager) and a mono-repo workspace.
- TypeScript (through .ts/.tsx files in the source code).
- Likely SolidJS for bluefish‑solid components.

##### Elements
- Data flow between the packages (especially the dependency of bluefish‑js on bluefish‑solid)
- Process flow from building, testing, and deployment.
- Libraries versus configuration/automation components.
- Source code (inside packages) versus documentation.

##### Putting It All Together
- Off to one side, include a “Documentation Engine” node that reflects the VitePress site built from the “docs” folder.
- At the bottom or side, add a “Pipeline” section showing the build process (turbo build, pnpm install, GitHub workflows) that ties the whole system together.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Monorepo Root"]:::monorepo

    subgraph "Packages"
        S["bluefish‑solid Package"]:::package
        S1["src"]:::package
        S2["public"]:::package
        S3["examples"]:::package
        S4["experiments"]:::package
        S5["stories"]:::package
        J["bluefish‑js Package"]:::package

        S --> S1
        S --> S2
        S --> S3
        S --> S4
        S --> S5
    end

    D["Documentation (VitePress)"]:::docs
    C["CI/CD (GitHub Workflows)"]:::ci
    X["Build System (Turbo & PNPM)"]:::build

    subgraph "Dev/Build Pipeline"
        E["Developer"]:::pipeline
        F["Local Build(pnpm_dev/Turbo)"]:::pipeline
        G["Build_Order:bluefish‑solid=>bluefish‑js"]:::pipeline
        H["CI/CD_Trigger"]:::pipeline
    end

    %% Monorepo container relationships
    A -->|"contains"| S
    A -->|"contains"| D
    A -->|"contains"| C
    A -->|"contains"| X

    %% Package dependency
    J -->|"depends_on"| S

    %% Build pipeline flow
    E -->|"initiates"| F
    X -->|"enables"| F
    F -->|"orders_build"| G
    G -->|"triggers"| H
    H -->|"runs"| C

    %% Click Events
    click A "https://github.com/bluefishjs/bluefish/blob/main/package.json"
    click S "https://github.com/bluefishjs/bluefish/tree/main/packages/bluefish-solid"
    click J "https://github.com/bluefishjs/bluefish/tree/main/packages/bluefish-js"
    click D "https://github.com/bluefishjs/bluefish/tree/main/docs"
    click C "https://github.com/bluefishjs/bluefish/tree/main/.github/workflows"
    click X "https://github.com/bluefishjs/bluefish/blob/main/turbo.json"

    %% Styles
    classDef monorepo fill:#b3cde0,stroke:#03396c,stroke-width:2px;
    classDef package fill:#ccebc5,stroke:#006400,stroke-width:2px;
    classDef docs fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef ci fill:#fdd,stroke:#a00,stroke-width:2px;
    classDef build fill:#d9d9d9,stroke:#666,stroke-width:2px;
    classDef pipeline fill:#ffd700,stroke:#aa0,stroke-width:2px;
```
