# coldchip/chip architecture

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

- Interactive diagram: https://gitdiagram.com/coldchip/chip
- Repository: https://github.com/coldchip/chip

## Overview

Chip is a compiled and interpreted programming language. In the compile workflow, a user invokes the CLI on source code; Chip tokenizes and parses it, checks semantics, generates bytecode, and optimizes the generated instructions. In the run workflow, the interpreter loads bytecode and executes it, including system calls and managed object collection. Type and variable-scope modules support semantic checking. The README documents the compiler stages; implementation excerpts show CLI dispatch and interpreter behavior, but not the full optimizer or library wiring.

Main entry points: [`src/main.c`](https://github.com/coldchip/chip/blob/main/src/main.c) (CLI Dispatch), [`src/intepreter.c`](https://github.com/coldchip/chip/blob/main/src/intepreter.c) (Bytecode Interpreter), [`src/semantic.c`](https://github.com/coldchip/chip/blob/main/src/semantic.c) (Semantic Analyzer), [`src/parse.c`](https://github.com/coldchip/chip/blob/main/src/parse.c) (Recursive Parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Source Front End"]
  node_cli["CLI Dispatch<br/>[main.c]"]
  node_lexer["Tokenizer<br/>[tokenize.c]"]
  node_parser["Recursive Parser<br/>[parse.c]"]
  node_expressions["Expression Parser<br/>[parse_expr.c]"]
end

subgraph group_analysis["Semantic Analysis"]
  node_semantics["Semantic Analyzer<br/>[semantic.c]"]
  node_types["Type System<br/>[type.c]"]
  node_scopes["Variable Scopes<br/>[varscope.c]"]
end

subgraph group_compiler["Bytecode Compiler"]
  node_codegen["Code Generator<br/>[codegen.c]"]
  node_optimizer["Bytecode Optimizer<br/>[optimize.c]"]
  node_bytecode["Bytecode File"]
end

subgraph group_runtime["Execution Runtime"]
  node_interpreter["Bytecode Interpreter<br/>[intepreter.c]"]
  node_gc["Object Collector<br/>[intepreter.c]"]
  node_syscalls["Host System Calls"]
  node_libraries["Chip Libraries"]
end

node_user(("User"))
node_source["Chip Source"]

node_user -->|"invokes"| node_cli
node_source -->|"provides source"| node_cli
node_cli -->|"tokenizes"| node_lexer
node_lexer -->|"tokens"| node_parser
node_parser -->|"parses expressions"| node_expressions
node_parser -->|"AST"| node_semantics
node_semantics -->|"checks types"| node_types
node_semantics -->|"tracks variables"| node_scopes
node_semantics -->|"checked AST"| node_codegen
node_codegen -->|"optimizes instructions"| node_optimizer
node_optimizer -->|"emits bytecode"| node_bytecode
node_user -->|"selects run"| node_cli
node_cli -->|"dispatches run"| node_interpreter
node_bytecode -->|"loaded by"| node_interpreter
node_interpreter -->|"collects objects"| node_gc
node_interpreter -->|"dispatches syscalls"| node_syscalls
node_libraries -.->|"uses runtime calls"| node_interpreter

click node_cli "https://github.com/coldchip/chip/blob/main/src/main.c"
click node_lexer "https://github.com/coldchip/chip/blob/main/src/tokenize.c"
click node_parser "https://github.com/coldchip/chip/blob/main/src/parse.c"
click node_expressions "https://github.com/coldchip/chip/blob/main/src/parse_expr.c"
click node_semantics "https://github.com/coldchip/chip/blob/main/src/semantic.c"
click node_types "https://github.com/coldchip/chip/blob/main/src/type.c"
click node_scopes "https://github.com/coldchip/chip/blob/main/src/varscope.c"
click node_codegen "https://github.com/coldchip/chip/blob/main/src/codegen.c"
click node_optimizer "https://github.com/coldchip/chip/blob/main/src/optimize.c"
click node_interpreter "https://github.com/coldchip/chip/blob/main/src/intepreter.c"
click node_gc "https://github.com/coldchip/chip/blob/main/src/intepreter.c"
click node_libraries "https://github.com/coldchip/chip/tree/main/libchip"

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_lexer,node_parser,node_expressions,node_user toneBlue
class node_semantics,node_types,node_scopes toneAmber
class node_codegen,node_optimizer,node_bytecode toneMint
class node_interpreter,node_gc,node_syscalls,node_libraries toneRose
class node_source toneIndigo
```

## Components

### Source Front End

- [CLI Dispatch](https://github.com/coldchip/chip/blob/main/src/main.c): `src/main.c`
- [Tokenizer](https://github.com/coldchip/chip/blob/main/src/tokenize.c): `src/tokenize.c`
- [Recursive Parser](https://github.com/coldchip/chip/blob/main/src/parse.c): `src/parse.c`
- [Expression Parser](https://github.com/coldchip/chip/blob/main/src/parse_expr.c): `src/parse_expr.c`

### Semantic Analysis

- [Semantic Analyzer](https://github.com/coldchip/chip/blob/main/src/semantic.c): `src/semantic.c`
- [Type System](https://github.com/coldchip/chip/blob/main/src/type.c): `src/type.c`
- [Variable Scopes](https://github.com/coldchip/chip/blob/main/src/varscope.c): `src/varscope.c`

### Bytecode Compiler

- [Code Generator](https://github.com/coldchip/chip/blob/main/src/codegen.c): `src/codegen.c`
- [Bytecode Optimizer](https://github.com/coldchip/chip/blob/main/src/optimize.c): `src/optimize.c`
- **Bytecode File**

### Execution Runtime

- [Bytecode Interpreter](https://github.com/coldchip/chip/blob/main/src/intepreter.c): `src/intepreter.c`
- [Object Collector](https://github.com/coldchip/chip/blob/main/src/intepreter.c): `src/intepreter.c`
- **Host System Calls**
- [Chip Libraries](https://github.com/coldchip/chip/tree/main/libchip): `libchip`

### Other components

- **User**
- **Chip Source**

## Connections

- User → CLI Dispatch: invokes (evidence: `src/main.c`)
- Chip Source → CLI Dispatch: provides source (evidence: `src/main.c`)
- CLI Dispatch → Tokenizer: tokenizes (evidence: `src/main.c`)
- Tokenizer → Recursive Parser: tokens (evidence: `README.md`)
- Recursive Parser → Expression Parser: parses expressions
- Recursive Parser → Semantic Analyzer: AST
- Semantic Analyzer → Type System: checks types (evidence: `src/semantic.c`)
- Semantic Analyzer → Variable Scopes: tracks variables (evidence: `src/semantic.c`)
- Semantic Analyzer → Code Generator: checked AST
- Code Generator → Bytecode Optimizer: optimizes instructions (evidence: `src/codegen.c`)
- Bytecode Optimizer → Bytecode File: emits bytecode (evidence: `README.md`)
- User → CLI Dispatch: selects run (evidence: `src/main.c`)
- CLI Dispatch → Bytecode Interpreter: dispatches run (evidence: `src/main.c`)
- Bytecode File → Bytecode Interpreter: loaded by (evidence: `src/intepreter.c`)
- Bytecode Interpreter → Object Collector: collects objects (evidence: `src/intepreter.c`)
- Bytecode Interpreter → Host System Calls: dispatches syscalls (evidence: `src/intepreter.c`)
- Chip Libraries → Bytecode Interpreter: uses runtime calls
