# pixeleecode/impulse architecture

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

- Interactive diagram: https://gitdiagram.com/pixeleecode/impulse
- Repository: https://github.com/pixeleecode/impulse

## Overview

##### Project type and purpose
- This is an open-source, full-stack micro-framework (“Impulse”) combining PHP (backend) and JavaScript (frontend) to build reactive, component-driven UIs without a heavy frontend stack.
- It exposes a tiny JS runtime (public/impulse.js) that turns annotated DOM elements into AJAX-driven, stateful PHP components.

##### Main architectural layers
A. Client (Browser)
- UI components annotated with impulse:* attributes
- The impulse.js runtime attaches listeners, serializes events, and applies partial DOM updates.
B. AJAX Gateway
- public/impulse.php (or your app’s symlink) is the single endpoint that receives all component requests.
C. PHP Core
1. Front controller: loads composer autoloader, reads impulse/config.json
2. ImpulseFactory → Instantiate the requested Component class (src/Components or user namespace)
3. Component Resolver / Config (src/Core/ComponentResolver, Config)
4. State & Method Collections (src/Collections) manage component state, queued actions, watchers
5. Handler Layer (src/Core/Handler/AjaxDispatcher) invokes the PHP method annotated #[Action]
6. Renderer Layer (src/Rendering/BladeRenderer, TwigRenderer or inline from Component::template())
7. Response Builder: packages the updated HTML fragment and any metadata as JSON
D. Optional Extensibility Points
- Custom renderers via bin/impulse make:renderer → implement TemplateRendererInterface
- CLI commands for scaffolding (src/Commands/MakeRendererCommand, RendererConfigureCommand)
- Configurable template engine (Twig, Blade, etc.)

##### How these components interact (data flow)
1. User triggers event in browser (e.g., click, input) → impulse.js captures it
2. JS sends AJAX POST to /public/impulse.php with: component identifier, current state, action name, args
3. PHP gateway loads ImpulseFactory → resolves component class → hydrates state
4. AjaxDispatcher invokes the action method → mutates component state
5. Renderer re-renders only the DOM fragment marked data-impulse-part
6. JSON response returns new HTML snippet (plus any instruction tokens)
7. impulse.js receives JSON → patches the DOM fragment in place

##### Key architectural patterns and principles
- Component-based: each PHP class extends Core\Component, encapsulating state, actions, template, and style
- Partial rendering: “DOM diffless” updates by replacing only marked fragments
- Dependency inversion & extensibility: TemplateRendererInterface abstracts the rendering engine
- Single-responsibility: Handler, Resolver, Factory, Renderer each do one thing

##### Essential elements
- Extensibility: “Custom Renderer” implements TemplateRendererInterface

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        browser["Browser"]:::frontend
        runtime["public/impulse.js"]:::frontend
    end

    %% AJAX Gateway
    subgraph "AJAX Gateway"
        gateway["public/impulse.php"]:::gateway
    end

    %% Backend Core
    subgraph "Backend Core"
        factory["ImpulseFactory"]:::core
        resolver["ComponentResolver"]:::core
        config["Config"]:::core
        subgraph "State & Method Collections"
            compColl["ComponentCollection"]:::core
            methodColl["MethodCollection"]:::core
            stateColl["StateCollection"]:::core
            watcherColl["WatcherCollection"]:::core
        end
        handler["AjaxDispatcher"]:::core
        subgraph "Renderer Layer"
            blade["BladeRenderer"]:::core
            twig["TwigRenderer"]:::core
            tmplIntf["TemplateRendererInterface"]:::core
        end
        baseComp["Component (Base)"]:::core
    end

    %% User Components
    subgraph "User Components"
        userComps["src/Components"]:::extension
    end

    %% Extensibility & CLI
    subgraph "Extensibility"
        customR["MakeRendererCommand"]:::extension
        configR["RendererConfigureCommand"]:::extension
        cli["bin/impulse"]:::extension
        docs["docs/architecture.md"]:::extension
    end

    %% Data Flow
    browser -->|"annotated DOM & events"| runtime
    runtime -->|"AJAX POST: state+action"| gateway
    gateway -->|"load factory"| factory
    factory -->|"resolve component"| resolver
    factory -->|"load config"| config
    resolver -->|"instantiate class"| baseComp
    baseComp -->|"user code"| userComps
    factory -->|"hydrate state"| stateColl
    stateColl --> handler
    methodColl --> handler
    watcherColl --> handler
    handler -->|"invoke #[Action] method"| baseComp
    handler -->|"pass to renderer"| blade & twig & tmplIntf
    blade -->|"render HTML fragment"| gateway
    twig -->|"render HTML fragment"| gateway
    tmplIntf -->|"abstract render"| blade & twig
    gateway -->|"JSON response"| runtime
    runtime -->|"patch DOM"| browser

    %% Click Events
    click runtime "https://github.com/pixeleecode/impulse/blob/master/public/impulse.js"
    click gateway "https://github.com/pixeleecode/impulse/blob/master/public/impulse.php"
    click factory "https://github.com/pixeleecode/impulse/blob/master/src/ImpulseFactory.php"
    click resolver "https://github.com/pixeleecode/impulse/blob/master/src/Core/ComponentResolver.php"
    click config "https://github.com/pixeleecode/impulse/blob/master/src/Core/Config.php"
    click compColl "https://github.com/pixeleecode/impulse/blob/master/src/Collections/Collection/ComponentCollection.php"
    click methodColl "https://github.com/pixeleecode/impulse/blob/master/src/Collections/Collection/MethodCollection.php"
    click stateColl "https://github.com/pixeleecode/impulse/blob/master/src/Collections/Collection/StateCollection.php"
    click watcherColl "https://github.com/pixeleecode/impulse/blob/master/src/Collections/Collection/WatcherCollection.php"
    click handler "https://github.com/pixeleecode/impulse/blob/master/src/Core/Handler/AjaxDispatcher.php"
    click blade "https://github.com/pixeleecode/impulse/blob/master/src/Rendering/BladeRenderer.php"
    click twig "https://github.com/pixeleecode/impulse/blob/master/src/Rendering/TwigRenderer.php"
    click tmplIntf "https://github.com/pixeleecode/impulse/blob/master/src/Interfaces/TemplateRendererInterface.php"
    click baseComp "https://github.com/pixeleecode/impulse/blob/master/src/Core/Component.php"
    click userComps "https://github.com/pixeleecode/impulse/tree/master/src/Components/"
    click customR "https://github.com/pixeleecode/impulse/blob/master/src/Commands/MakeRendererCommand.php"
    click configR "https://github.com/pixeleecode/impulse/blob/master/src/Commands/RendererConfigureCommand.php"
    click cli "https://github.com/pixeleecode/impulse/tree/master/bin/impulse"
    click docs "https://github.com/pixeleecode/impulse/blob/master/docs/architecture.md"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#0288d1,color:#01579b;
    classDef gateway fill:#e8f5e9,stroke:#43a047,color:#1b5e20;
    classDef core fill:#eceff1,stroke:#90a4ae,color:#37474f;
    classDef extension fill:#fff9c4,stroke:#fbc02d,color:#f57f17;
```
