# vladk1m0/gbfm architecture

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

- Interactive diagram: https://gitdiagram.com/vladk1m0/gbfm
- Repository: https://github.com/vladk1m0/gbfm

## Overview

##### Project type and purpose
- This is a command-line Brainfuck “machine” (an interpreter + transpiler) written in Go.
- Purpose: take a .bf source file, parse it, then either execute it directly or generate equivalent JavaScript code for later execution.

##### File structure
- Top level:
- main.go       → entry point; dispatches “run” vs “translate” modes
- gbfm.sh        → thin shell wrapper around the Go binary
- go.mod         → module definition
- test_data/     → sample .bf programs
- brainfuck/     → core package
- parser.go        → reads raw tokens, builds AST or instruction list
- interpreter.go   → executes instructions against a data tape (stack)
- transpiler.go    → walks instructions/AST, produces target code
- target.go        → definitions for code‐generation hooks, target interfaces
- stack/           → runtime tape (data memory) abstraction
- Tests everywhere to validate parser, stack, interpreter, and transpiler
- Patterns:
- Classic compiler pipeline: front-end (lexer/parser), intermediate in-memory representation, two back-ends (interpreter engine + transpiler back-end).
- Clear separation of concerns by package.

##### README for additional insights
- Only JavaScript is supported as a transpilation target.
- The shell script hides Go build & mode flags.
- External dependency: Node.js to run generated .bf.js.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        Shell["Shell Wrapper"]:::cli
        Main["Go Entry Point"]:::cli
    end
    Shell --> Main

    %% Parsing Layer
    Main --> Parser
    subgraph "Parsing Layer"
        Parser["Parser Component\n(parser.go)"]:::parser
    end
    Parser --> IR

    %% Intermediate Representation
    IR["IR / Instruction List"]:::ir

    %% Execution Layer
    IR --> Interpreter
    subgraph "Execution Layer"
        Interpreter["Interpreter Component\n(interpreter.go)"]:::exec
        Stack["Data Tape (Stack)\n(stack.go)"]:::exec
        OutputStdout["Stdout"]:::ext
    end
    Interpreter --> Stack
    Interpreter --> OutputStdout

    %% Transpilation Layer
    IR --> Transpiler
    subgraph "Transpilation Layer"
        Transpiler["Transpiler Component\n(transpiler.go)"]:::transpile
        Target["Target Interface\n(target.go)"]:::transpile
        JSOutput[".js Output File"]:::ir
    end
    Transpiler --> Target
    Transpiler --> JSOutput
    JSOutput -.-> Node["Node.js Runtime"]:::ext

    %% Tests & Sample Data
    subgraph "Tests & Sample Data"
        ParserTest["Parser Tests\n(parser_test.go)"]:::test
        InterpreterTest["Interpreter Tests\n(interpreter_test.go)"]:::test
        StackTest["Stack Tests\n(stack_test.go)"]:::test
        TranspilerTest["Transpiler Tests\n(transpiler_test.go)"]:::test
        SampleData["Sample .bf Programs"]:::test
    end
    ParserTest --> Parser
    InterpreterTest --> Interpreter
    StackTest --> Stack
    TranspilerTest --> Transpiler
    SampleData --> Parser

    %% Click Events
    click Shell "https://github.com/vladk1m0/gbfm/blob/master/gbfm.sh"
    click Main "https://github.com/vladk1m0/gbfm/blob/master/main.go"
    click Parser "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/parser.go"
    click ParserTest "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/parser_test.go"
    click Interpreter "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/interpreter.go"
    click InterpreterTest "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/interpreter_test.go"
    click Stack "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/stack/stack.go"
    click StackTest "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/stack/stack_test.go"
    click Transpiler "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/transpiler.go"
    click TranspilerTest "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/transpiler_test.go"
    click Target "https://github.com/vladk1m0/gbfm/blob/master/brainfuck/target.go"
    click SampleData "https://github.com/vladk1m0/gbfm/tree/master/test_data/"

    %% Styles
    classDef cli fill:#fde2e2,stroke:#e63946,color:#000;
    classDef parser fill:#e2f0cb,stroke:#78866b,color:#000;
    classDef ir fill:#fff3bf,stroke:#f0a500,color:#000;
    classDef exec fill:#cff4fc,stroke:#0a9396,color:#000;
    classDef transpile fill:#fcd5ce,stroke:#e76f51,color:#000;
    classDef ext fill:#e0e0e0,stroke:#adb5bd,color:#000,stroke-dasharray: 5 5;
    classDef test fill:#f0f0f0,stroke:#ccc,color:#000,stroke-dasharray: 2 2;
```
