# leonovk/minicode architecture

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

- Interactive diagram: https://gitdiagram.com/leonovk/minicode
- Repository: https://github.com/leonovk/minicode

## Overview

##### Project Type & Purpose
- Type: Command-line tool implementing an esoteric programming language
- Purpose:
– Parse “.mcode” source files
– Translate into internal opcodes/AST
– Execute instructions (including I/O, math, arrays, networking)
– Provide a CLI, installation script, and Docker image

##### Top-Level Architecture
A. CLI & Packaging
B. Core Engine (library)
C. External Environment
D. CI/CD / Docs (optional, for deployment view)

##### Main Components & Relationships
A. CLI & Packaging (src/main.rs + install.sh + Dockerfile)
- “minicode” binary (entry point)
- Initialization: read flags, load source file, set up runtime
→ passes raw source text to Parser

B. Core Engine (the core/ crate)
1. Parser module
– Files: parser/*.rs
– Responsibility: tokenize and parse source lines into opcodes or AST nodes
– Output: a sequence of opcodes or an IR

2. Opcode definitions
– Files: opcode/mod.rs
– Defines each instruction code for interpreter

3. Interpreter modules
– Files: interpreter/*.rs
– Subcomponents:
- calculate.rs (arithmetic)
- condition.rs (branching)
- arrays.rs (array ops)
- create.rs (variable creation)
- execute.rs (dispatch loop)
- .rs (source inclusion)
- network.rs (TCP send/receive)
- print.rs (console output)
– Responsibility: implement runtime behavior of each opcode

4. Code Runner & File I/O
– Files: code_runner/mod.rs, files/mod.rs
– Orchestrates the execution environment, file reads/writes

5. Network support
– Files: network/mod.rs
– Provides TCP socket wrappers for “send_tcp” opcode

6. Library Entry Point
– File: lib.rs
– Exposes a “run(source: &str)” API used by the CLI and tests

C. External Environment
- File System (reads .mcode files, writes output files)
- Network Stack (sockets for send_tcp)

D. CI/CD & Documentation
- .github/workflows/ci.yml (build + test)
- publish.yml (crate publishing)
- docs/ (static site, markdown)
- install.sh (user installation script)

##### Data Flow & Interactions
1. User invokes CLI (“minicode -p hello_world.mcode”).
2. CLI loads file → passes text to Core::Parser.
3. Parser → produces opcode sequence.
4. CLI or Core::run() → hands opcodes to CodeRunner.
5. CodeRunner loops: for each opcode, calls Interpreter → executes side effects:
– Math & variables → in-memory store
– I/O → FileSystem module
– Networking → Network module
– Print → stdout
6. Finish execution → CLI returns exit code.

##### Architectural Patterns & Design Principles
- Modular monolith: core engine split into feature-specific modules
- Clear separation:
– Parser layer
– Core opcode definitions
– Interpreter (behavior)
– Runner (orchestration)
– I/O and network adapters
- Single binary exposes library API + CLI interface
- Test harness invokes Core::run() with sample files

##### Final Checklist
– [ ] All major modules (Parser, Opcode, Interpreter, CodeRunner, I/O, Network)
– [ ] CLI entry point and flags handling
– [ ] External dependencies (filesystem, TCP stack)
– [ ] Build & publishing pipeline (GitHub Actions, Docker) if relevant

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Packaging
    subgraph "CLI & Packaging"
        CB["minicode CLI\nsrc/main.rs"]:::cli
        INSTALL["install.sh"]:::cli
        DOCKER["Dockerfile"]:::cli
    end

    %% Core Engine
    subgraph "Core Engine"
        LIB["Library Entry Point\ncore/src/lib.rs"]:::core
        PARSER["Parser Module\ncore/src/parser"]:::core
        OPCODE["Opcode Definitions\ncore/src/opcode/mod.rs"]:::core
        CODERUN["Code Runner\ncore/src/code_runner/mod.rs"]:::core
        INTERPRETER["Interpreter Modules\ncore/src/interpreter"]:::core
        FILES["File I/O Adapter\ncore/src/files/mod.rs"]:::core
        NETWORK_MOD["Network Support Module\ncore/src/network/mod.rs"]:::core
    end

    %% External Environment
    subgraph "External Environment"
        FS["File System"]:::external
        NS["Network Stack"]:::external
    end

    %% CI/CD & Docs
    subgraph "CI/CD & Docs"
        CI["CI Workflow\n.github/workflows/ci.yml"]:::ci
        PUBLISH["Publish Workflow\n.github/workflows/publish.yml"]:::ci
        DOCS["Documentation\ndocs/index.md\ndocs/ru.md"]:::ci
        TESTS["Integration Tests\ncore/tests/examples/*.mcode\ncore/tests/test_file.txt"]:::ci
    end

    %% Connections
    CB -->|"run(source)"| LIB
    LIB -->|"parse call"| PARSER
    PARSER -->|"AST/opcodes"| OPCODE
    OPCODE -->|"opcode defs"| INTERPRETER
    PARSER -->|"opcodes"| CODERUN
    LIB -->|"execute()"| CODERUN
    CODERUN -->|"dispatch"| INTERPRETER
    INTERPRETER -->|"file I/O ops"| FILES
    FILES -->|"reads/writes"| FS
    INTERPRETER -->|"network ops"| NETWORK_MOD
    NETWORK_MOD -->|"TCP packets"| NS

    %% Click Events
    click CB "https://github.com/leonovk/minicode/blob/master/src/main.rs"
    click INSTALL "https://github.com/leonovk/minicode/blob/master/install.sh"
    click DOCKER "https://github.com/leonovk/minicode/tree/master/Dockerfile"
    click PARSER "https://github.com/leonovk/minicode/tree/master/core/src/parser"
    click OPCODE "https://github.com/leonovk/minicode/blob/master/core/src/opcode/mod.rs"
    click INTERPRETER "https://github.com/leonovk/minicode/tree/master/core/src/interpreter"
    click CODERUN "https://github.com/leonovk/minicode/blob/master/core/src/code_runner/mod.rs"
    click FILES "https://github.com/leonovk/minicode/blob/master/core/src/files/mod.rs"
    click NETWORK_MOD "https://github.com/leonovk/minicode/blob/master/core/src/network/mod.rs"
    click LIB "https://github.com/leonovk/minicode/blob/master/core/src/lib.rs"
    click CI "https://github.com/leonovk/minicode/blob/master/.github/workflows/ci.yml"
    click PUBLISH "https://github.com/leonovk/minicode/blob/master/.github/workflows/publish.yml"
    click DOCS "https://github.com/leonovk/minicode/blob/master/docs/index.md"
    click TESTS "https://github.com/leonovk/minicode/blob/master/core/tests/examples/*.mcode"

    %% Styles
    classDef cli fill:#f96,stroke:#333,stroke-width:1px
    classDef core fill:#bbf,stroke:#333,stroke-width:1px
    classDef external fill:#9f9,stroke:#333,stroke-width:1px
    classDef ci fill:#ddd,stroke:#333,stroke-dasharray:5 5,stroke-width:1px
```
