# gtg922r/obsidian-numerals architecture

> Architecture diagram of the GitHub repository gtg922r/obsidian-numerals, 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/gtg922r/obsidian-numerals
- Repository: https://github.com/gtg922r/obsidian-numerals

## Overview

##### Project Type and Purpose
- This project is an Obsidian community plugin that provides an advanced in-note calculator. It parses “math” code blocks, evaluates expressions (including units, currencies, Greek letters, etc.) using mathjs, and offers features like auto-completion, result annotation, and configurable rendering styles (plain, TeX, or highlighted).

##### Analyzing the File Structure
- Top-level configuration and build files include:
- .editorconfig, .eslintrc, .npmrc, and package.json (indicating a JavaScript/TypeScript project with linting and npm-based build configurations).
- esbuild.config.mjs and tsconfig.json indicate a build process for TypeScript/modern JavaScript.
- manifest.json and manifest-beta.json represent the plugin’s manifest(s) for Obsidian.
- In the src directory:
- main.ts: Likely the entry point of the plugin.
- NumeralsSuggestor.ts: Handles auto-complete suggestions.
- Various utility files such as mathjsUtilities.ts and numeralsUtilities.ts support the processing of math expressions.
- settings.ts likely manages configurable options and plugin settings.
- Test files (e.g., numerals.test.ts) along with a dedicated tests folder show that testing is baked into the project.
- Supporting documentation includes a detailed README and possibly Jupyter notebook (mathjs_symbol_parse.ipynb).

##### Main Components and Their Relationships
- Plugin Core (main.ts): Initializes the plugin, integrates with Obsidian's API.
- Suggestor/Auto-completion (NumeralsSuggestor.ts): Monitors math code blocks and provides auto-completion for variables, functions, and constants based on user-defined expressions.
- Math Utilities (mathjsUtilities.ts, numeralsUtilities.ts): Contains the logic for parsing, evaluating, and formatting math expressions. These may interface directly with the mathjs library.
- Settings (settings.ts): Handles configuration settings, including render mode, currency mapping, and styling options.
- Build/Configuration Layer: Files such as package.json, esbuild.config.mjs, and tsconfig.json manage dependency management and build steps.
- Testing: Organized under tests and in files like numerals.test.ts to ensure the plugin behaves as expected.

##### Architectural Patterns and Key Technologies
- Component Separation: Clear logical separation between the core plugin initialization, UI/UX improvements (like suggestions and result rendering), and the evaluation logic.
- Integration with External Library: The plugin makes heavy use of the mathjs library; this should be depicted as an external dependency when outlining dependencies.
- Testing and Build Pipelines: Dedicated configuration files and test folders indicate a strong emphasis on code quality and continuous integration (CI workflows defined in .github/workflows).

##### Final Checklist
- Each component must have a clear, descriptive label.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Runtime Components
    subgraph "Runtime Components"
        PL["Obsidian Plugin Loader"]:::core
        PC["Plugin Core (main.ts)"]:::core
        SU["Numerals Suggestor (NumeralsSuggestor.ts)"]:::core
        MU["Math Utilities (mathjsUtilities.ts, numeralsUtilities.ts)"]:::util
        ST["Settings Manager (settings.ts)"]:::core
        EX["mathjs Library"]:::util
    end

    %% Build & Configuration Layer
    subgraph "Build & Config"
        MC["Manifest Files (manifest.json, manifest-beta.json)"]:::config
        BC["Build & Configuration (package.json, esbuild.config.mjs, tsconfig.json)"]:::config
    end

    %% Testing Components
    subgraph "Testing"
        TS["Tests Suite (numerals.test.ts, tests)"]:::test
    end

    %% Relationships
    PL -->|"initializes"| PC
    PC -->|"invokes"| SU
    PC -->|"invokes"| ST
    PC -->|"invokes"| MU
    SU -->|"calls"| MU
    MU -->|"uses"| EX
    PC ---|"reads"| MC
    PC ---|"reads"| BC
    TS ---|"tests"| PC

    %% Click Events
    click PC "https://github.com/gtg922r/obsidian-numerals/blob/master/src/main.ts"
    click SU "https://github.com/gtg922r/obsidian-numerals/blob/master/src/NumeralsSuggestor.ts"
    click MU "https://github.com/gtg922r/obsidian-numerals/blob/master/src/mathjsUtilities.ts"
    click MU "https://github.com/gtg922r/obsidian-numerals/blob/master/src/numeralsUtilities.ts"
    click ST "https://github.com/gtg922r/obsidian-numerals/blob/master/src/settings.ts"
    click BC "https://github.com/gtg922r/obsidian-numerals/blob/master/package.json"
    click BC "https://github.com/gtg922r/obsidian-numerals/blob/master/esbuild.config.mjs"
    click BC "https://github.com/gtg922r/obsidian-numerals/blob/master/tsconfig.json"
    click MC "https://github.com/gtg922r/obsidian-numerals/blob/master/manifest.json"
    click MC "https://github.com/gtg922r/obsidian-numerals/blob/master/manifest-beta.json"
    click TS "https://github.com/gtg922r/obsidian-numerals/blob/master/src/numerals.test.ts"
    click TS "https://github.com/gtg922r/obsidian-numerals/tree/master/tests"

    %% Styles
    classDef core fill:#d0e6f7,stroke:#334,stroke-width:2px;
    classDef util fill:#f9f1d0,stroke:#993,stroke-width:2px;
    classDef config fill:#e0dff0,stroke:#669,stroke-width:2px;
    classDef test fill:#d0f0d0,stroke:#393,stroke-width:2px;
```
