# ak47andrew/bee_hive architecture

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

- Interactive diagram: https://gitdiagram.com/ak47andrew/bee_hive
- Repository: https://github.com/ak47andrew/bee_hive

## Overview

#### Purpose and Runtime

BEE_HIVE is a Rust command-line compiler. It reads Bee (`.bee`) source programs and emits NJ, a Brainfuck-like target language, to stdout. The binary is built and distributed through Cargo/crates.io and release artifacts; it is not a web service. Primary entry points are `src/main.rs` and `src/cli.rs`.

#### CLI Boundary

`src/main.rs` initializes the executable and delegates command handling. `src/cli.rs` owns the user-facing contract: source-path input plus an optional debug mode. The CLI is the boundary between filesystem input and compiler output, allowing shell redirection such as `hive code.bee > output.nj`.

#### Translation Orchestrator

`src/translator/mod.rs` is the compiler subsystem façade and likely coordinates the translation pipeline. Its responsibility is to move source text through lexical analysis, intermediate representation construction, lowering/code generation, and final cleanup while surfacing compilation/debug information back to the CLI.

#### Front End: Tokens and Source Semantics

`src/translator/tokenizer.rs` converts Bee source into tokens for supported language constructs: integer variables, string output, integer printing, and input. `src/translator/compiler.rs` consumes that representation and compiles Bee statements into target-oriented operations. This is the key language boundary: Bee syntax and semantics are separated from NJ emission.

#### Intermediate Representation and Lowering

`src/translator/intermediate_language.rs` defines the compiler’s internal instruction layer between Bee parsing/compilation and textual NJ. It centralizes target operations such as pointer movement, immediate loads, variable storage/loading, and output. `src/translator/compiler.rs` produces this representation; downstream stages serialize/lower it to NJ-like code.

#### Stateful Target Concerns

`src/translator/memory_manager.rs` manages the Brainfuck-style tape model: variable-to-cell allocation and pointer/cell bookkeeping. It is architecturally necessary because generated NJ instructions depend on stable memory locations and explicit pointer positioning. `src/translator/func_call.rs` handles compilation of built-in language actions such as output and input, translating higher-level calls into the required intermediate/target sequences.

#### Output Finalization and Delivery

`src/translator/cleanup.rs` performs final output cleanup, likely removing or normalizing redundant generated instructions before NJ text is returned to stdout. `src/translator/intermediate_language.rs` and `src/translator/cleanup.rs` form the last compiler boundary before emitted code. Release packaging is automated by `.github/workflows/release.yml`; no external runtime service is required beyond the local Rust executable and source file.

Main entry points: [`src/translator/compiler.rs`](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/compiler.rs) (Bee compiler), [`src/translator/mod.rs`](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/mod.rs) (Translator façade), [`src/translator/intermediate_language.rs`](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/intermediate_language.rs) (Intermediate language), [`src/cli.rs`](https://github.com/ak47andrew/bee_hive/blob/master/src/cli.rs) (Command handling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI executable"]
  node_bee_source["Bee source &#40;.bee&#41;<br/>source input"]
  node_main["Executable entry<br/>Rust binary<br/>[main.rs]"]
  node_cli_handler["Command handling<br/>CLI boundary<br/>[cli.rs]"]
  node_nj_output["NJ code<br/>compiler output"]
end

subgraph group_frontend["Bee front end"]
  node_tokenizer["Tokenizer<br/>lexer<br/>[tokenizer.rs]"]
  node_compiler["Bee compiler<br/>semantic compiler<br/>[compiler.rs]"]
  node_function_calls["Built-in calls<br/>call lowering<br/>[func_call.rs]"]
end

subgraph group_translation["Translation pipeline"]
  node_translator{{"Translator façade<br/>compiler orchestrator<br/>[mod.rs]"}}
  node_memory_manager["Tape memory manager<br/>allocation state<br/>[memory_manager.rs]"]
  node_intermediate_language["Intermediate language<br/>IR"]
  node_cleanup["Output cleanup<br/>finalization pass<br/>[cleanup.rs]"]
end

subgraph group_delivery["Distribution"]
  node_release_workflow["Release workflow<br/>GitHub Actions<br/>[release.yml]"]
  node_cargo_release["Cargo and release artifacts<br/>distribution"]
end

node_bee_source -->|"source path"| node_cli_handler
node_main -->|"delegates"| node_cli_handler
node_cli_handler -->|"source text + debug"| node_translator
node_translator -->|"lexes"| node_tokenizer
node_tokenizer -->|"tokens"| node_compiler
node_compiler -->|"built-in actions"| node_function_calls
node_compiler -->|"variables"| node_memory_manager
node_memory_manager -->|"cell locations"| node_intermediate_language
node_function_calls -->|"lowered operations"| node_intermediate_language
node_compiler -->|"IR operations"| node_intermediate_language
node_intermediate_language -->|"generated instructions"| node_cleanup
node_cleanup -->|"final NJ"| node_translator
node_translator -->|"writes stdout"| node_nj_output
node_release_workflow -->|"builds and publishes"| node_cargo_release
node_cargo_release -.->|"distributes binary"| node_main

click node_main "https://github.com/ak47andrew/bee_hive/blob/master/src/main.rs"
click node_cli_handler "https://github.com/ak47andrew/bee_hive/blob/master/src/cli.rs"
click node_translator "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/mod.rs"
click node_tokenizer "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/tokenizer.rs"
click node_compiler "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/compiler.rs"
click node_function_calls "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/func_call.rs"
click node_memory_manager "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/memory_manager.rs"
click node_intermediate_language "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/intermediate_language.rs"
click node_cleanup "https://github.com/ak47andrew/bee_hive/blob/master/src/translator/cleanup.rs"
click node_release_workflow "https://github.com/ak47andrew/bee_hive/blob/master/.github/workflows/release.yml"

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_bee_source,node_main,node_cli_handler,node_nj_output toneBlue
class node_tokenizer,node_compiler,node_function_calls toneAmber
class node_translator,node_memory_manager,node_intermediate_language,node_cleanup toneMint
class node_release_workflow,node_cargo_release toneRose
```

## Components

### CLI executable

- **Bee source (.bee)**: source input · User-provided program file.
- [Executable entry](https://github.com/ak47andrew/bee_hive/blob/master/src/main.rs): Rust binary · `src/main.rs`
- [Command handling](https://github.com/ak47andrew/bee_hive/blob/master/src/cli.rs): CLI boundary · Accepts a source path and optional debug mode. · `src/cli.rs`
- **NJ code**: compiler output · Emitted to standard output for shell redirection.

### Bee front end

- [Tokenizer](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/tokenizer.rs): lexer · Converts Bee source text into tokens. · `src/translator/tokenizer.rs`
- [Bee compiler](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/compiler.rs): semantic compiler · Compiles Bee statements into target-oriented operations. · `src/translator/compiler.rs`
- [Built-in calls](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/func_call.rs): call lowering · Lowers Bee input and output actions. · `src/translator/func_call.rs`

### Translation pipeline

- [Translator façade](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/mod.rs): compiler orchestrator · Coordinates compilation and returns generated NJ. · `src/translator/mod.rs`
- [Tape memory manager](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/memory_manager.rs): allocation state · Tracks variable cells and target pointer position. · `src/translator/memory_manager.rs`
- [Intermediate language](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/intermediate_language.rs): IR · Target operations for movement, loads, storage, and output. · `src/translator/intermediate_language.rs`
- [Output cleanup](https://github.com/ak47andrew/bee_hive/blob/master/src/translator/cleanup.rs): finalization pass · Normalizes generated target instructions. · `src/translator/cleanup.rs`

### Distribution

- [Release workflow](https://github.com/ak47andrew/bee_hive/blob/master/.github/workflows/release.yml): GitHub Actions · Builds and publishes release artifacts. · `.github/workflows/release.yml`
- **Cargo and release artifacts**: distribution · Delivers the Rust CLI through crates.io and releases.

## Connections

- Bee source (.bee) → Command handling: source path
- Executable entry → Command handling: delegates
- Command handling → Translator façade: source text + debug
- Translator façade → Tokenizer: lexes
- Tokenizer → Bee compiler: tokens
- Bee compiler → Built-in calls: built-in actions
- Bee compiler → Tape memory manager: variables
- Tape memory manager → Intermediate language: cell locations
- Built-in calls → Intermediate language: lowered operations
- Bee compiler → Intermediate language: IR operations
- Intermediate language → Output cleanup: generated instructions
- Output cleanup → Translator façade: final NJ
- Translator façade → NJ code: writes stdout
- Release workflow → Cargo and release artifacts: builds and publishes
- Cargo and release artifacts → Executable entry: distributes binary