# unight0/xt architecture

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

- Interactive diagram: https://gitdiagram.com/unight0/xt
- Repository: https://github.com/unight0/xt

## Overview

#### Purpose and Entry Point
XT is a minimal interactive FORTH interpreter written in C. The build produces an `xt` executable (via `Makefile`); runtime input is interpreted directly, optionally preloading a FORTH source file such as `basis.f`.

Core startup and interpreter control are centered in:
- `xt.c`
- `input.c`
- `input.h`

#### Execution Model
The interpreter implements a classic stack-language loop: read source/input, tokenize it, resolve words in a dictionary, then execute primitive C implementations or compiled/interpreted FORTH definitions. The primary control boundary is between host-side C runtime code and user-visible FORTH words.

Relevant components:
- `xt.c`
- `lexer.c`
- `token.h`

#### Lexing and Input Sources
Input handling supports interactive input and source-file loading. The lexer converts character streams into FORTH tokens consumed by the interpreter/compiler path; this separates raw file/terminal input from language semantics.

Primary paths:
- `input.c`
- `input.h`
- `lexer.c`
- `lexer.h`

#### Dictionary and Word Resolution
The dictionary is the language’s central symbol table for named FORTH words. It supports lookup and likely definition/registration of both builtins and words loaded from FORTH files. This is the key extension boundary: `basis.f` can add standard-language behavior without changing the C executable.

Primary paths:
- `dict.c`
- `dict.h`
- `defs.h`

#### Runtime Stacks and Memory
FORTH execution state is stack-oriented. Stack operations are isolated behind a dedicated module, while shared runtime memory/layout declarations are collected separately. These components underpin data passing, return/control behavior, and compiled-word execution.

Primary paths:
- `stack.c`
- `stack.h`
- `memory.h`

#### Builtin Primitive Layer
C-defined builtins provide the interpreter’s fundamental operations and bridge language words to host execution. They are declared separately from their implementation and registered into the dictionary during runtime initialization.

Primary paths:
- `builtins.c`
- `builtins.h`
- `dict.h`

#### Standard Library and User Programs
`basis.f` is the standard FORTH library and is normally passed at startup to make the minimal core usable. Additional programs are loaded through FORTH-level inclusion, demonstrated by the example sources. These files execute within the same dictionary/stack runtime rather than through a separate application or service layer.

Primary paths:
- `basis.f`
- `examples/quine.f`
- `examples/list.f`

#### Infrastructure and External Dependencies
The repository is a native C program built with `make`; no web runtime, database, cloud infrastructure, or external service integration is indicated. Runtime interaction is local terminal/file I/O.

Primary path:
- `Makefile`

Main entry points: [`input.c`](https://github.com/unight0/xt/blob/master/input.c) (Input sources), [`xt.c`](https://github.com/unight0/xt/blob/master/xt.c) (Startup & control loop), [`dict.c`](https://github.com/unight0/xt/blob/master/dict.c) (Dictionary), [`lexer.c`](https://github.com/unight0/xt/blob/master/lexer.c) (Lexer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["C runtime"]
  node_make["Make build"]
  node_exe{{"xt executable<br/>native executable"}}
  node_startup["Startup &amp; control loop<br/>interpreter control<br/>[xt.c]"]
  node_input["Input sources<br/>terminal/file I/O<br/>[input.c]"]
  node_input_api["Input API<br/>C header<br/>[input.h]"]
  node_lexer["Lexer<br/>tokenizer<br/>[lexer.c]"]
  node_lexer_api["Lexer API<br/>C header<br/>[lexer.h]"]
  node_tokens["Token model<br/>language types<br/>[token.h]"]
  node_dictionary[("Dictionary<br/>word symbol table<br/>[dict.c]")]
  node_dict_api["Dictionary API<br/>C header<br/>[dict.h]"]
  node_definitions["Runtime definitions<br/>shared declarations<br/>[defs.h]"]
  node_builtins["C primitives<br/>builtin words<br/>[builtins.c]"]
  node_builtins_api["Builtin API<br/>C header<br/>[builtins.h]"]
  node_stacks["Runtime stacks<br/>execution state<br/>[stack.c]"]
  node_stack_api["Stack API<br/>C header<br/>[stack.h]"]
  node_memory["Memory layout<br/>shared declarations<br/>[memory.h]"]
end

subgraph group_forth["FORTH sources"]
  node_basis["Standard library<br/>FORTH source<br/>[basis.f]"]
  node_quine["Quine example<br/>FORTH program<br/>[quine.f]"]
  node_list["List example<br/>FORTH program<br/>[list.f]"]
end

node_make -->|"builds"| node_exe
node_exe -->|"starts"| node_startup
node_startup -->|"reads"| node_input
node_input -.->|"implements"| node_input_api
node_input -->|"character stream"| node_lexer
node_lexer -.->|"implements"| node_lexer_api
node_lexer -->|"emits"| node_tokens
node_startup -->|"resolves words"| node_dictionary
node_dictionary -.->|"implements"| node_dict_api
node_dictionary -->|"uses"| node_definitions
node_builtins -.->|"implements"| node_builtins_api
node_builtins -->|"registers primitives"| node_dictionary
node_startup -->|"initializes"| node_builtins
node_startup -->|"executes with"| node_stacks
node_stacks -.->|"implements"| node_stack_api
node_stacks -->|"uses"| node_memory
node_basis -->|"preloaded as source"| node_input
node_basis -->|"defines words"| node_dictionary
node_quine -->|"loaded as source"| node_input
node_list -->|"loaded as source"| node_input

click node_make "https://github.com/unight0/xt/blob/master/Makefile"
click node_startup "https://github.com/unight0/xt/blob/master/xt.c"
click node_input "https://github.com/unight0/xt/blob/master/input.c"
click node_input_api "https://github.com/unight0/xt/blob/master/input.h"
click node_lexer "https://github.com/unight0/xt/blob/master/lexer.c"
click node_lexer_api "https://github.com/unight0/xt/blob/master/lexer.h"
click node_tokens "https://github.com/unight0/xt/blob/master/token.h"
click node_dictionary "https://github.com/unight0/xt/blob/master/dict.c"
click node_dict_api "https://github.com/unight0/xt/blob/master/dict.h"
click node_definitions "https://github.com/unight0/xt/blob/master/defs.h"
click node_builtins "https://github.com/unight0/xt/blob/master/builtins.c"
click node_builtins_api "https://github.com/unight0/xt/blob/master/builtins.h"
click node_stacks "https://github.com/unight0/xt/blob/master/stack.c"
click node_stack_api "https://github.com/unight0/xt/blob/master/stack.h"
click node_memory "https://github.com/unight0/xt/blob/master/memory.h"
click node_basis "https://github.com/unight0/xt/blob/master/basis.f"
click node_quine "https://github.com/unight0/xt/blob/master/examples/quine.f"
click node_list "https://github.com/unight0/xt/blob/master/examples/list.f"

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_make,node_exe,node_startup,node_input,node_input_api,node_lexer,node_lexer_api,node_tokens,node_dictionary,node_dict_api,node_definitions,node_builtins,node_builtins_api,node_stacks,node_stack_api,node_memory toneBlue
class node_basis,node_quine,node_list toneAmber
```

## Components

### C runtime

Native interpreter modules.

- [Make build](https://github.com/unight0/xt/blob/master/Makefile): build · Builds the native executable. · `Makefile`
- **xt executable**: native executable
- [Startup & control loop](https://github.com/unight0/xt/blob/master/xt.c): interpreter control · Initializes runtime and drives read-token-execute. · `xt.c`
- [Input sources](https://github.com/unight0/xt/blob/master/input.c): terminal/file I/O · Reads interactive input and preload files. · `input.c`
- [Input API](https://github.com/unight0/xt/blob/master/input.h): C header · `input.h`
- [Lexer](https://github.com/unight0/xt/blob/master/lexer.c): tokenizer · Converts character streams into FORTH tokens. · `lexer.c`
- [Lexer API](https://github.com/unight0/xt/blob/master/lexer.h): C header · `lexer.h`
- [Token model](https://github.com/unight0/xt/blob/master/token.h): language types · `token.h`
- [Dictionary](https://github.com/unight0/xt/blob/master/dict.c): word symbol table · Resolves and registers named FORTH words. · `dict.c`
- [Dictionary API](https://github.com/unight0/xt/blob/master/dict.h): C header · `dict.h`
- [Runtime definitions](https://github.com/unight0/xt/blob/master/defs.h): shared declarations · `defs.h`
- [C primitives](https://github.com/unight0/xt/blob/master/builtins.c): builtin words · Host implementations of fundamental FORTH operations. · `builtins.c`
- [Builtin API](https://github.com/unight0/xt/blob/master/builtins.h): C header · `builtins.h`
- [Runtime stacks](https://github.com/unight0/xt/blob/master/stack.c): execution state · Provides stack-oriented data and control state. · `stack.c`
- [Stack API](https://github.com/unight0/xt/blob/master/stack.h): C header · `stack.h`
- [Memory layout](https://github.com/unight0/xt/blob/master/memory.h): shared declarations · `memory.h`

### FORTH sources

Library and programs loaded by the interpreter.

- [Standard library](https://github.com/unight0/xt/blob/master/basis.f): FORTH source · Normally preloaded to extend the minimal core. · `basis.f`
- [Quine example](https://github.com/unight0/xt/blob/master/examples/quine.f): FORTH program · `examples/quine.f`
- [List example](https://github.com/unight0/xt/blob/master/examples/list.f): FORTH program · `examples/list.f`

## Connections

- Make build → xt executable: builds
- xt executable → Startup & control loop: starts
- Startup & control loop → Input sources: reads
- Input sources → Input API: implements
- Input sources → Lexer: character stream
- Lexer → Lexer API: implements
- Lexer → Token model: emits
- Startup & control loop → Dictionary: resolves words
- Dictionary → Dictionary API: implements
- Dictionary → Runtime definitions: uses
- C primitives → Builtin API: implements
- C primitives → Dictionary: registers primitives
- Startup & control loop → C primitives: initializes
- Startup & control loop → Runtime stacks: executes with
- Runtime stacks → Stack API: implements
- Runtime stacks → Memory layout: uses
- Standard library → Input sources: preloaded as source
- Standard library → Dictionary: defines words
- Quine example → Input sources: loaded as source
- List example → Input sources: loaded as source