# dvtate/postfix-haskell architecture

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

- Interactive diagram: https://gitdiagram.com/dvtate/postfix-haskell
- Repository: https://github.com/dvtate/postfix-haskell

## Overview

postfix-haskell is a low-level functional language compiler targeting WebAssembly. Users enter code through the interactive shell or compile a source file; both paths lex and interpret it, then produce WebAssembly Text. The compiler’s central context manages language values, macros, namespaces, and module imports, while expression nodes represent generated code. The README also documents branching, enums, inline assembly, and an embeddable API. Some subsystem links are based on documented capabilities and tree paths because their implementation was not sampled.

Main entry points: [`lib/context.ts`](https://github.com/dvtate/postfix-haskell/blob/master/lib/context.ts) (Compiler context), [`lib/wat.ts`](https://github.com/dvtate/postfix-haskell/blob/master/lib/wat.ts) (WAT generation), [`index.ts`](https://github.com/dvtate/postfix-haskell/blob/master/index.ts) (CLI), [`tools/file.ts`](https://github.com/dvtate/postfix-haskell/blob/master/tools/file.ts) (File compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_cli["CLI<br/>[index.ts]"]
  node_file["File compiler<br/>[file.ts]"]
  node_shell["Interactive shell<br/>[shell.ts]"]
end

subgraph group_language["Language processing"]
  node_lexer["Lexer<br/>[scan.ts]"]
  node_parser["Parser<br/>[parse.ts]"]
  node_context["Compiler context<br/>[context.ts]"]
  node_values["Values and types<br/>[value.ts]"]
  node_globals["Macros and operators<br/>[globals.ts]"]
  node_namespaces["Namespaces<br/>[namespace.ts]"]
  node_modules["Module manager<br/>[module.ts]"]
end

subgraph group_backend["WebAssembly backend"]
  node_expressions["Expression IR<br/>[index.ts]"]
  node_functions["Functions and closures<br/>[func.ts]"]
  node_wat["WAT generation<br/>[wat.ts]"]
  node_runtime["Wasm runtime<br/>[rt.wat]"]
  node_no_runtime["Runtime-free mode<br/>[no_rt.wat]"]
end

subgraph group_library["Language library"]
  node_standard_library["Standard library<br/>[lang.phs]"]
end

node_user(("Programmer"))
node_wasm_text["WAT output"]
node_wabt["WABT validator"]
node_binaryen["Binaryen optimizer"]

node_user -->|"runs command"| node_cli
node_cli -->|"starts shell"| node_shell
node_cli -->|"compiles file"| node_file
node_user -->|"enters code"| node_shell
node_file -->|"lexes source"| node_lexer
node_shell -->|"lexes input"| node_lexer
node_lexer -->|"supplies tokens"| node_parser
node_parser -->|"interprets tokens"| node_context
node_context -->|"invokes operators"| node_globals
node_context -->|"manages values"| node_values
node_context -->|"resolves names"| node_namespaces
node_context -->|"manages imports"| node_modules
node_context -->|"builds expressions"| node_expressions
node_expressions -->|"represents functions"| node_functions
node_context -->|"generates output"| node_wat
node_wat -->|"includes runtime"| node_runtime
node_wat -.->|"omits runtime"| node_no_runtime
node_wat -->|"validates output"| node_wabt
node_file -.->|"optimizes output"| node_binaryen
node_wat -->|"returns WAT"| node_wasm_text
node_user -->|"imports features"| node_standard_library
node_standard_library -->|"defines language operators"| node_context

click node_cli "https://github.com/dvtate/postfix-haskell/blob/master/index.ts"
click node_file "https://github.com/dvtate/postfix-haskell/blob/master/tools/file.ts"
click node_shell "https://github.com/dvtate/postfix-haskell/blob/master/tools/shell.ts"
click node_lexer "https://github.com/dvtate/postfix-haskell/blob/master/lib/scan.ts"
click node_parser "https://github.com/dvtate/postfix-haskell/blob/master/lib/parse.ts"
click node_context "https://github.com/dvtate/postfix-haskell/blob/master/lib/context.ts"
click node_values "https://github.com/dvtate/postfix-haskell/blob/master/lib/value.ts"
click node_globals "https://github.com/dvtate/postfix-haskell/blob/master/lib/globals.ts"
click node_namespaces "https://github.com/dvtate/postfix-haskell/blob/master/lib/namespace.ts"
click node_modules "https://github.com/dvtate/postfix-haskell/blob/master/lib/module.ts"
click node_expressions "https://github.com/dvtate/postfix-haskell/blob/master/lib/expr/index.ts"
click node_functions "https://github.com/dvtate/postfix-haskell/blob/master/lib/expr/func.ts"
click node_wat "https://github.com/dvtate/postfix-haskell/blob/master/lib/wat.ts"
click node_runtime "https://github.com/dvtate/postfix-haskell/blob/master/lib/rt.wat"
click node_no_runtime "https://github.com/dvtate/postfix-haskell/blob/master/lib/no_rt.wat"
click node_standard_library "https://github.com/dvtate/postfix-haskell/blob/master/std/lang.phs"

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_cli,node_file,node_shell toneBlue
class node_lexer,node_parser,node_context,node_values,node_globals,node_namespaces,node_modules toneAmber
class node_expressions,node_functions,node_wat,node_runtime,node_no_runtime toneMint
class node_standard_library toneRose
class node_user,node_wasm_text,node_wabt,node_binaryen toneIndigo
```

## Components

### User entry

- [CLI](https://github.com/dvtate/postfix-haskell/blob/master/index.ts): `index.ts`
- [File compiler](https://github.com/dvtate/postfix-haskell/blob/master/tools/file.ts): `tools/file.ts`
- [Interactive shell](https://github.com/dvtate/postfix-haskell/blob/master/tools/shell.ts): `tools/shell.ts`

### Language processing

- [Lexer](https://github.com/dvtate/postfix-haskell/blob/master/lib/scan.ts): `lib/scan.ts`
- [Parser](https://github.com/dvtate/postfix-haskell/blob/master/lib/parse.ts): `lib/parse.ts`
- [Compiler context](https://github.com/dvtate/postfix-haskell/blob/master/lib/context.ts): `lib/context.ts`
- [Values and types](https://github.com/dvtate/postfix-haskell/blob/master/lib/value.ts): `lib/value.ts`
- [Macros and operators](https://github.com/dvtate/postfix-haskell/blob/master/lib/globals.ts): `lib/globals.ts`
- [Namespaces](https://github.com/dvtate/postfix-haskell/blob/master/lib/namespace.ts): `lib/namespace.ts`
- [Module manager](https://github.com/dvtate/postfix-haskell/blob/master/lib/module.ts): `lib/module.ts`

### WebAssembly backend

- [Expression IR](https://github.com/dvtate/postfix-haskell/blob/master/lib/expr/index.ts): `lib/expr/index.ts`
- [Functions and closures](https://github.com/dvtate/postfix-haskell/blob/master/lib/expr/func.ts): `lib/expr/func.ts`
- [WAT generation](https://github.com/dvtate/postfix-haskell/blob/master/lib/wat.ts): `lib/wat.ts`
- [Wasm runtime](https://github.com/dvtate/postfix-haskell/blob/master/lib/rt.wat): `lib/rt.wat`
- [Runtime-free mode](https://github.com/dvtate/postfix-haskell/blob/master/lib/no_rt.wat): `lib/no_rt.wat`

### Language library

- [Standard library](https://github.com/dvtate/postfix-haskell/blob/master/std/lang.phs): `std/lang.phs`

### Other components

- **Programmer**
- **WAT output**
- **WABT validator**
- **Binaryen optimizer**

## Connections

- Programmer → CLI: runs command
- CLI → Interactive shell: starts shell
- CLI → File compiler: compiles file
- Programmer → Interactive shell: enters code
- File compiler → Lexer: lexes source
- Interactive shell → Lexer: lexes input
- Lexer → Parser: supplies tokens
- Parser → Compiler context: interprets tokens
- Compiler context → Macros and operators: invokes operators
- Compiler context → Values and types: manages values
- Compiler context → Namespaces: resolves names
- Compiler context → Module manager: manages imports
- Compiler context → Expression IR: builds expressions
- Expression IR → Functions and closures: represents functions
- Compiler context → WAT generation: generates output
- WAT generation → Wasm runtime: includes runtime
- WAT generation → Runtime-free mode: omits runtime
- WAT generation → WABT validator: validates output
- File compiler → Binaryen optimizer: optimizes output
- WAT generation → WAT output: returns WAT
- Programmer → Standard library: imports features
- Standard library → Compiler context: defines language operators