# carlosrabelo/pforth architecture

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

- Interactive diagram: https://gitdiagram.com/carlosrabelo/pforth
- Repository: https://github.com/carlosrabelo/pforth

## Overview

PForth is a deterministic 16-bit Forth interpreter/compiler implemented in C++, Go, Pascal, and Rust, with shared Forth libraries and demo programs. The user workflow is to launch a port, provide Forth source files or interactive input, and have that port’s runtime interpret or compile and execute the words, producing console output. The sampled C++, Go, and Rust sources show their CLI-to-runtime flow; Pascal and the shared Forth assets are documented in the README but their runtime wiring was not sampled.

Main entry points: [`cpp/pforth/src/cli.cpp`](https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/cli.cpp) (C++ CLI), [`go/pforth/cmd/pforth/main.go`](https://github.com/carlosrabelo/pforth/blob/master/go/pforth/cmd/pforth/main.go) (Go CLI), [`rust/pforth/src/main.rs`](https://github.com/carlosrabelo/pforth/blob/master/rust/pforth/src/main.rs) (Rust CLI), [`cpp/pforth/src/forth.cpp`](https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/forth.cpp) (C++ Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Command Interfaces"]
  node_cpp_cli["C++ CLI<br/>[cli.cpp]"]
  node_go_cli["Go CLI<br/>[main.go]"]
  node_rust_cli["Rust CLI<br/>[main.rs]"]
end

subgraph group_runtimes["Forth Runtimes"]
  node_cpp_engine["C++ Engine<br/>[forth.cpp]"]
  node_go_engine["Go Engine<br/>[forth.go]"]
  node_rust_engine["Rust Engine<br/>[forth.rs]"]
  node_pascal_app["Pascal Port"]
end

subgraph group_assets["Forth Programs"]
  node_shared_libs["Shared Libraries"]
  node_demo_programs["Demo Programs"]
end

node_user(("User"))
node_console(("Console I/O"))

node_user -->|"invokes"| node_cpp_cli
node_user -->|"invokes"| node_go_cli
node_user -->|"invokes"| node_rust_cli
node_user -->|"uses"| node_pascal_app
node_cpp_cli -->|"loads files; starts REPL"| node_cpp_engine
node_cpp_engine -->|"reads and writes"| node_console
node_go_cli -->|"initializes; loads; runs"| node_go_engine
node_go_engine -->|"reads and writes"| node_console
node_rust_cli -->|"parses; runs"| node_rust_engine
node_rust_engine -.->|"reads and writes"| node_console
node_pascal_app -.->|"interacts"| node_console

click node_cpp_cli "https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/cli.cpp"
click node_cpp_engine "https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/forth.cpp"
click node_go_cli "https://github.com/carlosrabelo/pforth/blob/master/go/pforth/cmd/pforth/main.go"
click node_go_engine "https://github.com/carlosrabelo/pforth/blob/master/go/pforth/internal/forth/forth.go"
click node_rust_cli "https://github.com/carlosrabelo/pforth/blob/master/rust/pforth/src/main.rs"
click node_rust_engine "https://github.com/carlosrabelo/pforth/blob/master/rust/pforth/src/forth.rs"
click node_pascal_app "https://github.com/carlosrabelo/pforth/tree/master/pascal/pforth/src"
click node_shared_libs "https://github.com/carlosrabelo/pforth/tree/master/pforth"
click node_demo_programs "https://github.com/carlosrabelo/pforth/tree/master/demos"

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_cpp_cli,node_go_cli,node_rust_cli,node_user toneBlue
class node_cpp_engine,node_go_engine,node_rust_engine,node_pascal_app toneAmber
class node_shared_libs,node_demo_programs toneMint
class node_console toneIndigo
```

## Components

### Command Interfaces

- [C++ CLI](https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/cli.cpp): `cpp/pforth/src/cli.cpp`
- [Go CLI](https://github.com/carlosrabelo/pforth/blob/master/go/pforth/cmd/pforth/main.go): `go/pforth/cmd/pforth/main.go`
- [Rust CLI](https://github.com/carlosrabelo/pforth/blob/master/rust/pforth/src/main.rs): `rust/pforth/src/main.rs`

### Forth Runtimes

- [C++ Engine](https://github.com/carlosrabelo/pforth/blob/master/cpp/pforth/src/forth.cpp): `cpp/pforth/src/forth.cpp`
- [Go Engine](https://github.com/carlosrabelo/pforth/blob/master/go/pforth/internal/forth/forth.go): `go/pforth/internal/forth/forth.go`
- [Rust Engine](https://github.com/carlosrabelo/pforth/blob/master/rust/pforth/src/forth.rs): `rust/pforth/src/forth.rs`
- [Pascal Port](https://github.com/carlosrabelo/pforth/tree/master/pascal/pforth/src): `pascal/pforth/src`

### Forth Programs

- [Shared Libraries](https://github.com/carlosrabelo/pforth/tree/master/pforth): `pforth`
- [Demo Programs](https://github.com/carlosrabelo/pforth/tree/master/demos): `demos`

### Other components

- **User**
- **Console I/O**

## Connections

- User → C++ CLI: invokes (evidence: `README.md`)
- User → Go CLI: invokes (evidence: `README.md`)
- User → Rust CLI: invokes (evidence: `README.md`)
- User → Pascal Port: uses (evidence: `README.md`)
- C++ CLI → C++ Engine: loads files; starts REPL (evidence: `cpp/pforth/src/cli.cpp`)
- C++ Engine → Console I/O: reads and writes (evidence: `cpp/pforth/src/forth.cpp`)
- Go CLI → Go Engine: initializes; loads; runs (evidence: `go/pforth/cmd/pforth/main.go`)
- Go Engine → Console I/O: reads and writes (evidence: `go/pforth/internal/forth/forth.go`)
- Rust CLI → Rust Engine: parses; runs (evidence: `rust/pforth/src/main.rs`)
- Rust Engine → Console I/O: reads and writes
- Pascal Port → Console I/O: interacts