# sakamochanq/dms-calculator architecture

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

- Interactive diagram: https://gitdiagram.com/sakamochanq/dms-calculator
- Repository: https://github.com/sakamochanq/dms-calculator

## Overview

##### Project Type and Purpose
- This is a small Excel‐VBA “add-in” style tool (a macro library) that you load into an Excel workbook (.xlsm) to perform DMS (degrees-minutes-seconds) arithmetic directly in cells.
- The user installs the VBA module (src/main.vba) via the VBA Editor, then invokes functions like sok_add, sok_sub, sok_sumAll, etc., as native Excel functions.

##### File Structure Analysis
- Top-level:
- LICENSE, README.md – project metadata
- assets/ – images for documentation (logo, demo GIF)
- docs/ – multi-language README files
- src/main.vba – the single VBA module containing all sok_ functions
- No separate backend/frontend, no database, no web server or external services.

##### README Insights
- Describes installation steps: clone repo → open VBA Editor → import main.vba → save as macro-enabled workbook → use sok_ functions in cells.
- Core functionality: DMS arithmetic, compass direction, conversion to/from decimal, trig functions on DMS values.

##### Diagramming the Architecture
a. Main Components
1. User (Excel end-user)
2. Excel Application (host environment)
3. VBA Runtime / VBA Editor
4. DMS-Calculator VBA Module (main.vba)
5. Excel Workbook (macro-enabled .xlsm)
6. Worksheet Cells (input/output)
b. Relationships & Data Flow
- User → Excel UI: enters sok_* formula in a cell.
- Excel Calculation Engine → VBA Runtime: when it encounters sok_* it invokes the VBA module.
- VBA Module (main.vba) → internal DMS logic: parses arguments, performs calculation.
- VBA Module → returns result back to Excel Calculation Engine.
- Excel Calculation Engine → writes result into the output cell.
c. Architectural Patterns & Principles
- Single-module plugin pattern: all logic lives in one VBA module.
- Function-call integration: tight Excel-VBA binding—no network, no external libraries.
- Separation of concerns:
- Excel handles UI & cell storage
- VBA handles computation
d. Key Technologies & Frameworks
- Microsoft Excel (host)
- VBA Runtime (built into Excel)
- Custom VBA code (main.vba)

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(("User")):::user
    User -->|enter sok_* formula| Cells

    subgraph "Excel Application"
        CalcEngine["Calculation Engine"]:::host
        Cells["Worksheet Cells"]:::host
        CalcEngine -->|invoke sok_*| ModSub
        ModSub -->|return DMS result| CalcEngine
        CalcEngine -->|write result| Cells

        subgraph "VBA Runtime"
            ModSub["DMS-Calculator Module"]:::custom
            subgraph "Module Functions"
                Arithmetic["Arithmetic Functions"]:::custom
                Compass["Compass Functions"]:::custom
                Trigonometry["Trigonometry Functions"]:::custom
                Converters["Conversion Functions"]:::custom
            end
        end

        subgraph "Workbook (.xlsm)"
            Cells
        end
    end

    subgraph "Project Documentation"
        README["README.md"]:::docs
        License["LICENSE"]:::docs
        Assets["assets/"]:::docs
        EngRead["docs/README-en.md"]:::docs
        KrRead["docs/README-kr.md"]:::docs
    end

    click ModSub "https://github.com/sakamochanq/dms-calculator/blob/master/src/main.vba"
    click README "https://github.com/sakamochanq/dms-calculator/blob/master/README.md"
    click License "https://github.com/sakamochanq/dms-calculator/tree/master/LICENSE"
    click Assets "https://github.com/sakamochanq/dms-calculator/tree/master/assets/"
    click EngRead "https://github.com/sakamochanq/dms-calculator/blob/master/docs/README-en.md"
    click KrRead "https://github.com/sakamochanq/dms-calculator/blob/master/docs/README-kr.md"

    classDef host fill:#BBE1FA,stroke:#1B4F72,stroke-width:1px
    classDef custom fill:#B0FFA3,stroke:#145A32,stroke-width:1px
    classDef user fill:#FFFACD,stroke:#7D6608,stroke-width:1px
    classDef docs fill:#FADBD8,stroke:#78281F,stroke-width:1px
```
