# byusistudio/code-cin architecture

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

- Interactive diagram: https://gitdiagram.com/byusistudio/code-cin
- Repository: https://github.com/byusistudio/code-cin

## Overview

Code CIN is a CIN/PL/ASM language toolchain and cross-platform virtual machine. A user submits source or an existing binary/image through the Python CLI; it compiles or assembles the input, then runs it through the Go native VM by default, with Python interpretation and JIT paths also available. The graph includes the documented CROM/AOT, debugging and profiling branches, plus host graphics and audio capabilities. README documents the major workflows; sampled source confirms selected compiler, VM and debugger behavior, but not every integration link.

Main entry points: [`codecin/cpu.py`](https://github.com/byusistudio/code-cin/blob/master/codecin/cpu.py) (Python CPU), [`codecin/cli.py`](https://github.com/byusistudio/code-cin/blob/master/codecin/cli.py) (Python CLI), [`codecin/isa.py`](https://github.com/byusistudio/code-cin/blob/master/codecin/isa.py) (Instruction set), [`codecin/native/engine/system.go`](https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/system.go) (Host system calls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Front ends"]
  node_cli["Python CLI<br/>[cli.py]"]
  node_cin["CIN compiler<br/>[cin.py]"]
  node_go_compiler["Go CIN compiler<br/>[codegen.go]"]
  node_assembler["PL/ASM assembler<br/>[assembler.py]"]
  node_disasm["Disassembler<br/>[disasm.py]"]
  node_isa["Instruction set<br/>[isa.py]"]
end

subgraph group_runtime["Execution runtime"]
  node_crom["CROM format<br/>[crom.py]"]
  node_aot["AOT compiler<br/>[aot.py]"]
  node_cpu["Python CPU<br/>[cpu.py]"]
  node_jit["JIT engine<br/>[jit.py]"]
  node_native_api["Native bridge<br/>[native.py]"]
  node_go_vm["Go VM<br/>[vm.go]"]
  node_memory["Memory system<br/>[memory.py]"]
  node_cache[("LRU cache<br/>[cache.py]")]
end

subgraph group_observability["Debug and analysis"]
  node_debugger["Interactive debugger<br/>[debugger.py]"]
  node_stats["Execution statistics<br/>[stats.py]"]
end

subgraph group_host["Host capabilities"]
  node_audio["Audio playback<br/>[audio.go]"]
  node_canvas["2D canvas<br/>[canvas.go]"]
  node_host_syscalls["Host system calls<br/>[system.go]"]
end

node_user(("Program user"))
node_output(("Program output"))

node_user -->|"runs input"| node_cli
node_cli -->|"compiles CIN"| node_cin
node_cli -.->|"selects native compile"| node_go_compiler
node_cli -->|"assembles PL/ASM"| node_assembler
node_cin -->|"emits instructions"| node_isa
node_go_compiler -->|"emits instructions"| node_isa
node_assembler -->|"encodes instructions"| node_isa
node_cli -->|"loads or saves"| node_crom
node_crom -->|"provides program image"| node_cli
node_cli -.->|"requests static build"| node_aot
node_cli -->|"runs interpreter"| node_cpu
node_cpu -.->|"invokes native VM"| node_native_api
node_native_api -->|"passes bytecode and memory"| node_go_vm
node_cpu -.->|"dispatches hot blocks"| node_jit
node_cpu -->|"reads and writes"| node_memory
node_cpu -->|"records memory accesses"| node_cache
node_cpu -->|"records execution"| node_stats
node_cpu -->|"supports debug session"| node_debugger
node_debugger -->|"steps and inspects"| node_cpu
node_go_vm -->|"dispatches SYS calls"| node_host_syscalls
node_host_syscalls -.->|"plays audio"| node_audio
node_host_syscalls -.->|"draws and exports"| node_canvas
node_cpu -->|"produces output"| node_output
node_cli -.->|"disassembles program"| node_disasm
node_disasm -->|"decodes instructions"| node_isa

click node_cli "https://github.com/byusistudio/code-cin/blob/master/codecin/cli.py"
click node_cin "https://github.com/byusistudio/code-cin/blob/master/codecin/cin.py"
click node_go_compiler "https://github.com/byusistudio/code-cin/blob/master/codecin/native/compiler/codegen.go"
click node_assembler "https://github.com/byusistudio/code-cin/blob/master/codecin/assembler.py"
click node_disasm "https://github.com/byusistudio/code-cin/blob/master/codecin/disasm.py"
click node_isa "https://github.com/byusistudio/code-cin/blob/master/codecin/isa.py"
click node_crom "https://github.com/byusistudio/code-cin/blob/master/codecin/crom.py"
click node_aot "https://github.com/byusistudio/code-cin/blob/master/codecin/aot.py"
click node_cpu "https://github.com/byusistudio/code-cin/blob/master/codecin/cpu.py"
click node_jit "https://github.com/byusistudio/code-cin/blob/master/codecin/jit.py"
click node_native_api "https://github.com/byusistudio/code-cin/blob/master/codecin/native.py"
click node_go_vm "https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/vm.go"
click node_memory "https://github.com/byusistudio/code-cin/blob/master/codecin/memory.py"
click node_cache "https://github.com/byusistudio/code-cin/blob/master/codecin/cache.py"
click node_debugger "https://github.com/byusistudio/code-cin/blob/master/codecin/debugger.py"
click node_stats "https://github.com/byusistudio/code-cin/blob/master/codecin/stats.py"
click node_audio "https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/audio.go"
click node_canvas "https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/canvas.go"
click node_host_syscalls "https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/system.go"

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_cin,node_go_compiler,node_assembler,node_disasm,node_isa,node_user toneBlue
class node_crom,node_aot,node_cpu,node_jit,node_native_api,node_go_vm,node_memory,node_cache toneAmber
class node_debugger,node_stats toneMint
class node_audio,node_canvas,node_host_syscalls toneRose
class node_output toneIndigo
```

## Components

### Front ends

- [Python CLI](https://github.com/byusistudio/code-cin/blob/master/codecin/cli.py): `codecin/cli.py`
- [CIN compiler](https://github.com/byusistudio/code-cin/blob/master/codecin/cin.py): `codecin/cin.py`
- [Go CIN compiler](https://github.com/byusistudio/code-cin/blob/master/codecin/native/compiler/codegen.go): `codecin/native/compiler/codegen.go`
- [PL/ASM assembler](https://github.com/byusistudio/code-cin/blob/master/codecin/assembler.py): `codecin/assembler.py`
- [Disassembler](https://github.com/byusistudio/code-cin/blob/master/codecin/disasm.py): `codecin/disasm.py`
- [Instruction set](https://github.com/byusistudio/code-cin/blob/master/codecin/isa.py): `codecin/isa.py`

### Execution runtime

- [CROM format](https://github.com/byusistudio/code-cin/blob/master/codecin/crom.py): `codecin/crom.py`
- [AOT compiler](https://github.com/byusistudio/code-cin/blob/master/codecin/aot.py): `codecin/aot.py`
- [Python CPU](https://github.com/byusistudio/code-cin/blob/master/codecin/cpu.py): `codecin/cpu.py`
- [JIT engine](https://github.com/byusistudio/code-cin/blob/master/codecin/jit.py): `codecin/jit.py`
- [Native bridge](https://github.com/byusistudio/code-cin/blob/master/codecin/native.py): `codecin/native.py`
- [Go VM](https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/vm.go): `codecin/native/engine/vm.go`
- [Memory system](https://github.com/byusistudio/code-cin/blob/master/codecin/memory.py): `codecin/memory.py`
- [LRU cache](https://github.com/byusistudio/code-cin/blob/master/codecin/cache.py): `codecin/cache.py`

### Debug and analysis

- [Interactive debugger](https://github.com/byusistudio/code-cin/blob/master/codecin/debugger.py): `codecin/debugger.py`
- [Execution statistics](https://github.com/byusistudio/code-cin/blob/master/codecin/stats.py): `codecin/stats.py`

### Host capabilities

- [Audio playback](https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/audio.go): `codecin/native/engine/audio.go`
- [2D canvas](https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/canvas.go): `codecin/native/engine/canvas.go`
- [Host system calls](https://github.com/byusistudio/code-cin/blob/master/codecin/native/engine/system.go): `codecin/native/engine/system.go`

### Other components

- **Program user**
- **Program output**

## Connections

- Program user → Python CLI: runs input
- Python CLI → CIN compiler: compiles CIN
- Python CLI → Go CIN compiler: selects native compile
- Python CLI → PL/ASM assembler: assembles PL/ASM
- CIN compiler → Instruction set: emits instructions
- Go CIN compiler → Instruction set: emits instructions
- PL/ASM assembler → Instruction set: encodes instructions
- Python CLI → CROM format: loads or saves
- CROM format → Python CLI: provides program image
- Python CLI → AOT compiler: requests static build
- Python CLI → Python CPU: runs interpreter
- Python CPU → Native bridge: invokes native VM
- Native bridge → Go VM: passes bytecode and memory
- Python CPU → JIT engine: dispatches hot blocks
- Python CPU → Memory system: reads and writes
- Python CPU → LRU cache: records memory accesses
- Python CPU → Execution statistics: records execution
- Python CPU → Interactive debugger: supports debug session
- Interactive debugger → Python CPU: steps and inspects
- Go VM → Host system calls: dispatches SYS calls
- Host system calls → Audio playback: plays audio
- Host system calls → 2D canvas: draws and exports
- Python CPU → Program output: produces output
- Python CLI → Disassembler: disassembles program
- Disassembler → Instruction set: decodes instructions