# nxthingbutv0id/simpleassembler architecture

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

- Interactive diagram: https://gitdiagram.com/nxthingbutv0id/simpleassembler
- Repository: https://github.com/nxthingbutv0id/simpleassembler

## Overview

Simple Assembler is a Rust command-line assembler for BatPU-2 source. Its main workflow reads one or more assembly files, parses instructions, lays out and resolves the program, evaluates it, encodes instructions, and writes a binary file. The graph keeps the ISA model and operand types distinct from those processing stages. Relationships between the pipeline stages are explicit in `src/lib.rs`; some internal dependencies are based only on the SOURCE INDEX, so unsampled behavior is not expanded beyond those references.

Main entry points: [`src/architecture/batpu2/instruction.rs`](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/instruction.rs) (Instruction model), [`src/lib.rs`](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/lib.rs) (Assembler), [`src/parser/tokens.rs`](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/tokens.rs) (Token parsers), [`src/encode.rs`](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/encode.rs) (Instruction encoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pipeline["Assembly pipeline"]
  node_assembler["Assembler<br/>[lib.rs]"]
  node_layout["Program layout<br/>[layout.rs]"]
  node_resolve["Label resolution<br/>[resolve.rs]"]
  node_eval["Program evaluation<br/>[eval.rs]"]
  node_encoder["Instruction encoder<br/>[encode.rs]"]
  node_printer["Assembly printer<br/>[print.rs]"]
end

subgraph group_syntax["Assembly syntax"]
  node_parser["File parser<br/>[mod.rs]"]
  node_tokens["Token parsers<br/>[tokens.rs]"]
  node_wrappers["Instruction parsers<br/>[wrappers.rs]"]
end

subgraph group_isa["BatPU-2 model"]
  node_instruction["Instruction model<br/>[instruction.rs]"]
  node_opcode["Opcode set<br/>[opcode.rs]"]
end

subgraph group_operands["Operand types"]
  node_condition["Conditions<br/>[condition.rs]"]
  node_definition["Definitions<br/>[definition.rs]"]
  node_immediate["Immediate values<br/>[immediate.rs]"]
  node_label["Labels<br/>[label.rs]"]
  node_port["I/O ports<br/>[port.rs]"]
  node_register["Registers<br/>[register.rs]"]
end

node_developer(("Assembly author"))
node_cli["CLI<br/>[main.rs]"]
node_output["Binary file"]

node_developer -.->|"runs assembler"| node_cli
node_cli -.->|"invokes"| node_assembler
node_assembler -->|"parses files"| node_parser
node_parser -->|"dispatches parsers"| node_wrappers
node_wrappers -->|"builds instructions"| node_instruction
node_tokens -->|"parses opcodes"| node_opcode
node_tokens -->|"parses conditions"| node_condition
node_tokens -->|"parses definitions"| node_definition
node_tokens -->|"parses values"| node_immediate
node_tokens -->|"parses labels"| node_label
node_tokens -->|"parses ports"| node_port
node_tokens -->|"parses registers"| node_register
node_assembler -->|"lays out program"| node_layout
node_assembler -->|"resolves symbols"| node_resolve
node_assembler -->|"evaluates program"| node_eval
node_assembler -->|"encodes instructions"| node_encoder
node_assembler -->|"writes binary"| node_output
node_assembler -->|"prints assembly"| node_printer
node_encoder -->|"encodes"| node_instruction
node_encoder -->|"encodes opcodes"| node_opcode
node_encoder -->|"encodes values"| node_immediate
node_encoder -->|"encodes addresses"| node_label
node_instruction -->|"stores opcode"| node_opcode
node_instruction -->|"stores operands"| node_condition
node_instruction -->|"stores operands"| node_definition
node_instruction -->|"stores operands"| node_immediate
node_instruction -->|"stores operands"| node_label
node_instruction -->|"stores operands"| node_port
node_instruction -->|"stores operands"| node_register

click node_cli "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/main.rs"
click node_assembler "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/lib.rs"
click node_parser "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/mod.rs"
click node_tokens "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/tokens.rs"
click node_wrappers "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/wrappers.rs"
click node_layout "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/layout.rs"
click node_resolve "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/resolve.rs"
click node_eval "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/eval.rs"
click node_encoder "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/encode.rs"
click node_printer "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/print.rs"
click node_instruction "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/instruction.rs"
click node_opcode "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/opcode.rs"
click node_condition "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/condition.rs"
click node_definition "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/definition.rs"
click node_immediate "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/immediate.rs"
click node_label "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/label.rs"
click node_port "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/port.rs"
click node_register "https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/register.rs"

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_assembler,node_layout,node_resolve,node_eval,node_encoder,node_printer toneBlue
class node_parser,node_tokens,node_wrappers toneAmber
class node_instruction,node_opcode toneMint
class node_condition,node_definition,node_immediate,node_label,node_port,node_register toneRose
class node_developer,node_output toneIndigo
class node_cli toneTeal
```

## Components

### Assembly pipeline

- [Assembler](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/lib.rs): `src/lib.rs`
- [Program layout](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/layout.rs): `src/layout.rs`
- [Label resolution](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/resolve.rs): `src/resolve.rs`
- [Program evaluation](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/eval.rs): `src/eval.rs`
- [Instruction encoder](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/encode.rs): `src/encode.rs`
- [Assembly printer](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/print.rs): `src/print.rs`

### Assembly syntax

- [File parser](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/mod.rs): `src/parser/mod.rs`
- [Token parsers](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/tokens.rs): `src/parser/tokens.rs`
- [Instruction parsers](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/parser/wrappers.rs): `src/parser/wrappers.rs`

### BatPU-2 model

- [Instruction model](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/instruction.rs): `src/architecture/batpu2/instruction.rs`
- [Opcode set](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/opcode.rs): `src/architecture/batpu2/opcode.rs`

### Operand types

- [Conditions](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/condition.rs): `src/architecture/batpu2/operand/condition.rs`
- [Definitions](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/definition.rs): `src/architecture/batpu2/operand/definition.rs`
- [Immediate values](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/immediate.rs): `src/architecture/batpu2/operand/immediate.rs`
- [Labels](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/label.rs): `src/architecture/batpu2/operand/label.rs`
- [I/O ports](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/port.rs): `src/architecture/batpu2/operand/port.rs`
- [Registers](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/architecture/batpu2/operand/register.rs): `src/architecture/batpu2/operand/register.rs`

### Other components

- **Assembly author**
- [CLI](https://github.com/nxthingbutv0id/simpleassembler/blob/master/src/main.rs): `src/main.rs`
- **Binary file**

## Connections

- Assembly author → CLI: runs assembler (evidence: `readme.md`)
- CLI → Assembler: invokes
- Assembler → File parser: parses files (evidence: `src/lib.rs`)
- File parser → Instruction parsers: dispatches parsers (evidence: `src/parser/mod.rs`)
- Instruction parsers → Instruction model: builds instructions (evidence: `src/parser/wrappers.rs`)
- Token parsers → Opcode set: parses opcodes (evidence: `src/parser/tokens.rs`)
- Token parsers → Conditions: parses conditions (evidence: `src/parser/tokens.rs`)
- Token parsers → Definitions: parses definitions (evidence: `src/parser/tokens.rs`)
- Token parsers → Immediate values: parses values (evidence: `src/parser/tokens.rs`)
- Token parsers → Labels: parses labels (evidence: `src/parser/tokens.rs`)
- Token parsers → I/O ports: parses ports (evidence: `src/parser/tokens.rs`)
- Token parsers → Registers: parses registers (evidence: `src/parser/tokens.rs`)
- Assembler → Program layout: lays out program (evidence: `src/lib.rs`)
- Assembler → Label resolution: resolves symbols (evidence: `src/lib.rs`)
- Assembler → Program evaluation: evaluates program (evidence: `src/lib.rs`)
- Assembler → Instruction encoder: encodes instructions (evidence: `src/lib.rs`)
- Assembler → Binary file: writes binary (evidence: `src/lib.rs`)
- Assembler → Assembly printer: prints assembly (evidence: `src/lib.rs`)
- Instruction encoder → Instruction model: encodes (evidence: `src/encode.rs`)
- Instruction encoder → Opcode set: encodes opcodes (evidence: `src/encode.rs`)
- Instruction encoder → Immediate values: encodes values (evidence: `src/encode.rs`)
- Instruction encoder → Labels: encodes addresses (evidence: `src/encode.rs`)
- Instruction model → Opcode set: stores opcode (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → Conditions: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → Definitions: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → Immediate values: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → Labels: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → I/O ports: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
- Instruction model → Registers: stores operands (evidence: `src/architecture/batpu2/instruction.rs`)
