# starbuck7410/brainfuck-compiler architecture

> Architecture diagram of the GitHub repository starbuck7410/brainfuck-compiler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/starbuck7410/brainfuck-compiler
- Repository: https://github.com/starbuck7410/brainfuck-compiler

## Overview

1. **Repository purpose**
   - This is a **Brainfuck compiler written in C**.
   - It takes a Brainfuck source file and emits a **native little-endian x86_64 ELF executable** directly, without calling an external assembler.

2. **Top-level pipeline**
   - The compiler flow is: **read Brainfuck source → translate to internal operations → emit machine code bytes → wrap them in ELF headers → write output binary**.
   - The result is a runnable Unix-like executable, not an interpreter.

3. **Main entry point**
   - `src/main.c` is the orchestration layer.
   - It likely handles command-line arguments (`bfc <source_file> <output_binary>`), invokes the compiler stages, and coordinates file I/O.

4. **Brainfuck front-end / operation model**
   - `src/operations.c` and `include/operations.h` represent Brainfuck-level behavior.
   - This layer maps Brainfuck commands such as pointer movement, cell increment/decrement, I/O, and loop constructs into compiler actions.
   - The README notes a simple optimization exists: **folding identical operations** into one instruction sequence.

5. **Control-flow handling**
   - `src/stack.c` and `include/stack.h` implement a **stack used for bracket matching and jump address management**.
   - This is the key data structure for translating `[` and `]` into forward/backward branch targets in generated code.

6. **Machine-code emission**
   - `src/instructions.c` and `include/instructions.h` are responsible for encoding **x86_64 instructions as raw bytes**.
   - This is the lowest compiler layer, where Brainfuck actions become actual CPU instructions rather than abstract IR.
   - The presence of `opcodes.h` and `registers.h` indicates the compiler hardcodes supported instruction encodings, opcodes, and register names/types.

7. **ELF binary construction**
   - `src/headers.c` and `include/headers.h` handle **ELF header and related metadata generation**.
   - This layer packages the emitted code into a valid executable format for Unix-like systems on little-endian machines.
   - Since the compiler emits an ELF directly, this boundary is separate from instruction generation and is responsible for executable layout.

8. **Supporting definition headers**
   - `include/opcodes.h` and `include/registers.h` are compile-time reference tables for the code generator.
   - They centralize architecture-specific constants, which helps keep the instruction encoder and operation translator separated.

9. **Output characteristics and constraints**
   - The compiler targets **x86_64 little-endian ELF**, with the README suggesting it should work on Linux, *BSD, and possibly macOS-like environments, though it was only tested on Arch Linux.
   - This means the architecture is tightly bound to the executable format and CPU instruction set.

10. **Build and packaging**
   - `makefile` is the build entry point.
   - Standard build/test workflows are provided: compile the compiler, run it on a Brainfuck source file, and optionally inspect or execute the generated binary.

11. **Optimization scope**
   - The current architecture is explicitly **non-optimizing**, with only basic folding implemented.
   - Planned future optimizations are mentioned, but they are not yet part of the core architecture.

12. **How to draw the architecture**
   - A good diagram would show three main layers:
     - **Front-end parsing / Brainfuck operation handling**
     - **x86_64 instruction encoding**
     - **ELF file assembly and output**
   - The **stack** is a supporting subsystem for loop control, and `main` is the coordinator that wires the stages together.

Main entry points: [`src/instructions.c`](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/instructions.c) (Encoder), [`src/main.c`](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/main.c) (Main), [`src/headers.c`](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/headers.c) (ELF builder), [`src/operations.c`](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/operations.c) (Ops)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Front-end"]
  node_node_operations["Ops<br/>bf translator<br/>[operations.c]"]
  node_node_operations_h["Ops API<br/>bf model<br/>[operations.h]"]
end

subgraph group_group_codegen["Codegen"]
  node_node_instructions["Encoder<br/>[instructions.c]"]
  node_node_instructions_h["Encoder API<br/>codegen API<br/>[instructions.h]"]
  node_node_opcodes["Opcodes<br/>isa constants<br/>[opcodes.h]"]
  node_node_registers["Registers<br/>isa constants<br/>[registers.h]"]
end

subgraph group_group_elf["ELF packaging"]
  node_node_headers["ELF builder<br/>elf assembler<br/>[headers.c]"]
  node_node_headers_h["ELF API<br/>[headers.h]"]
  node_node_output["ELF binary<br/>native executable"]
end

subgraph group_group_support["Support"]
  node_node_main["Main<br/>orchestrator<br/>[main.c]"]
  node_node_stack["Stack<br/>[stack.c]"]
  node_node_stack_h["Stack API<br/>[stack.h]"]
  node_node_makefile["Makefile<br/>build config"]
end

node_node_makefile -->|"builds"| node_node_main
node_node_main -->|"translate"| node_node_operations
node_node_main -->|"encode"| node_node_instructions
node_node_main -->|"package"| node_node_headers
node_node_main -->|"write"| node_node_output
node_node_operations -->|"uses"| node_node_operations_h
node_node_operations -->|"loops"| node_node_stack
node_node_stack -->|"exposes"| node_node_stack_h
node_node_instructions -->|"uses"| node_node_instructions_h
node_node_instructions -->|"encodes"| node_node_opcodes
node_node_instructions -->|"encodes"| node_node_registers
node_node_instructions -->|"hands off"| node_node_headers
node_node_headers -->|"uses"| node_node_headers_h
node_node_headers -->|"wraps"| node_node_output

click node_node_main "https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/main.c"
click node_node_operations "https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/operations.c"
click node_node_operations_h "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/operations.h"
click node_node_stack "https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/stack.c"
click node_node_stack_h "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/stack.h"
click node_node_instructions "https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/instructions.c"
click node_node_instructions_h "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/instructions.h"
click node_node_opcodes "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/opcodes.h"
click node_node_registers "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/registers.h"
click node_node_headers "https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/headers.c"
click node_node_headers_h "https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/headers.h"
click node_node_makefile "https://github.com/starbuck7410/brainfuck-compiler/tree/main/makefile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_operations,node_node_operations_h toneBlue
class node_node_instructions,node_node_instructions_h,node_node_opcodes,node_node_registers toneAmber
class node_node_headers,node_node_headers_h,node_node_output toneMint
class node_node_main,node_node_stack,node_node_stack_h,node_node_makefile toneRose
```

## Components

### Front-end

Brainfuck input handling and operation translation

- [Ops](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/operations.c): bf translator · Maps Brainfuck commands into compiler operations with simple folding · `src/operations.c`
- [Ops API](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/operations.h): bf model · Operation definitions and front-end interface · `include/operations.h`

### Codegen

x86_64 byte emission and ISA constants

- [Encoder](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/instructions.c): x86_64 encoder · Turns compiler operations into raw machine-code bytes · `src/instructions.c`
- [Encoder API](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/instructions.h): codegen API · Instruction encoder interface · `include/instructions.h`
- [Opcodes](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/opcodes.h): isa constants · Hardcoded opcode values used by the encoder · `include/opcodes.h`
- [Registers](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/registers.h): isa constants · Register names and encoding helpers for x86_64 · `include/registers.h`

### ELF packaging

Executable header and file assembly

- [ELF builder](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/headers.c): elf assembler · Builds ELF headers and executable metadata · `src/headers.c`
- [ELF API](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/headers.h): elf API · ELF header construction interface · `include/headers.h`
- **ELF binary**: native executable · Generated little-endian x86_64 ELF output

### Support

Shared data structures and build entry point

- [Main](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/main.c): orchestrator · CLI entry point that wires the compiler stages together · `src/main.c`
- [Stack](https://github.com/starbuck7410/brainfuck-compiler/blob/main/src/stack.c): loop stack · Bracket matching and jump target management for loops · `src/stack.c`
- [Stack API](https://github.com/starbuck7410/brainfuck-compiler/blob/main/include/stack.h): stack API · Stack interface used by loop handling · `include/stack.h`
- [Makefile](https://github.com/starbuck7410/brainfuck-compiler/tree/main/makefile): build config · Build entry point for compiling the compiler · `makefile`

## Connections

- Makefile → Main: builds · Compiles the compiler binary
- Main → Ops: translate · Coordinates reading source and front-end translation
- Main → Encoder: encode · Hands off translated operations for machine-code emission
- Main → ELF builder: package · Wraps emitted code in ELF metadata
- Main → ELF binary: write · Writes the final executable to disk
- Ops → Ops API: uses · Implements the Brainfuck operation model
- Ops → Stack: loops · Uses the stack to match brackets and manage jumps
- Stack → Stack API: exposes · Stack interface for loop control
- Encoder → Encoder API: uses · Implements the encoder interface
- Encoder → Opcodes: encodes · References opcode constants for byte emission
- Encoder → Registers: encodes · References register encodings and names
- Encoder → ELF builder: hands off · Provides machine-code bytes to the ELF packager
- ELF builder → ELF API: uses · Implements the ELF construction interface
- ELF builder → ELF binary: wraps · Produces a runnable ELF executable