How leonovk/minicode works
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