# nklopstock611/turing-machine-interpreter architecture

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

- Interactive diagram: https://gitdiagram.com/nklopstock611/turing-machine-interpreter
- Repository: https://github.com/nklopstock611/turing-machine-interpreter

## Overview

##### Project type and purpose
- This is a command‐line Turing Machine interpreter written in Python.
- It reads a “.tm” file that describes a simple TM‐style language, lexes and executes it on an in-memory tape, and prints the result to the console.

##### File structure
- Top level:
- tm.py        – main entrypoint, ties everything together
- args.py      – command‐line argument parsing
- interpreter/ – core interpreter modules
– lexer.py   – turns source lines into tokens/instructions
– tape.py    – implements the tape model and head operations
- examples/    – sample .tm programs (not part of runtime logic)
- No separate frontend/backend or database—this is a single process, CLI tool.
- Uses Python’s standard modules, plus custom lexer and tape classes.

##### README for additional insights
- Describes the TM instruction set and the invocation syntax (`python tm.py ...`).
- Confirms that the system follows an Interpreter Pattern: it lexes lines, maps them to instructions, and executes them.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User/Shell"]:::externalIO

    subgraph "Orchestration (CLI)"
        CLI_main["tm.py"]:::orchestration
        CLI_args["args.py"]:::orchestration
    end

    subgraph "External I/O"
        Examples["examples/ Directory"]:::externalIO
        FS[".tm File System"]:::externalIO
        Console["Console Output"]:::externalIO
    end

    subgraph "Core Logic"
        Lexer["lexer.py"]:::core
        Engine["Interpreter Engine"]:::core
    end

    subgraph "State (Tape Model)"
        Tape["tape.py"]:::state
    end

    User -->|"invoke CLI"| CLI_main
    CLI_main -->|"parse flags"| CLI_args
    CLI_main -->|"open .tm file"| FS
    Examples -->|"contains sample .tm"| FS
    FS -->|".tm lines"| Lexer
    Lexer -->|"tokens"| Engine
    Engine -->|"tape read/write/move"| Tape
    Engine -->|"printed output"| Console

    click CLI_main "https://github.com/nklopstock611/turing-machine-interpreter/blob/main/tm.py"
    click CLI_args "https://github.com/nklopstock611/turing-machine-interpreter/blob/main/args.py"
    click Examples "https://github.com/nklopstock611/turing-machine-interpreter/tree/main/examples/"
    click Lexer "https://github.com/nklopstock611/turing-machine-interpreter/blob/main/interpreter/lexer.py"
    click Tape "https://github.com/nklopstock611/turing-machine-interpreter/blob/main/interpreter/tape.py"
    click Engine "https://github.com/nklopstock611/turing-machine-interpreter/blob/main/tm.py"

    classDef orchestration fill:#ADD8E6,stroke:#000,color:#000;
    classDef core fill:#FFA500,stroke:#000,color:#000;
    classDef state fill:#DDA0DD,stroke:#000,color:#000;
    classDef externalIO fill:#90EE90,stroke:#000,color:#000;
```
