# xdmanus1/hpy-framework architecture

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

- Interactive diagram: https://gitdiagram.com/xdmanus1/hpy-framework
- Repository: https://github.com/xdmanus1/hpy-framework

## Overview

##### Project type and purpose
- Project Type: An open-source CLI tool and library for scaffolding, building, serving, and live-reloading Brython-based web applications.
- Purpose: Read a root directory of `.hpy`+Python+static files; parse templates and Brython code; produce standard HTML/JS output; serve locally with live reload.

##### File structure
- Top-level CLI entry point: `hpy_tool.py` and `pyproject.toml`/`setup.py`.
- Core library in `hpy_core/` with submodules:
- `cli.py` – command definitions (`init`, `build`, `serve`, `watch`).
- `config.py` – loads `hpy.toml`.
- `parsing.py` – parses `.hpy` templates, `<python>` blocks, styles, head/body fragments.
- `building.py` – assembles pages into final HTML using `_app.html` and `_layout.hpy`, collects assets.
- `serving.py` – HTTP server for dev mode.
- `watching.py` – file-watch + live-reload orchestration.
- `project_templates/` – scaffolding templates for `hpy init`.
- Documentation site in `docs/` and example projects in `examples/`.
- Tests in `tests/`.

##### README for additional insights
- Core features: project init, config, directory-based workflow, layout support, asset handling, Brython integration, dev/prod build modes, serve/watch.
- Workflow: read `hpy.toml` → identify input/output dirs → copy static → parse layout & pages → inject into shell → write output → (optionally) serve or watch.
- Technologies: Python CLI (Typer), `watchfiles`, `tomli`, Brython (client).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI and Config
    subgraph "CLI & Configuration Layer"
        direction TB
        HT["hpy_tool.py"]:::cli
        CLI["cli.py\n(init, build, serve, watch)"]:::cli
        CFG["config.py\n(load hpy.toml)"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine" 
        direction TB
        PARS["parsing.py\n(parse .hpy templates)"]:::core
        BLD["building.py\n(assemble HTML, assets)"]:::core
        SRV["serving.py\n(dev HTTP server)"]:::core
        WCH["watching.py\n(file-watch & live-reload)"]:::core
        INIT["init.py\n(project scaffolding)"]:::core
        TPL["project_templates/\n(scaffold templates)"]:::core
    end

    %% File System
    subgraph "File System" 
        direction TB
        FS_IN["Input Directory\n(src/, .hpy, static)"]:::io
        FS_OUT["Output Directory\n(dist/, build/)"]:::io
    end

    %% External Browser
    BROWSER["Browser"]:::external

    %% Flows
    HT -->|invokes| CLI
    CLI -->|reads config| CFG
    CLI -->|init command| INIT
    INIT -->|uses templates| TPL
    CLI -->|build/watch/serve| PARS
    PARS -->|read templates and input| FS_IN
    PARS -->|output data| BLD
    BLD -->|write files| FS_OUT
    CLI -->|serve command| SRV
    SRV -->|serves files| FS_OUT
    SRV -->|HTTP| BROWSER
    CLI -->|watch command| WCH
    WCH -->|on change| PARS
    WCH -->|trigger rebuild| BLD
    WCH -->|send reload| BROWSER

    %% Click Events
    click HT "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_tool.py"
    click CLI "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/cli.py"
    click CFG "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/config.py"
    click PARS "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/parsing.py"
    click BLD "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/building.py"
    click SRV "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/serving.py"
    click WCH "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/watching.py"
    click INIT "https://github.com/xdmanus1/hpy-framework/blob/main/hpy_core/init.py"
    click TPL "https://github.com/xdmanus1/hpy-framework/tree/main/hpy_core/project_templates/"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#E0F7E9,stroke:#028A0F,color:#027A0F;
    classDef io fill:#FFEED0,stroke:#D97706,color:#B45309;
    classDef external fill:#F0F0F0,stroke:#999999,color:#666666;
```
