# pervognsen/bitwise architecture

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

- Interactive diagram: https://gitdiagram.com/pervognsen/bitwise
- Repository: https://github.com/pervognsen/bitwise

## Overview

This repository is an educational systems-programming project whose implemented software centers on the Ion C-like language compiler and Rattle, a Python hardware-description toolkit. The Ion workflow starts at its command-line entry point and compiles source through lexical, syntactic, semantic, and code-generation responsibilities; system packages and RISC-V language sources provide notable language and target capabilities. Rattle provides bit-level circuit construction, with tutorial examples. The sampled evidence establishes Ion’s amalgamated module composition and Rattle’s tutorial/helper references, but not all internal stage calls, so those links are omitted.

Main entry points: [`ion/main.c`](https://github.com/pervognsen/bitwise/blob/master/ion/main.c) (Ion entry point), [`rattle/rattle.py`](https://github.com/pervognsen/bitwise/blob/master/rattle/rattle.py) (Circuit construction), [`rattle/rattle_extras.py`](https://github.com/pervognsen/bitwise/blob/master/rattle/rattle_extras.py) (Circuit utilities), [`rattle/tutorial.py`](https://github.com/pervognsen/bitwise/blob/master/rattle/tutorial.py) (Circuit examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ion_front["Ion Frontend"]
  node_ion_cli["Ion entry point<br/>[main.c]"]
  node_ion_os["CLI and OS<br/>[os.c]"]
  node_ion_lex["Lexer<br/>[lex.c]"]
  node_ion_parse["Parser<br/>[parse.c]"]
  node_ion_ast["AST construction<br/>[ast.c]"]
end

subgraph group_ion_core["Ion Compiler Core"]
  node_ion_types["Type system<br/>[type.c]"]
  node_ion_resolve["Semantic resolver<br/>[resolve.c]"]
  node_ion_gen["C code generator<br/>[gen.c]"]
  node_ion_runtime["Compiler runtime<br/>[ion.c]"]
  node_ion_targets["Target configuration<br/>[targets.c]"]
  node_ion_common["Shared utilities<br/>[common.c]"]
end

subgraph group_ion_lang["Ion Language Assets"]
  node_ion_packages["System packages"]
  node_ion_riscv["RISC-V sources"]
  node_noir["Noir language source<br/>[noir.ion]"]
end

subgraph group_rattle["Rattle HDL"]
  node_rattle_core["Circuit construction<br/>[rattle.py]"]
  node_rattle_extras["Circuit utilities<br/>[rattle_extras.py]"]
  node_rattle_tutorial["Circuit examples<br/>[tutorial.py]"]
end

node_user(("Compiler user"))

node_user -->|"invokes"| node_ion_cli
node_ion_cli -->|"calls"| node_ion_runtime
node_ion_cli -->|"includes"| node_ion_os
node_ion_cli -->|"includes"| node_ion_lex
node_ion_cli -->|"includes"| node_ion_parse
node_ion_cli -->|"includes"| node_ion_ast
node_ion_cli -->|"includes"| node_ion_types
node_ion_cli -->|"includes"| node_ion_resolve
node_ion_cli -->|"includes"| node_ion_gen
node_ion_cli -->|"includes"| node_ion_targets
node_ion_cli -->|"includes"| node_ion_common
node_rattle_tutorial -->|"imports"| node_rattle_core
node_rattle_extras -->|"imports"| node_rattle_core

click node_ion_cli "https://github.com/pervognsen/bitwise/blob/master/ion/main.c"
click node_ion_os "https://github.com/pervognsen/bitwise/blob/master/ion/os.c"
click node_ion_lex "https://github.com/pervognsen/bitwise/blob/master/ion/lex.c"
click node_ion_parse "https://github.com/pervognsen/bitwise/blob/master/ion/parse.c"
click node_ion_ast "https://github.com/pervognsen/bitwise/blob/master/ion/ast.c"
click node_ion_types "https://github.com/pervognsen/bitwise/blob/master/ion/type.c"
click node_ion_resolve "https://github.com/pervognsen/bitwise/blob/master/ion/resolve.c"
click node_ion_gen "https://github.com/pervognsen/bitwise/blob/master/ion/gen.c"
click node_ion_runtime "https://github.com/pervognsen/bitwise/blob/master/ion/ion.c"
click node_ion_targets "https://github.com/pervognsen/bitwise/blob/master/ion/targets.c"
click node_ion_common "https://github.com/pervognsen/bitwise/blob/master/ion/common.c"
click node_ion_packages "https://github.com/pervognsen/bitwise/tree/master/ion/system_packages"
click node_ion_riscv "https://github.com/pervognsen/bitwise/tree/master/ion/riscv"
click node_noir "https://github.com/pervognsen/bitwise/blob/master/noir/noir/noir.ion"
click node_rattle_core "https://github.com/pervognsen/bitwise/blob/master/rattle/rattle.py"
click node_rattle_extras "https://github.com/pervognsen/bitwise/blob/master/rattle/rattle_extras.py"
click node_rattle_tutorial "https://github.com/pervognsen/bitwise/blob/master/rattle/tutorial.py"

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_ion_cli,node_ion_os,node_ion_lex,node_ion_parse,node_ion_ast,node_user toneBlue
class node_ion_types,node_ion_resolve,node_ion_gen,node_ion_runtime,node_ion_targets,node_ion_common toneAmber
class node_ion_packages,node_ion_riscv,node_noir toneMint
class node_rattle_core,node_rattle_extras,node_rattle_tutorial toneRose
```

## Components

### Ion Frontend

- [Ion entry point](https://github.com/pervognsen/bitwise/blob/master/ion/main.c): `ion/main.c`
- [CLI and OS](https://github.com/pervognsen/bitwise/blob/master/ion/os.c): `ion/os.c`
- [Lexer](https://github.com/pervognsen/bitwise/blob/master/ion/lex.c): `ion/lex.c`
- [Parser](https://github.com/pervognsen/bitwise/blob/master/ion/parse.c): `ion/parse.c`
- [AST construction](https://github.com/pervognsen/bitwise/blob/master/ion/ast.c): `ion/ast.c`

### Ion Compiler Core

- [Type system](https://github.com/pervognsen/bitwise/blob/master/ion/type.c): `ion/type.c`
- [Semantic resolver](https://github.com/pervognsen/bitwise/blob/master/ion/resolve.c): `ion/resolve.c`
- [C code generator](https://github.com/pervognsen/bitwise/blob/master/ion/gen.c): `ion/gen.c`
- [Compiler runtime](https://github.com/pervognsen/bitwise/blob/master/ion/ion.c): `ion/ion.c`
- [Target configuration](https://github.com/pervognsen/bitwise/blob/master/ion/targets.c): `ion/targets.c`
- [Shared utilities](https://github.com/pervognsen/bitwise/blob/master/ion/common.c): `ion/common.c`

### Ion Language Assets

- [System packages](https://github.com/pervognsen/bitwise/tree/master/ion/system_packages): `ion/system_packages`
- [RISC-V sources](https://github.com/pervognsen/bitwise/tree/master/ion/riscv): `ion/riscv`
- [Noir language source](https://github.com/pervognsen/bitwise/blob/master/noir/noir/noir.ion): `noir/noir/noir.ion`

### Rattle HDL

- [Circuit construction](https://github.com/pervognsen/bitwise/blob/master/rattle/rattle.py): `rattle/rattle.py`
- [Circuit utilities](https://github.com/pervognsen/bitwise/blob/master/rattle/rattle_extras.py): `rattle/rattle_extras.py`
- [Circuit examples](https://github.com/pervognsen/bitwise/blob/master/rattle/tutorial.py): `rattle/tutorial.py`

### Other components

- **Compiler user**

## Connections

- Compiler user → Ion entry point: invokes (evidence: `README.md`)
- Ion entry point → Compiler runtime: calls (evidence: `ion/main.c`)
- Ion entry point → CLI and OS: includes (evidence: `ion/main.c`)
- Ion entry point → Lexer: includes (evidence: `ion/main.c`)
- Ion entry point → Parser: includes (evidence: `ion/main.c`)
- Ion entry point → AST construction: includes (evidence: `ion/main.c`)
- Ion entry point → Type system: includes (evidence: `ion/main.c`)
- Ion entry point → Semantic resolver: includes (evidence: `ion/main.c`)
- Ion entry point → C code generator: includes (evidence: `ion/main.c`)
- Ion entry point → Target configuration: includes (evidence: `ion/main.c`)
- Ion entry point → Shared utilities: includes (evidence: `ion/main.c`)
- Circuit examples → Circuit construction: imports (evidence: `rattle/tutorial.py`)
- Circuit utilities → Circuit construction: imports (evidence: `rattle/rattle_extras.py`)