# gogomillan/monty architecture

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

- Interactive diagram: https://gitdiagram.com/gogomillan/monty
- Repository: https://github.com/gogomillan/monty

## Overview

##### Main Components
- Entry Point/Controller:
- The main function in main.c serves as the program’s entry point. It handles command-line arguments, opening and reading the bytecode file.
- File Reading & Parsing:
- Modules like readfile.c and check_command.c are responsible for reading the file and determining which opcode each line represents.
- set_number.c likely assists in processing numeric arguments (for example, for the “push” opcode).
- Opcode Execution Handlers:
- Each opcode is implemented in its own file (e.g., _push.c, _pall.c, _pop.c, _add.c, etc.). These files represent the different actions the interpreter can execute (stack operations like push, pop, swap, add, sub, div, mul, mod, pchar, pstr, rotl, rotr, nop).
- Data Structure Management:
- Files like freestack.c and monty.h (with shared data types) manage the underlying data structure that can be a stack or queue. This global structure is at the heart of the interpreter logic.
- Additional/Bonus Support:
- The bf directory contains Brainf*ck files used for the bonus feature, indicating an extra layer of logic or alternative interpretation for Brainf*ck code.
- Auxiliary/Resource Components:
- The assets directory holds image resources (e.g., the Monty logo). These might not be core to the runtime but are important for branding or documentation visuals.
- Bytecode Examples:
- The bytecodes directory contains several .m files used to test or demonstrate the various opcodes and behaviors of the interpreter.

##### Relationships & Interactions
1. The CLI invokes the interpreter (main.c), which validates command-line parameters.
2. The file reading module (readfile.c) opens and parses the input Monty bytecode file.
3. The command check module (check_command.c) translates each line into a recognized opcode.
4. The interpreter’s core dispatches the opcode to the corresponding execution handler (files like _push.c, _pall.c, etc.).
5. The opcode handler interacts with the central global data structure (implemented via modules like freestack.c and defined in monty.h) to perform operations (stack manipulation, arithmetic, etc.).
6. Output is sent back to the terminal, while error conditions (e.g., insufficient stack elements, division by zero) are handled as described.

##### Architectural Patterns & Design Principles
- Separation of Concerns: Each functionality is split into modules – file handling, command parsing, opcode execution, and data management.
- Modularity: The design leverages multiple small C files, each implementing a single instruction or helper function, which simplifies debugging and maintenance.
- Error Handling: The interpreter integrates robust error handling for incorrect command usage, invalid file paths, or execution errors (e.g., empty stack scenarios).
- Extensibility: The structure supports adding more opcodes or even another language (as evidenced by the bonus Brainf*ck support).

##### Elements
- Clear labels for each major component:
- “Main Controller (main.c)”
- “File Parser & Validator (readfile.c, check_command.c, set_number.c)”
- “Opcode Handlers (e.g., _push.c, _pop.c, _pall.c, etc.)”
- “Data Structure Manager (freestack.c, monty.h)”
- “Brainf*ck Bonus Module (bf directory)”
- Flow of data and control starting from the CLI input to file processing, then through opcode dispatch, execution, manipulation of the stack/queue, and output to the screen.
- Annotations:
- Error flow paths (e.g., what happens when a file cannot be opened or an invalid opcode is encountered).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Control Layer
    subgraph "Control Layer"
        CLI("User Input/CLI"):::control
        Main("Main Controller (main.c)"):::control
    end
    CLI --> Main

    %% Parsing Layer
    subgraph "Parsing Layer"
        ReadFile("File Reader (readfile.c)"):::parser
        CheckCmd("Command Checker (check_command.c)"):::parser
        SetNum("Set Number (set_number.c)"):::parser
    end
    Main --> ReadFile
    Main --> CheckCmd
    Main --> SetNum

    %% Dispatcher & Opcode Handlers
    subgraph "Dispatcher & Opcode Handlers"
        Dispatcher("Dispatcher"):::opcode
        ReadFile --> Dispatcher
        CheckCmd --> Dispatcher
        SetNum --> Dispatcher

        push("_push.c"):::opcode
        pall("_pall.c"):::opcode
        pop("_pop.c"):::opcode
        add("_add.c"):::opcode
        sub("_sub.c"):::opcode
        div("_div.c"):::opcode
        mul("_mul.c"):::opcode
        mod("_mod.c"):::opcode
        nop("_nop.c"):::opcode
        pchar("_pchar.c"):::opcode
        pint("_pint.c"):::opcode
        pstr("_pstr.c"):::opcode
        swap("_swap.c"):::opcode
        rotl("_rotl.c"):::opcode
        rotr("_rotr.c"):::opcode

        Dispatcher --> push
        Dispatcher --> pall
        Dispatcher --> pop
        Dispatcher --> add
        Dispatcher --> sub
        Dispatcher --> div
        Dispatcher --> mul
        Dispatcher --> mod
        Dispatcher --> nop
        Dispatcher --> pchar
        Dispatcher --> pint
        Dispatcher --> pstr
        Dispatcher --> swap
        Dispatcher --> rotl
        Dispatcher --> rotr
    end

    %% Data Structure Management
    subgraph "Data Structure Management"
        monty("monty.h"):::data
        free("freestack.c"):::data
        stack("_stack.c"):::data
        queue("_queue.c"):::data
    end
    push --> monty
    pall --> monty
    pop --> monty
    add --> monty
    sub --> monty
    div --> monty
    mul --> monty
    mod --> monty
    nop --> monty
    pchar --> monty
    pint --> monty
    pstr --> monty
    swap --> monty
    rotl --> monty
    rotr --> monty

    monty --> free
    monty --> stack
    monty --> queue

    %% Output/Error Handling
    Output("Output/Error Handling"):::output
    monty --> Output

    %% Bonus Module
    subgraph "Bonus Module"
        BF("Brainf*ck Bonus Module"):::bonus
        bf1000("bf/1000-holberton.bf"):::bonus
        bf1001("bf/1001-add.bf"):::bonus
        bf1002("bf/1002-mul.bf"):::bonus
        bf1003("bf/1003-mul.bf"):::bonus
        BF --> bf1000
        BF --> bf1001
        BF --> bf1002
        BF --> bf1003
    end
    Main --> BF
    BF --> monty

    %% Auxiliary Resources
    subgraph "Auxiliary Resources"
        Assets("Assets (assets directory)"):::resources
        Bytecodes("Bytecode Examples (bytecodes directory)"):::resources
    end
    Main --> Bytecodes
    Main --> Assets

    %% Styles
    classDef control fill:#ffcccb,stroke:#333,stroke-width:2px;
    classDef parser fill:#cceeff,stroke:#333,stroke-width:2px;
    classDef opcode fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef data fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef bonus fill:#caffca,stroke:#333,stroke-width:2px;
    classDef resources fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef output fill:#e0e0e0,stroke:#333,stroke-width:2px;

    %% Click Events
    click Main "https://github.com/gogomillan/monty/blob/master/main.c"
    click ReadFile "https://github.com/gogomillan/monty/blob/master/readfile.c"
    click CheckCmd "https://github.com/gogomillan/monty/blob/master/check_command.c"
    click SetNum "https://github.com/gogomillan/monty/blob/master/set_number.c"
    click push "https://github.com/gogomillan/monty/blob/master/_push.c"
    click pall "https://github.com/gogomillan/monty/blob/master/_pall.c"
    click pop "https://github.com/gogomillan/monty/blob/master/_pop.c"
    click add "https://github.com/gogomillan/monty/blob/master/_add.c"
    click sub "https://github.com/gogomillan/monty/blob/master/_sub.c"
    click div "https://github.com/gogomillan/monty/blob/master/_div.c"
    click mul "https://github.com/gogomillan/monty/blob/master/_mul.c"
    click mod "https://github.com/gogomillan/monty/blob/master/_mod.c"
    click nop "https://github.com/gogomillan/monty/blob/master/_nop.c"
    click pchar "https://github.com/gogomillan/monty/blob/master/_pchar.c"
    click pint "https://github.com/gogomillan/monty/blob/master/_pint.c"
    click pstr "https://github.com/gogomillan/monty/blob/master/_pstr.c"
    click swap "https://github.com/gogomillan/monty/blob/master/_swap.c"
    click rotl "https://github.com/gogomillan/monty/blob/master/_rotl.c"
    click rotr "https://github.com/gogomillan/monty/blob/master/_rotr.c"
    click monty "https://github.com/gogomillan/monty/blob/master/monty.h"
    click free "https://github.com/gogomillan/monty/blob/master/freestack.c"
    click stack "https://github.com/gogomillan/monty/blob/master/_stack.c"
    click queue "https://github.com/gogomillan/monty/blob/master/_queue.c"
    click BF "https://github.com/gogomillan/monty/tree/master/bf"
    click bf1000 "https://github.com/gogomillan/monty/blob/master/bf/1000-holberton.bf"
    click bf1001 "https://github.com/gogomillan/monty/blob/master/bf/1001-add.bf"
    click bf1002 "https://github.com/gogomillan/monty/blob/master/bf/1002-mul.bf"
    click bf1003 "https://github.com/gogomillan/monty/blob/master/bf/1003-mul.bf"
    click Assets "https://github.com/gogomillan/monty/tree/master/assets"
    click Bytecodes "https://github.com/gogomillan/monty/tree/master/bytecodes"
```
