# parnoldx/nasctui architecture

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

- Interactive diagram: https://gitdiagram.com/parnoldx/nasctui
- Repository: https://github.com/parnoldx/nasctui

## Overview

##### Project Type and Purpose
– Type: A standalone terminal-UI (TUI) calculator application.
– Purpose: Let users type free-form math expressions, compute results via libqalculate, display them in real time, and maintain reactive dependency tracking with undo/redo.

##### File Structure
– src/
- main.go & main_test.go: Application entry point, top-level orchestration and test harness.
- calculator.go + calc_wrapper.cpp: cgo bridge between Go and the C++ libqalculate library.
- input.go, input.txt, events.go: Parse and track user keystrokes, map them to events.
- undo.go: History management, undo/redo stacks.
- help.txt: Inline user documentation.
– Root-level
- Makefile & install.sh: Build and install scripts.
- .github/workflows: CI/CD for build and release.
- README.md, SPEC.md: Project description and specifications.

##### README for Additional Insights
– Powered by libqalculate (external C++ library).
– Core features: real-time evaluation, unit conversion, multi-line persistent history, autocomplete, undo/redo.
– No external database or network services; all computation is local.

##### Main Components & Their Relationships
a. User Interface Layer (src/ui.go + rendering + style + ui_utils)
– Renders input pane, output pane, menus, help.
– Captures raw keyboard events via events.go and forwards to the Input Handler.
b. Input & Event Processing (src/input.go + events.go)
– Tokenizes keystrokes, manages multiple lines, identifies commands (e.g., undo/redo).
– Emits “expression ready” events.
c. Core Calculation Layer
– calculator.go invokes functions in calc_wrapper.cpp via cgo.
– calc_wrapper.cpp wraps calls to libqalculate API, performing parsing, evaluation, unit conversion, variable binding.
d. libqalculate (external C++ library)
– Performs actual math parsing and evaluation.
e. Undo/Redo Manager (src/undo.go)
– Listens to state-change events, pushes snapshots or deltas to history stacks.
f. Orchestrator/Main Loop (src/main.go)
– Initializes UI, input, calculation layer, and history manager.
– Listens to events in a loop and routes data between UI, Input Handler, and Calculator.

##### Architectural Patterns & Design Principles
– Layered architecture: UI → Input/Event → Business Logic (Calculator & Undo) → External Library.
– Event-driven design: decouples keystroke capture, parsing, calculation, and rendering.
– cgo boundary: isolates C++ code into calc_wrapper.cpp to keep Go code pure and testable.
– Single-process, in-memory state; no external persistence layer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    UI["UI Layer\n(src/ui.go, rendering.go, style.go, ui_utils.go)"]:::go
    Input["Input/Event Processor\n(src/input.go, events.go)"]:::go
    Orch["Orchestrator/Main Loop\n(src/main.go)"]:::go
    Calc["Core Calculator\n(src/calculator.go)"]:::go
    Wrap["C++ Wrapper\n(src/calc_wrapper.cpp)"]:::cpp
    Lib["libqalculate\n(external C++ library)"]:::external
    Undo["Undo/Redo Manager\n(src/undo.go)"]:::go
    CI["Build & CI/CD\n(Makefile, install.sh, workflows)"]:::ci

    UI -->|"RawKeystroke"| Input
    Input -->|"ExpressionReady"| Orch
    Orch -->|"ExpressionString"| Calc
    Calc -->|"cgoCall"| Wrap
    Wrap -->|"APIcall"| Lib
    Lib -->|"Result"| Wrap
    Wrap -->|"Result"| Calc
    Calc -->|"Result"| Orch
    Orch -->|"RenderUpdate"| UI

    Calc -->|"StateChange"| Undo
    Undo -->|"UndoRedoCommand"| Orch

    CI -.-> Orch

    click UI "https://github.com/parnoldx/nasctui/blob/master/src/ui.go"
    click Input "https://github.com/parnoldx/nasctui/blob/master/src/input.go"
    click Orch "https://github.com/parnoldx/nasctui/blob/master/src/main.go"
    click Calc "https://github.com/parnoldx/nasctui/blob/master/src/calculator.go"
    click Wrap "https://github.com/parnoldx/nasctui/blob/master/src/calc_wrapper.cpp"
    click Undo "https://github.com/parnoldx/nasctui/blob/master/src/undo.go"
    click CI "https://github.com/parnoldx/nasctui/tree/master/Makefile"

    classDef go fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef cpp fill:#FFA500,stroke:#000,stroke-width:1px
    classDef external fill:#FF6347,stroke:#000,stroke-width:1px
    classDef ci fill:#D3D3D3,stroke:#000,stroke-width:1px
```
