# mrxsin/bbc architecture

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

- Interactive diagram: https://gitdiagram.com/mrxsin/bbc
- Repository: https://github.com/mrxsin/bbc

## Overview

BBC is a Brainfuck-written compiler that accepts Brainfuck source and can check it, emit BFX, inspect BFX, or compile native Windows x86-64 and Android ARM64 programs. The documented compile workflow filters and optimizes source, creates BFX, then uses the embedded XAX importer and driver to verify, lower, and package the target executable. README documentation also describes optimization levels and checked tape behavior. Source excerpts were unavailable, so relationships below are supported by the README; internal XAX implementation boundaries are represented only at the documented level.

Main entry points: [`compiler`](https://github.com/mrxsin/bbc/tree/main/compiler) (XAX driver), [`compiler/fold.bf`](https://github.com/mrxsin/bbc/blob/main/compiler/fold.bf) (Code folding), [`compiler/compiler.bf`](https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf) (Source filtering), [`compiler/stream_chunks.bf`](https://github.com/mrxsin/bbc/blob/main/compiler/stream_chunks.bf) (Stream processing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front_end["Brainfuck front end"]
  node_source_filter["Source filtering<br/>[compiler.bf]"]
  node_folding["Code folding<br/>[fold.bf]"]
  node_streaming["Stream processing<br/>[stream_chunks.bf]"]
  node_bfx["BFX record"]
end

subgraph group_xax["XAX compilation"]
  node_importer["XAX importer"]
  node_semantic_graph["Verified graph"]
  node_driver["XAX driver"]
  node_verification["Graph verification"]
  node_lowering["Target lowering"]
  node_packaging["Executable packaging"]
end

subgraph group_interface["Compiler interface"]
  node_check["Source check<br/>[compiler.bf]"]
  node_emit["BFX emission<br/>[compiler.bf]"]
  node_inspect["BFX info<br/>[compiler.bf]"]
end

node_developer(("Compiler user"))
node_bf_source["Brainfuck source"]
node_windows["Windows executable"]
node_android["Android executable"]

node_developer -->|"provides"| node_bf_source
node_bf_source -->|"filters"| node_source_filter
node_source_filter -->|"optimizes"| node_folding
node_folding -->|"emits"| node_bfx
node_developer -->|"requests"| node_check
node_check -->|"checks"| node_bf_source
node_developer -->|"requests"| node_emit
node_emit -->|"emits"| node_bfx
node_developer -->|"requests"| node_inspect
node_inspect -->|"inspects"| node_bfx
node_developer -->|"compiles"| node_driver
node_driver -->|"invokes"| node_importer
node_importer -->|"imports"| node_bfx
node_importer -->|"creates"| node_semantic_graph
node_driver -->|"verifies"| node_verification
node_driver -->|"lowers"| node_lowering
node_driver -->|"packages"| node_packaging
node_packaging -->|"produces"| node_windows
node_packaging -->|"produces"| node_android
node_folding -.->|"supports"| node_streaming

click node_source_filter "https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf"
click node_folding "https://github.com/mrxsin/bbc/blob/main/compiler/fold.bf"
click node_streaming "https://github.com/mrxsin/bbc/blob/main/compiler/stream_chunks.bf"
click node_check "https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf"
click node_emit "https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf"
click node_inspect "https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf"
click node_importer "https://github.com/mrxsin/bbc/tree/main/compiler"
click node_semantic_graph "https://github.com/mrxsin/bbc/tree/main/compiler"
click node_driver "https://github.com/mrxsin/bbc/tree/main/compiler"
click node_verification "https://github.com/mrxsin/bbc/tree/main/compiler"
click node_lowering "https://github.com/mrxsin/bbc/tree/main/compiler"
click node_packaging "https://github.com/mrxsin/bbc/tree/main/compiler"

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_source_filter,node_folding,node_streaming,node_bfx,node_developer toneBlue
class node_importer,node_semantic_graph,node_driver,node_verification,node_lowering,node_packaging toneAmber
class node_check,node_emit,node_inspect toneMint
class node_bf_source,node_windows,node_android toneIndigo
```

## Components

### Brainfuck front end

- [Source filtering](https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf): `compiler/compiler.bf`
- [Code folding](https://github.com/mrxsin/bbc/blob/main/compiler/fold.bf): `compiler/fold.bf`
- [Stream processing](https://github.com/mrxsin/bbc/blob/main/compiler/stream_chunks.bf): `compiler/stream_chunks.bf`
- **BFX record**

### XAX compilation

- [XAX importer](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`
- [Verified graph](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`
- [XAX driver](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`
- [Graph verification](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`
- [Target lowering](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`
- [Executable packaging](https://github.com/mrxsin/bbc/tree/main/compiler): `compiler`

### Compiler interface

- [Source check](https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf): `compiler/compiler.bf`
- [BFX emission](https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf): `compiler/compiler.bf`
- [BFX info](https://github.com/mrxsin/bbc/blob/main/compiler/compiler.bf): `compiler/compiler.bf`

### Other components

- **Compiler user**
- **Brainfuck source**
- **Windows executable**
- **Android executable**

## Connections

- Compiler user → Brainfuck source: provides (evidence: `README.md`)
- Brainfuck source → Source filtering: filters (evidence: `README.md`)
- Source filtering → Code folding: optimizes (evidence: `README.md`)
- Code folding → BFX record: emits (evidence: `README.md`)
- Compiler user → Source check: requests (evidence: `README.md`)
- Source check → Brainfuck source: checks (evidence: `README.md`)
- Compiler user → BFX emission: requests (evidence: `README.md`)
- BFX emission → BFX record: emits (evidence: `README.md`)
- Compiler user → BFX info: requests (evidence: `README.md`)
- BFX info → BFX record: inspects (evidence: `README.md`)
- Compiler user → XAX driver: compiles (evidence: `README.md`)
- XAX driver → XAX importer: invokes (evidence: `README.md`)
- XAX importer → BFX record: imports (evidence: `README.md`)
- XAX importer → Verified graph: creates (evidence: `README.md`)
- XAX driver → Graph verification: verifies (evidence: `README.md`)
- XAX driver → Target lowering: lowers (evidence: `README.md`)
- XAX driver → Executable packaging: packages (evidence: `README.md`)
- Executable packaging → Windows executable: produces (evidence: `README.md`)
- Executable packaging → Android executable: produces (evidence: `README.md`)
- Code folding → Stream processing: supports
