# nimblemachines/muforth architecture

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

- Interactive diagram: https://gitdiagram.com/nimblemachines/muforth
- Repository: https://github.com/nimblemachines/muforth

## Overview

muforth is a host-side, indirect-threaded Forth used primarily as a tethered cross-compiler and interactive tool for embedded systems. The documented workflow is to start the host, load its Forth environment, choose a target build environment, compile code on the host, then transfer and execute the result on a device. The README documents this workflow and supported architecture families; source excerpts show the executable entry point and core runtime responsibilities, but do not expose most target-specific call paths.

Main entry points: [`src/muforth.h`](https://github.com/nimblemachines/muforth/blob/master/src/muforth.h) (Runtime definitions), [`mu/target`](https://github.com/nimblemachines/muforth/tree/master/mu/target) (Target environments), [`src/spleen_font.c`](https://github.com/nimblemachines/muforth/blob/master/src/spleen_font.c) (Spleen font data), [`src/main.c`](https://github.com/nimblemachines/muforth/blob/master/src/main.c) (Host executable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["Host Forth runtime"]
  node_host_cli["Host executable<br/>[main.c]"]
  node_runtime["Forth initialization<br/>[muforth.c]"]
  node_startup["Forth startup<br/>[startup.mu4]"]
  node_dictionary[("Dictionary<br/>[dict.c]")]
  node_execution["ITC engine<br/>[engine-itc.c]"]
  node_primitives["Core primitives<br/>[kernel.c]"]
  node_multiprecision["Extended arithmetic<br/>[mp-math.c]"]
  node_font_data["Spleen font data<br/>[spleen_font.c]"]
  node_font_8["8×16 font table<br/>[spleen8x16.h]"]
  node_font_12["12×24 font table<br/>[spleen12x24.h]"]
  node_shared_defs["Runtime definitions<br/>[muforth.h]"]
end

subgraph group_cross["Cross compilation"]
  node_target_env["Target environments"]
  node_target_asm["Assemblers"]
  node_target_tools["Target tools"]
  node_bitmap_font["Bitmap fonts"]
end

subgraph group_targets["Embedded targets"]
  node_compiled_image["Compiled code"]
  node_device(("Microcontroller"))
  node_midi_projects["MIDI projects"]
end

subgraph group_io["Host interfaces"]
  node_file_ops["File primitives<br/>[file.c]"]
  node_terminal["Terminal support<br/>[tty.c]"]
  node_usb_linux["Linux USB<br/>[usb-linux.c]"]
  node_usb_darwin["macOS USB<br/>[usb-darwin.c]"]
end

node_developer(("Developer"))

node_developer -->|"starts"| node_host_cli
node_host_cli -->|"calls init/start"| node_runtime
node_runtime -->|"loads at startup"| node_startup
node_developer -->|"chooses target"| node_target_env
node_target_env -->|"provides tools"| node_target_asm
node_target_env -->|"provides tools"| node_target_tools
node_developer -->|"interacts with"| node_startup
node_target_asm -->|"compiles for"| node_compiled_image
node_target_tools -.->|"supports bring-up"| node_device
node_compiled_image -->|"transfers and runs"| node_device
node_file_ops -->|"uses declarations"| node_shared_defs
node_terminal -->|"uses declarations"| node_shared_defs
node_usb_linux -->|"uses declarations"| node_shared_defs
node_usb_darwin -->|"uses declarations"| node_shared_defs
node_font_data -->|"includes table"| node_font_8
node_font_data -->|"includes table"| node_font_12
node_bitmap_font -.->|"supports font generation"| node_compiled_image

click node_host_cli "https://github.com/nimblemachines/muforth/blob/master/src/main.c"
click node_runtime "https://github.com/nimblemachines/muforth/blob/master/src/muforth.c"
click node_startup "https://github.com/nimblemachines/muforth/blob/master/mu/startup.mu4"
click node_dictionary "https://github.com/nimblemachines/muforth/blob/master/src/dict.c"
click node_execution "https://github.com/nimblemachines/muforth/blob/master/src/engine-itc.c"
click node_primitives "https://github.com/nimblemachines/muforth/blob/master/src/kernel.c"
click node_multiprecision "https://github.com/nimblemachines/muforth/blob/master/src/mp-math.c"
click node_file_ops "https://github.com/nimblemachines/muforth/blob/master/src/file.c"
click node_terminal "https://github.com/nimblemachines/muforth/blob/master/src/tty.c"
click node_usb_linux "https://github.com/nimblemachines/muforth/blob/master/src/usb-linux.c"
click node_usb_darwin "https://github.com/nimblemachines/muforth/blob/master/src/usb-darwin.c"
click node_target_env "https://github.com/nimblemachines/muforth/tree/master/mu/target"
click node_target_asm "https://github.com/nimblemachines/muforth/tree/master/mu/target"
click node_target_tools "https://github.com/nimblemachines/muforth/tree/master/mu/target"
click node_compiled_image "https://github.com/nimblemachines/muforth/tree/master/mu/target"
click node_bitmap_font "https://github.com/nimblemachines/muforth/tree/master/mu/bitmap-font"
click node_midi_projects "https://github.com/nimblemachines/muforth/tree/master/mu/target/6809/midi"
click node_font_data "https://github.com/nimblemachines/muforth/blob/master/src/spleen_font.c"
click node_font_8 "https://github.com/nimblemachines/muforth/blob/master/src/spleen8x16.h"
click node_font_12 "https://github.com/nimblemachines/muforth/blob/master/src/spleen12x24.h"
click node_shared_defs "https://github.com/nimblemachines/muforth/blob/master/src/muforth.h"

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_host_cli,node_runtime,node_startup,node_dictionary,node_execution,node_primitives,node_multiprecision,node_font_data,node_font_8,node_font_12,node_shared_defs toneBlue
class node_target_env,node_target_asm,node_target_tools,node_bitmap_font toneAmber
class node_compiled_image,node_device,node_midi_projects toneMint
class node_file_ops,node_terminal,node_usb_linux,node_usb_darwin toneRose
class node_developer toneIndigo
```

## Components

### Host Forth runtime

- [Host executable](https://github.com/nimblemachines/muforth/blob/master/src/main.c): `src/main.c`
- [Forth initialization](https://github.com/nimblemachines/muforth/blob/master/src/muforth.c): `src/muforth.c`
- [Forth startup](https://github.com/nimblemachines/muforth/blob/master/mu/startup.mu4): `mu/startup.mu4`
- [Dictionary](https://github.com/nimblemachines/muforth/blob/master/src/dict.c): `src/dict.c`
- [ITC engine](https://github.com/nimblemachines/muforth/blob/master/src/engine-itc.c): `src/engine-itc.c`
- [Core primitives](https://github.com/nimblemachines/muforth/blob/master/src/kernel.c): `src/kernel.c`
- [Extended arithmetic](https://github.com/nimblemachines/muforth/blob/master/src/mp-math.c): `src/mp-math.c`
- [Spleen font data](https://github.com/nimblemachines/muforth/blob/master/src/spleen_font.c): `src/spleen_font.c`
- [8×16 font table](https://github.com/nimblemachines/muforth/blob/master/src/spleen8x16.h): `src/spleen8x16.h`
- [12×24 font table](https://github.com/nimblemachines/muforth/blob/master/src/spleen12x24.h): `src/spleen12x24.h`
- [Runtime definitions](https://github.com/nimblemachines/muforth/blob/master/src/muforth.h): `src/muforth.h`

### Cross compilation

- [Target environments](https://github.com/nimblemachines/muforth/tree/master/mu/target): `mu/target`
- [Assemblers](https://github.com/nimblemachines/muforth/tree/master/mu/target): `mu/target`
- [Target tools](https://github.com/nimblemachines/muforth/tree/master/mu/target): `mu/target`
- [Bitmap fonts](https://github.com/nimblemachines/muforth/tree/master/mu/bitmap-font): `mu/bitmap-font`

### Embedded targets

- [Compiled code](https://github.com/nimblemachines/muforth/tree/master/mu/target): `mu/target`
- **Microcontroller**
- [MIDI projects](https://github.com/nimblemachines/muforth/tree/master/mu/target/6809/midi): `mu/target/6809/midi`

### Host interfaces

- [File primitives](https://github.com/nimblemachines/muforth/blob/master/src/file.c): `src/file.c`
- [Terminal support](https://github.com/nimblemachines/muforth/blob/master/src/tty.c): `src/tty.c`
- [Linux USB](https://github.com/nimblemachines/muforth/blob/master/src/usb-linux.c): `src/usb-linux.c`
- [macOS USB](https://github.com/nimblemachines/muforth/blob/master/src/usb-darwin.c): `src/usb-darwin.c`

### Other components

- **Developer**

## Connections

- Developer → Host executable: starts (evidence: `README.md`)
- Host executable → Forth initialization: calls init/start (evidence: `src/main.c`)
- Forth initialization → Forth startup: loads at startup (evidence: `README.md`)
- Developer → Target environments: chooses target (evidence: `README.md`)
- Target environments → Assemblers: provides tools (evidence: `README.md`)
- Target environments → Target tools: provides tools (evidence: `README.md`)
- Developer → Forth startup: interacts with (evidence: `README.md`)
- Assemblers → Compiled code: compiles for (evidence: `README.md`)
- Target tools → Microcontroller: supports bring-up
- Compiled code → Microcontroller: transfers and runs (evidence: `README.md`)
- File primitives → Runtime definitions: uses declarations (evidence: `src/file.c`)
- Terminal support → Runtime definitions: uses declarations (evidence: `src/tty.c`)
- Linux USB → Runtime definitions: uses declarations (evidence: `src/usb-linux.c`)
- macOS USB → Runtime definitions: uses declarations (evidence: `src/usb-darwin.c`)
- Spleen font data → 8×16 font table: includes table (evidence: `src/spleen_font.c`)
- Spleen font data → 12×24 font table: includes table (evidence: `src/spleen_font.c`)
- Bitmap fonts → Compiled code: supports font generation
