# gyu-chul/hab-legacy architecture

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

- Interactive diagram: https://gitdiagram.com/gyu-chul/hab-legacy
- Repository: https://github.com/gyu-chul/hab-legacy

## Overview

##### Project type and purpose
- HAB is an open-source, desktop GUI tool for visualizing and interactively debugging Python program execution.
- It combines a compiler-style pipeline (lexical, syntax, semantic analysis, runtime) with a graphical interface and code-editing surface.

##### File structure
- Top-level build and config: CMakeLists.txt, .env, .gitignore, LICENSE, main.cpp, script.py
- & lib folders hold C++ headers and helper libraries
- src/ folder subdivides into:
- code-editor (GUI text editor component)
- window (application window management)
- lexical-analyzer (Scanner submodule)
- syntax-analyzer
- semantic-analyzer
- runtime (executes interpreted instructions, steps through code)
- datas (data model for runtime, includes Object/number types)
- graphic-maker (builds visual scene)
- graphic-utility (drawing primitives, helper routines)

##### README for additional insights
- Core goal: “visually expose the execution process of the source code”
- Interactive: “allows source code modification with a mouse in a GUI area”
- Written in C++ with a Python-execution backend (driven by script.py)

##### Main components and their relationships
a. Components:
- Code Editor (src/code-editor)
- GUI Window Manager (src/window)
- Compiler Pipeline:
- Lexical Analyzer (src/lexical-analyzer)
- Syntax Analyzer (src/syntax-analyzer)
- Semantic Analyzer (src/semantic-analyzer)
- Runtime Engine (src/runtime)
- Data Model (src/datas)
- Visualization Engine:
- Graphic Utility (src/graphic-utility)
- Graphic Maker (src/graphic-maker)
- Orchestration Script (script.py)
- External Python Interpreter
- Build System (CMake)

b. Interactions and data flow:
1. User types or edits code in the Code Editor.
2. On compile/step command, editor sends source text to Lexical Analyzer.
3. Tokens flow into Syntax Analyzer → AST.
4. AST is checked by Semantic Analyzer → annotated IR.
5. IR is handed to Runtime Engine, which interfaces with the Python Interpreter or executes an internal bytecode.
6. Runtime Engine emits state changes (stack, heap, variable values) into the Data Model.
7. Data Model updates feed into the Graphic Utility for drawing primitives.
8. Graphic Maker composes those primitives into visual elements (e.g., call stacks, variable tables).
9. Visualization frames are rendered inside the GUI Window.
10. script.py can launch or reload the interpreter session, manage hot-reload of code.

c. Architectural patterns & design principles:
- Compiler pipeline (lex → parse → semantic check → runtime)
- Model-View-Controller (Model = Data Model, View = Graphic Maker/Utility + Window, Controller = Code Editor + Runtime events)
- Event-driven GUI (user actions trigger analysis & visualization updates)
- Modular separation (each analyzer in its own directory, clear data flows)

d. Key technologies & libraries:
- C++17 (assumed) with CMake build
- Python 3 interpreter integration via script.py
- GUI toolkit (e.g., Qt, SDL, or custom canvas – inspect CMake for actual choice)
- Custom Scanner, Parser, Semantic modules in C++
- Runtime engine with hooks into Data Model objects

##### Details to capture
- Directory/module names next to each block (e.g., “Lexical Analyzer (src/lexical-analyzer)”).
- Build integration via CMake if relevant for deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interaction
    User["User (mouse edits, step/run)"]:::user

    %% Frontend components
    CodeEditor["Code Editor<br/>(src/code-editor)"]:::frontend
    GUIWindow["GUI Window Manager<br/>(src/window)"]:::frontend

    %% Analysis Engine pipeline
    subgraph "Analysis Engine"
        direction TB
        Lexical["Lexical Analyzer<br/>(src/lexical-analyzer)"]:::pipeline
        Scanner["Scanner<br/>(src/lexical-analyzer/Scanner)"]:::pipeline
        Syntax["Syntax Analyzer<br/>(src/syntax-analyzer)"]:::pipeline
        Semantic["Semantic Analyzer<br/>(src/semantic-analyzer)"]:::pipeline
    end

    %% Runtime & Data Model
    Runtime["Runtime Engine<br/>(src/runtime)"]:::runtimeorange
    subgraph "Data Model"
        direction TB
        DataModelCore["Data Model<br/>(src/datas)"]:::runtimeorange
        ObjectTypes["Object Types<br/>(src/datas/Object)"]:::runtimeorange
        NumberType["Number Type<br/>(src/datas/Object/number)"]:::runtimeorange
    end

    %% Visualization Engine
    subgraph "Visualization Engine"
        direction TB
        GraphicUtility["Graphic Utility<br/>(src/graphic-utility)"]:::visualpurple
        GraphicMaker["Graphic Maker<br/>(src/graphic-maker)"]:::visualpurple
    end

    %% External integrations
    Script["Orchestration Script<br/>(script.py)"]:::externalgray
    PythonInterp["External Python Interpreter"]:::externalgray
    CMake["Build System (CMake)<br/>(CMakeLists.txt)"]:::externalgray

    %% Data flows
    User -->|"edit/step command"| CodeEditor
    CodeEditor -->|"source code"| Lexical
    Lexical -->|"scanned tokens"| Scanner
    Scanner -->|"tokens"| Syntax
    Syntax -->|"AST"| Semantic
    Semantic -->|"annotated IR"| Runtime
    Runtime -->|"state changes"| DataModelCore
    DataModelCore -->|"model data"| GraphicUtility
    GraphicUtility -->|"draw primitives"| GraphicMaker
    GraphicMaker -->|"visual frames"| GUIWindow
    Runtime -->|"execute instructions"| PythonInterp
    Script -->|"launch/hot-reload"| PythonInterp
    Script -->|"manage session"| Runtime
    GUIWindow -->|"render frames & callbacks"| CodeEditor

    %% Data Model internal flows
    DataModelCore --> ObjectTypes
    ObjectTypes --> NumberType

    %% Click events
    click CodeEditor "https://github.com/gyu-chul/hab-legacy/tree/main/src/code-editor"
    click GUIWindow "https://github.com/gyu-chul/hab-legacy/tree/main/src/window"
    click Lexical "https://github.com/gyu-chul/hab-legacy/tree/main/src/lexical-analyzer"
    click Scanner "https://github.com/gyu-chul/hab-legacy/tree/main/src/lexical-analyzer/Scanner"
    click Syntax "https://github.com/gyu-chul/hab-legacy/tree/main/src/syntax-analyzer"
    click Semantic "https://github.com/gyu-chul/hab-legacy/tree/main/src/semantic-analyzer"
    click Runtime "https://github.com/gyu-chul/hab-legacy/tree/main/src/runtime"
    click DataModelCore "https://github.com/gyu-chul/hab-legacy/tree/main/src/datas"
    click ObjectTypes "https://github.com/gyu-chul/hab-legacy/tree/main/src/datas/Object"
    click NumberType "https://github.com/gyu-chul/hab-legacy/tree/main/src/datas/Object/number"
    click GraphicUtility "https://github.com/gyu-chul/hab-legacy/tree/main/src/graphic-utility"
    click GraphicMaker "https://github.com/gyu-chul/hab-legacy/tree/main/src/graphic-maker"
    click Script "https://github.com/gyu-chul/hab-legacy/blob/main/script.py"
    click CMake "https://github.com/gyu-chul/hab-legacy/blob/main/CMakeLists.txt"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef pipeline fill:#90EE90,stroke:#000;
    classDef runtimeorange fill:#FFD580,stroke:#000;
    classDef visualpurple fill:#D8BFD8,stroke:#000;
    classDef externalgray fill:#D3D3D3,stroke:#000;
    classDef user fill:#E0FFFF,stroke:#000;
```
