# shapoco/calctus architecture

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

- Interactive diagram: https://gitdiagram.com/shapoco/calctus
- Repository: https://github.com/shapoco/calctus

## Overview

##### Project Type and Purpose
- Calctus is a desktop calculator application (Windows Forms-based) with advanced numerical and graphical capabilities.
- Its purpose is to allow users to enter mixed-format expressions (decimal, hexadecimal, binary, SI-prefixed, etc.), evaluate calculations, plot graphs, and even call external scripts as functions.
- The README highlights features like syntax highlighting, auto-completion, a full suite of built-in and user-defined functions, and methods for numerical equation solving (Newton’s method).

##### Analyzing the File Structure
- The project is organized into several key directories. For example:
- The “Calctus” directory holds the core engine and application entry files (Program.cs).
- “Calctus/UI” and its subdirectory “Sheets” contain the Windows Forms UI components (including MainForm, GraphForm, custom controls, settings dialogs, etc.).
- The “Windows” directory provides Windows-specific functionalities (e.g., ClipboardListener, StartupShortcut, WinUser), which integrate OS-level features.
- Additional files such as App.config, solution and project files (.sln, .csproj), and configuration resources support build and deployment.
- Such a breakdown suggests a clear separation of concerns between the computation logic (parsing, evaluating, formatting, etc.), presentation (UI forms and dialogs), and integration with Windows platform features.

a. Main Components:
- UI Layer: Windows Forms-based User Interface including MainForm, various dialogs, and interactive components (Sheets, Graph panels, settings windows).
- Core Calculation Engine:
- Parser Module: Converts user-entered string expressions into an abstract syntax tree. (See Calctus/Model/Parsers)
- Expression and Evaluator Modules: Responsible for constructing and evaluating expressions. (Calctus/Model/Expressions and Evaluations)
- Functions and Mathematical Modules: Houses built-in functions (and user-defined ones), mathematical operations (including Newton’s method). (Calctus/Model/Functions and Mathematics)
- Formats Module: Deals with different numeric representations and conversion between decimal, hexadecimal, binary, SI units, etc. (Calctus/Model/Formats)
- Graph & Plotting Module: Provides functionality to plot mathematical graphs. (Calctus/Model/Graphs)
- External Integration Module:
- Scripting and External Function Calls: Enables external scripts (e.g., Python) to be used as functions within the calculator.
- Windows Integration: Modules for handling OS-specific interactions (ClipboardListener, StartupShortcut).

b. Determining Relationships and Interactions:
- The UI layer receives user input (expressions, function calls, etc.) and passes these to the Core Calculation Engine.
- The Parser transforms the input into an Abstract Syntax Tree (AST), which is then processed by the Evaluator.
- The Evaluator incorporates the Functions, Formats, and Mathematics modules to compute results which are then returned to the UI.
- The Graph module is called when the user opts for plotting based on evaluated functions.
- External Script Call support integrates into the function execution pipeline, invoking external interpreters as needed.
- Windows Integration components ensure that UI and application behavior conforms to Windows system events (clipboard monitoring, startup management).

c. Highlighting Architectural Patterns and Design Principles:
- The project implements a layered architecture: clear separation between presentation (UI) and business logic (core engine).
- Modular design is evident from the distinct “Model” folders for Expressions, Evaluations, Functions, etc., supporting maintainability and extensibility.
- Use of specialized modules for parsing and evaluation indicates that the application likely employs common compiler design patterns (lexer, parser, AST, evaluator).
- The integration of external scripts suggests a plugin-like extensibility approach.

d. Relevant Technologies and Frameworks:
- C# and .NET (Windows Forms) for the application layer.
- Windows-specific APIs for OS integration (as seen in the Windows directory).
- Standard libraries for mathematical functions, alongside custom-built libraries for specific functionalities (e.g., Newton's method, graph plotting).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        U["UI Layer\n(Windows Forms: MainForm, GraphForm, etc.)"]:::ui
    end

    %% Core Calculation Engine
    subgraph "Core Calculation Engine"
        P["Parser Module\n(AST Creation, Lexer, Parser)"]:::core
        E["Evaluator Module\n(Expression Evaluation & Processing)"]:::core
        EX["Expression Module\n(Expression Constructs)"]:::core
        FUN["Functions Module\n(Built-in & User-Defined)"]:::core
        MATH["Mathematics Module\n(Newton-Raphson, etc.)"]:::core
        FORM["Formats Module\n(Numeric & SI Formatting)"]:::core
        DT["Data Types Module\n(Custom Types)"]:::core
        ST["Standards Module\n(Color spaces, UnixTime, etc.)"]:::core
        GRAPH["Graph & Plotting Module\n(Graph.cs, Plotter.cs)"]:::core
        EXT["External Integration Module\n(External script integration)"]:::integration
    end

    %% Windows Integration
    subgraph "Windows Integration"
        WIN["Windows Integration\n(ClipboardListener, StartupShortcut, etc.)"]:::win
    end

    %% Data Flow Connections
    U -->|"sendsInput"| P
    P -->|"generatesAST"| E
    E -->|"processes"| EX
    E -->|"calls"| FUN
    E -->|"calls"| MATH
    E -->|"calls"| FORM
    E -->|"uses"| DT
    E -->|"uses"| ST
    E -->|"triggers"| GRAPH
    FUN -->|"integrates"| EXT
    E -->|"returnsResult"| U
    U -->|"handlesEvents"| WIN

    %% Classes for styling
    classDef ui fill:#fbb,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef integration fill:#fea,stroke:#333,stroke-width:2px;
    classDef win fill:#afa,stroke:#333,stroke-width:2px;

    %% Click Events
    click U "https://github.com/shapoco/calctus/tree/main/Calctus/UI"
    click P "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Parsers"
    click EX "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Expressions"
    click E "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Evaluations"
    click FUN "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Functions"
    click MATH "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Mathematics"
    click FORM "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Formats"
    click DT "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Types"
    click ST "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Standards"
    click GRAPH "https://github.com/shapoco/calctus/tree/main/Calctus/Model/Graphs"
    click EXT "https://github.com/shapoco/calctus/blob/main/Calctus/Model/Functions/ExternalFuncDef.cs"
    click WIN "https://github.com/shapoco/calctus/tree/main/Windows"
```
