# lightning-js/blits architecture

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

- Interactive diagram: https://gitdiagram.com/lightning-js/blits
- Repository: https://github.com/lightning-js/blits

## Overview

##### And isolate the core components
- Core Framework Library – The heart of Blits is located within the src directory. This includes:
– Application and Component lifecycles (src/application.js, src/component.js)
– The component base and setup modules (src/component/base and src/component/setup)
– Reactivity system (src/lib/reactivity, src/lib/reactivityguard)
– Template parsing (src/lib/templateparser) and precompilation (src/lib/precompiler)
– Event handling, logging, and utility functions (src/lib/eventListeners, src/lib/utils, src/lib/log)
- Rendering & Engine Integration – The src/engines folder (especially src/engines/L3) shows integration layers with the Lightning 3 Renderer, including shader and font loaders.
- Plugin System – The src/plugins directory holds plugins for app state, language, logging, and theming. This is an extensibility point for customization.
- CLI/Tooling & Application scaffolding – The bin/ folder and packages (packages/create-app and packages/create-blits) reinforce that Blits provides commands to generate new apps and boilerplate projects.
- Additional Utilities – Include public assets, helper modules, and integration with tooling like Vite in the vite directory.

##### Relationships and Interactions
- The Framework Core (application, component, reactivity, parser) drives user applications.
- Components interact with the Lightning 3 rendering engine (via the engines submodules) and communicate using event systems and the reactive data layer.
- The Router and Transition modules work together to manage navigation, animated scene changes, and state transitions.
- Plugins integrate into the core providing additional functionalities such as global app state, themes, and multilingual support.
- The CLI modules (in bin and packages) serve as entry points for project creation and scaffolding, interfacing with the core libraries to set up new projects.
- Vite integrations and build tooling (in the vite folder) handle bundling, preprocessing, and compiling the XML–style templates along with type-checking and other development concerns.

##### Architectural Patterns & Design Principles
- Modularity: The project is divided neatly among core functionalities, helper libraries, and extensibility points.
- Layered architecture: There is a clear separation between the UI (component/template), business logic (reactivity, state management), and communication with the rendering engine.
- Extensibility: The plugin system and CLI scaffolding packages highlight a design aimed at easy customization and extension.
- MVC/MVVM hints: While not a classic implementation, the separation of component logic, routing, and reactivity indicates patterns similar to modern front–end frameworks.

##### Final Steps
- Drill down into the core runtime:
– Left section: Core Libraries (application, components, reactivity, template parser).
– Center: Routing and transition management.
– Right section: Engine integration and plugin modules.
- Overlay the build and toolchain integrations (bin, vite, docs) as supporting services that interact with the core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Scaffolding Layer
    subgraph "CLI & Scaffolding"
        P["CLI Tools"]:::cli
        Q["Scaffolding: create-app"]:::cli
        Q2["Scaffolding: create-blits"]:::cli
    end

    %% Core Framework Library
    subgraph "Core Framework Library"
        A["Application Lifecycle"]:::core
        B["Component Lifecycle"]:::core
        C["Component Base"]:::core
        D["Component Setup"]:::core
        E["Reactivity"]:::core
        F["Reactivity Guard"]:::core
        G["Template Parser"]:::core
        H["Precompiler"]:::core
        I["Event Listeners"]:::core
        J["Logging"]:::core
        K["Utilities"]:::core
    end

    %% Routing & Transitions Layer
    subgraph "Routing & Transitions"
        L["Router"]:::router
        M["Transitions"]:::router
    end

    %% Rendering & Plugin Layer
    subgraph "Rendering & Plugins"
        N["Engine Integration (Lightning 3)"]:::engine
        O["Plugin System"]:::engine
    end

    %% Build & Tooling Layer
    subgraph "Build & Tooling"
        R["Vite Integration & Public Assets"]:::build
    end

    %% Connections between layers
    P -->|"scaffolds"| A
    Q -->|"scaffolds"| A
    Q2 -->|"scaffolds"| A

    A -->|"triggersRouting"| L
    A -->|"rendersViaEngine"| N
    A -->|"integratesPlugins"| O

    E -->|"feedsReactivity"| B
    L -->|"managesTransitions"| M

    R -->|"bundles"| A

    %% Styling classes
    classDef cli fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef router fill:#abebc6,stroke:#27ae60,stroke-width:2px;
    classDef engine fill:#f5b7b1,stroke:#c0392b,stroke-width:2px;
    classDef build fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;

    %% Click Events
    click A "https://github.com/lightning-js/blits/blob/master/src/application.js"
    click B "https://github.com/lightning-js/blits/blob/master/src/component.js"
    click C "https://github.com/lightning-js/blits/tree/master/src/component/base"
    click D "https://github.com/lightning-js/blits/tree/master/src/component/setup"
    click E "https://github.com/lightning-js/blits/tree/master/src/lib/reactivity"
    click F "https://github.com/lightning-js/blits/tree/master/src/lib/reactivityguard"
    click G "https://github.com/lightning-js/blits/tree/master/src/lib/templateparser"
    click H "https://github.com/lightning-js/blits/tree/master/src/lib/precompiler"
    click I "https://github.com/lightning-js/blits/blob/master/src/lib/eventListeners.js"
    click J "https://github.com/lightning-js/blits/blob/master/src/lib/log.js"
    click K "https://github.com/lightning-js/blits/blob/master/src/lib/utils.js"
    click L "https://github.com/lightning-js/blits/tree/master/src/router"
    click M "https://github.com/lightning-js/blits/tree/master/src/router/transitions"
    click N "https://github.com/lightning-js/blits/tree/master/src/engines/L3"
    click O "https://github.com/lightning-js/blits/tree/master/src/plugins"
    click P "https://github.com/lightning-js/blits/tree/master/bin"
    click Q "https://github.com/lightning-js/blits/tree/master/packages/create-app"
    click Q2 "https://github.com/lightning-js/blits/tree/master/packages/create-blits"
    click R "https://github.com/lightning-js/blits/tree/master/vite"
```
