# asc91/dumb_calculator architecture

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

- Interactive diagram: https://gitdiagram.com/asc91/dumb_calculator
- Repository: https://github.com/asc91/dumb_calculator

## Overview

##### Project type and purpose
- This is a small command-line arithmetic expression evaluator written in C.
- It reads an infix expression from stdin, tokenizes it, converts it to RPN with the shunting-yard algorithm, then evaluates the RPN and prints a result.
- It is essentially a CLI calculator engine implementing core compiler-style stages (lexing, parsing, evaluation).

##### File structure
- Top-level files:
- Makefile – build automation
- README.md – project description
- .gitignore – ignores build artifacts
- / directory – public headers for each module (eval.h, helper.h, shunting_yard.h, token.h)
- src/ directory – implementation of each module:
- main.c – orchestrates input → pipeline → output
- token.c – lexical analysis (tokenizer)
- shunting_yard.c – parser/infix-to-RPN converter
- eval.c – RPN evaluation engine
- helper.c – supporting utilities (error messages, string handling)

##### Key insights from README
- Pipeline stages are clearly described: input → token queue → RPN conversion → evaluation → output.
- Current limitations: no brackets, no non-decimal numbers, limited error handling.
- Future extensions: bracket support, hex/binary parsing, Qt UI, fuzzy testing.

##### Main components and their relationships
a. Input Component (stdin handler)
- Reads raw expression string.
b. Tokenizer Module
- Uses helper routines to split input into tokens (numbers, operators).
- Exposes a queue or list of tokens.
c. Parser (Shunting Yard) Module
- Accepts token queue, applies operator precedence rules.
- Outputs an RPN token sequence.
d. Evaluation Module
- Takes RPN sequence, computes numeric result via stack.
e. Output Component
- Formats and prints the final result to stdout.
f. Helper Utilities
- Shared error handling, memory management, string-to-number conversion.

##### Relationships and data flow
stdin → Tokenizer → Parser → Evaluator → stdout
- Makefile and build artifacts can be shown as a side-component for deployment.

##### Architectural patterns and design principles
- Pipeline architecture (linear stages).
- Modular design: each stage is encapsulated in its own C module and header.
- Single responsibility principle: tokenizer only splits tokens; parser only rearranges; evaluator only computes.

##### Technologies and dependencies
- C99 (or earlier) standard library only.
- Build system: Makefile, no external dependencies.
- Future Qt UI component will introduce a GUI layer sitting in front of the pipeline, replacing or augmenting stdin/stdout.

##### Detailed capture
- Build component (Makefile) to indicate how everything is compiled and linked.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% I/O Component
    IO[/Input/Output\nsrc/main.c/]:::io

    %% Core Pipeline Modules
    Tokenizer["Tokenizer\ninclude/token.h\nsrc/token.c"]:::core
    Parser["Shunting Yard\ninclude/shunting_yard.h\nsrc/shunting_yard.c"]:::core
    Evaluator["Evaluator\ninclude/eval.h\nsrc/eval.c"]:::core

    %% Helper Utilities
    Helper["Helper Utilities\ninclude/helper.h\nsrc/helper.c"]:::util

    %% Side Components
    MAKE["Makefile"]:::side
    README["README.md"]:::side

    %% Data Flow
    IO -->|"raw string"| Tokenizer
    Tokenizer -->|"token queue"| Parser
    Parser -->|"RPN tokens"| Evaluator
    Evaluator -->|"result value"| IO

    %% Cross-Cutting Utilities
    Helper -.-> Tokenizer
    Helper -.-> Parser
    Helper -.-> Evaluator

    %% Build & Docs Dependencies
    MAKE -.-> IO
    MAKE -.-> Tokenizer
    MAKE -.-> Parser
    MAKE -.-> Evaluator
    MAKE -.-> Helper
    README -.-> IO
    README -.-> Tokenizer
    README -.-> Parser
    README -.-> Evaluator
    README -.-> Helper

    %% Click Events
    click IO "https://github.com/asc91/dumb_calculator/blob/main/src/main.c"
    click Tokenizer "https://github.com/asc91/dumb_calculator/blob/main/include/token.h"
    click Tokenizer "https://github.com/asc91/dumb_calculator/blob/main/src/token.c"
    click Parser "https://github.com/asc91/dumb_calculator/blob/main/include/shunting_yard.h"
    click Parser "https://github.com/asc91/dumb_calculator/blob/main/src/shunting_yard.c"
    click Evaluator "https://github.com/asc91/dumb_calculator/blob/main/include/eval.h"
    click Evaluator "https://github.com/asc91/dumb_calculator/blob/main/src/eval.c"
    click Helper "https://github.com/asc91/dumb_calculator/blob/main/include/helper.h"
    click Helper "https://github.com/asc91/dumb_calculator/blob/main/src/helper.c"
    click MAKE "https://github.com/asc91/dumb_calculator/tree/main/Makefile"
    click README "https://github.com/asc91/dumb_calculator/blob/main/README.md"

    %% Styles
    classDef io fill:#b2f2bb,stroke:#333,stroke-width:1px;
    classDef core fill:#a5d8ff,stroke:#333,stroke-width:1px;
    classDef util fill:#e9ecef,stroke:#333,stroke-width:1px;
    classDef side fill:#f8f0fc,stroke:#333,stroke-width:1px;
```
