# aswinsilver/aphelion architecture

> Architecture diagram of the GitHub repository aswinsilver/aphelion, 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/aswinsilver/aphelion
- Repository: https://github.com/aswinsilver/aphelion

## Overview

Aphelion is a C11 language implementation whose main workflow takes `.agne` source through lexing, parsing, semantic checking, bytecode compilation, and execution in a stack VM; the CLI also exposes inspection, checking, and bytecode-file operations. Source modules and compiled-in ACSL cryptography extend programs through `summon`, while the REPL compiles and runs individual input lines. README statements establish the compiler pipeline and product capabilities; sampled source and the SOURCE INDEX support several implementation links, but not every runtime call is visible in the excerpts.

Main entry points: [`src/main.c`](https://github.com/aswinsilver/aphelion/blob/main/src/main.c) (CLI commands), [`src/acsl.c`](https://github.com/aswinsilver/aphelion/blob/main/src/acsl.c) (Native registry), [`src/parser.c`](https://github.com/aswinsilver/aphelion/blob/main/src/parser.c) (AST parser), [`src/compiler.c`](https://github.com/aswinsilver/aphelion/blob/main/src/compiler.c) (Bytecode compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language front end"]
  node_lexer["Lexer<br/>[lexer.c]"]
  node_parser["AST parser<br/>[parser.c]"]
  node_ast["AST model<br/>[ast.c]"]
  node_semantic["Type checker<br/>[semantic.c]"]
  node_compiler["Bytecode compiler<br/>[compiler.c]"]
end

subgraph group_runtime["Bytecode runtime"]
  node_bytecode["Bytecode format<br/>[bytecode.c]"]
  node_vm["Stack VM<br/>[vm.c]"]
  node_values["Runtime values<br/>[value.c]"]
end

subgraph group_integration["Modules and native APIs"]
  node_module["Source module loader<br/>[module.c]"]
  node_native["Native registry<br/>[acsl.c]"]
  node_acsl_hash["Hash and HMAC<br/>[acsl_hash.c]"]
  node_acsl_cipher["Authenticated cipher<br/>[acsl_cipher.c]"]
  node_acsl_key["Key derivation<br/>[acsl_key.c]"]
  node_acsl_random["Secure randomness<br/>[acsl_random.c]"]
end

subgraph group_interfaces["User interfaces"]
  node_cli["CLI commands<br/>[main.c]"]
  node_repl["One-line REPL<br/>[main.c]"]
end

node_user(("Programmer"))
node_source_files["&#96;.agne&#96; source"]
node_apb_file["&#96;.apb&#96; bytecode"]
node_crypto_deps["OpenSSL / Argon2"]

node_user -->|"runs command"| node_cli
node_user -->|"enters lines"| node_repl
node_source_files -->|"provides source"| node_cli
node_cli -->|"token inspection"| node_lexer
node_cli -->|"AST inspection"| node_parser
node_lexer -->|"supplies tokens"| node_parser
node_parser -->|"builds tree"| node_ast
node_parser -->|"passes AST"| node_semantic
node_semantic -->|"checks before compile"| node_compiler
node_compiler -->|"emits instructions"| node_bytecode
node_bytecode -->|"executes instructions"| node_vm
node_vm -->|"operates on values"| node_values
node_cli -->|"compiles source"| node_compiler
node_cli -->|"writes or reads"| node_bytecode
node_cli -->|"runs program"| node_vm
node_repl -->|"compiles each line"| node_compiler
node_repl -->|"runs compiled line"| node_vm
node_cli -->|"loads summoned modules"| node_module
node_module -->|"parses source modules"| node_parser
node_module -->|"recognizes native module"| node_native
node_vm -->|"dispatches native calls"| node_native
node_native -->|"invokes crypto"| node_acsl_hash
node_native -->|"invokes crypto"| node_acsl_cipher
node_native -->|"invokes crypto"| node_acsl_key
node_native -->|"invokes crypto"| node_acsl_random
node_crypto_deps -->|"provides crypto"| node_acsl_cipher
node_crypto_deps -->|"provides derivation"| node_acsl_key
node_crypto_deps -->|"provides randomness"| node_acsl_random
node_compiler -->|"serializes for output"| node_bytecode
node_bytecode -->|"reads or writes"| node_apb_file

click node_cli "https://github.com/aswinsilver/aphelion/blob/main/src/main.c"
click node_repl "https://github.com/aswinsilver/aphelion/blob/main/src/main.c"
click node_lexer "https://github.com/aswinsilver/aphelion/blob/main/src/lexer.c"
click node_parser "https://github.com/aswinsilver/aphelion/blob/main/src/parser.c"
click node_ast "https://github.com/aswinsilver/aphelion/blob/main/src/ast.c"
click node_semantic "https://github.com/aswinsilver/aphelion/blob/main/src/semantic.c"
click node_compiler "https://github.com/aswinsilver/aphelion/blob/main/src/compiler.c"
click node_module "https://github.com/aswinsilver/aphelion/blob/main/src/module.c"
click node_bytecode "https://github.com/aswinsilver/aphelion/blob/main/src/bytecode.c"
click node_vm "https://github.com/aswinsilver/aphelion/blob/main/src/vm.c"
click node_values "https://github.com/aswinsilver/aphelion/blob/main/src/value.c"
click node_native "https://github.com/aswinsilver/aphelion/blob/main/src/acsl.c"
click node_acsl_hash "https://github.com/aswinsilver/aphelion/blob/main/src/acsl_hash.c"
click node_acsl_cipher "https://github.com/aswinsilver/aphelion/blob/main/src/acsl_cipher.c"
click node_acsl_key "https://github.com/aswinsilver/aphelion/blob/main/src/acsl_key.c"
click node_acsl_random "https://github.com/aswinsilver/aphelion/blob/main/src/acsl_random.c"

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_lexer,node_parser,node_ast,node_semantic,node_compiler toneBlue
class node_bytecode,node_vm,node_values toneAmber
class node_module,node_native,node_acsl_hash,node_acsl_cipher,node_acsl_key,node_acsl_random toneMint
class node_cli,node_repl toneRose
class node_user,node_source_files,node_apb_file,node_crypto_deps toneIndigo
```

## Components

### Language front end

- [Lexer](https://github.com/aswinsilver/aphelion/blob/main/src/lexer.c): `src/lexer.c`
- [AST parser](https://github.com/aswinsilver/aphelion/blob/main/src/parser.c): `src/parser.c`
- [AST model](https://github.com/aswinsilver/aphelion/blob/main/src/ast.c): `src/ast.c`
- [Type checker](https://github.com/aswinsilver/aphelion/blob/main/src/semantic.c): `src/semantic.c`
- [Bytecode compiler](https://github.com/aswinsilver/aphelion/blob/main/src/compiler.c): `src/compiler.c`

### Bytecode runtime

- [Bytecode format](https://github.com/aswinsilver/aphelion/blob/main/src/bytecode.c): `src/bytecode.c`
- [Stack VM](https://github.com/aswinsilver/aphelion/blob/main/src/vm.c): `src/vm.c`
- [Runtime values](https://github.com/aswinsilver/aphelion/blob/main/src/value.c): `src/value.c`

### Modules and native APIs

- [Source module loader](https://github.com/aswinsilver/aphelion/blob/main/src/module.c): `src/module.c`
- [Native registry](https://github.com/aswinsilver/aphelion/blob/main/src/acsl.c): `src/acsl.c`
- [Hash and HMAC](https://github.com/aswinsilver/aphelion/blob/main/src/acsl_hash.c): `src/acsl_hash.c`
- [Authenticated cipher](https://github.com/aswinsilver/aphelion/blob/main/src/acsl_cipher.c): `src/acsl_cipher.c`
- [Key derivation](https://github.com/aswinsilver/aphelion/blob/main/src/acsl_key.c): `src/acsl_key.c`
- [Secure randomness](https://github.com/aswinsilver/aphelion/blob/main/src/acsl_random.c): `src/acsl_random.c`

### User interfaces

- [CLI commands](https://github.com/aswinsilver/aphelion/blob/main/src/main.c): `src/main.c`
- [One-line REPL](https://github.com/aswinsilver/aphelion/blob/main/src/main.c): `src/main.c`

### Other components

- **Programmer**
- **`.agne` source**
- **`.apb` bytecode**
- **OpenSSL / Argon2**

## Connections

- Programmer → CLI commands: runs command (evidence: `README.md`)
- Programmer → One-line REPL: enters lines (evidence: `README.md`)
- `.agne` source → CLI commands: provides source (evidence: `README.md`)
- CLI commands → Lexer: token inspection (evidence: `src/main.c`)
- CLI commands → AST parser: AST inspection (evidence: `src/main.c`)
- Lexer → AST parser: supplies tokens (evidence: `src/parser.c`)
- AST parser → AST model: builds tree (evidence: `src/parser.c`)
- AST parser → Type checker: passes AST (evidence: `README.md`)
- Type checker → Bytecode compiler: checks before compile (evidence: `README.md`)
- Bytecode compiler → Bytecode format: emits instructions (evidence: `README.md`)
- Bytecode format → Stack VM: executes instructions (evidence: `README.md`)
- Stack VM → Runtime values: operates on values
- CLI commands → Bytecode compiler: compiles source (evidence: `src/main.c`)
- CLI commands → Bytecode format: writes or reads (evidence: `README.md`)
- CLI commands → Stack VM: runs program (evidence: `README.md`)
- One-line REPL → Bytecode compiler: compiles each line (evidence: `README.md`)
- One-line REPL → Stack VM: runs compiled line (evidence: `README.md`)
- CLI commands → Source module loader: loads summoned modules (evidence: `src/main.c`)
- Source module loader → AST parser: parses source modules (evidence: `src/module.c`)
- Source module loader → Native registry: recognizes native module
- Stack VM → Native registry: dispatches native calls
- Native registry → Hash and HMAC: invokes crypto (evidence: `src/acsl.c`)
- Native registry → Authenticated cipher: invokes crypto (evidence: `src/acsl.c`)
- Native registry → Key derivation: invokes crypto (evidence: `src/acsl.c`)
- Native registry → Secure randomness: invokes crypto (evidence: `src/acsl.c`)
- OpenSSL / Argon2 → Authenticated cipher: provides crypto (evidence: `README.md`)
- OpenSSL / Argon2 → Key derivation: provides derivation (evidence: `README.md`)
- OpenSSL / Argon2 → Secure randomness: provides randomness (evidence: `README.md`)
- Bytecode compiler → Bytecode format: serializes for output (evidence: `README.md`)
- Bytecode format → `.apb` bytecode: reads or writes (evidence: `README.md`)
