# peixe2b/unilogic architecture

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

- Interactive diagram: https://gitdiagram.com/peixe2b/unilogic
- Repository: https://github.com/peixe2b/unilogic

## Overview

UniLogic is a source language compiler with multiple output targets and configurable runtime behavior. The main workflow is source text through lexing, parsing, AST normalization and semantic checking, then target-specific encoding or code generation; the CLI coordinates compilation and execution. The README also documents project-management commands and profiling, but the supplied tree and excerpts do not establish their internal implementation, so they are represented only at the driver level. Edges are limited to relationships shown by excerpts, the source index, or README statements.

Main entry points: [`Main.py`](https://github.com/peixe2b/unilogic/blob/main/Main.py) (CLI driver), [`Transcoder/Decoder/ul2c.py`](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2c.py) (C generator), [`Compiler/SynTree Def/ast_nodes.py`](https://github.com/peixe2b/unilogic/blob/main/Compiler/SynTree%20Def/ast_nodes.py) (AST model), [`Compiler/Runtime/ul_gc.c`](https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_gc.c) (Garbage collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_front["Language Front End"]
  node_lexer["Lexer<br/>[src2token.py]"]
  node_parser["Parser<br/>[token2ast.py]"]
  node_ast["AST model<br/>[ast_nodes.py]"]
  node_normalize["AST normalizer<br/>[simplifycode.py]"]
  node_semantic["Semantic checker<br/>[semcheck.py]"]
end

subgraph group_trans["Transcoding Targets"]
  node_cgen["C generator<br/>[ul2c.py]"]
  node_pygen["Python generator<br/>[ul2py.py]"]
  node_jsgen["JavaScript generator<br/>[ul2js.py]"]
  node_llvmgen["LLVM generator<br/>[ul2llvm.py]"]
  node_wasm["WebAssembly target<br/>[Main.py]"]
  node_pyencode["Python encoder<br/>[py2ul.py]"]
  node_cencode["C encoder<br/>[c2ul.py]"]
  node_ubiencode["Bytecode encoder<br/>[ul2ubi.py]"]
end

subgraph group_runtime["Runtime Memory"]
  node_gc["Garbage collector<br/>[ul_gc.c]"]
  node_manual["Manual memory<br/>[ul_manual.c]"]
  node_refcount["Reference counting<br/>[ul_refcount.c]"]
  node_arena["Arena allocator<br/>[ul_arena.c]"]
end

subgraph group_product["Product Entry"]
  node_driver["CLI driver<br/>[Main.py]"]
  node_project["Project commands<br/>[Main.py]"]
  node_profile["Profiler capability<br/>[Main.py]"]
end

node_user(("UL developer"))

node_user -->|"invokes"| node_driver
node_driver -->|"tokenizes"| node_lexer
node_driver -->|"parses"| node_parser
node_parser -->|"builds"| node_ast
node_driver -->|"normalizes"| node_normalize
node_driver -->|"checks"| node_semantic
node_semantic -->|"walks"| node_ast
node_normalize -->|"rewrites"| node_ast
node_driver -->|"generates C"| node_cgen
node_driver -->|"generates Python"| node_pygen
node_driver -->|"generates JavaScript"| node_jsgen
node_driver -->|"generates LLVM"| node_llvmgen
node_driver -->|"targets WASM"| node_wasm
node_driver -->|"transpiles Python"| node_pyencode
node_driver -.->|"transpiles C"| node_cencode
node_driver -->|"emits bytecode"| node_ubiencode
node_cgen -->|"walks"| node_ast
node_cgen -->|"uses type map"| node_semantic
node_pygen -->|"walks"| node_ast
node_jsgen -->|"walks"| node_ast
node_llvmgen -->|"walks"| node_ast
node_ubiencode -->|"uses nodes"| node_ast
node_driver -->|"offers commands"| node_project
node_driver -->|"offers profiling"| node_profile
node_cgen -.->|"selects by DR"| node_gc
node_cgen -.->|"selects by DR"| node_manual
node_cgen -.->|"selects by DR"| node_refcount
node_cgen -.->|"selects by DR"| node_arena
node_gc -.-> node_manual
node_gc -.-> node_refcount
node_gc -.-> node_arena

click node_driver "https://github.com/peixe2b/unilogic/blob/main/Main.py"
click node_lexer "https://github.com/peixe2b/unilogic/blob/main/Compiler/Lexer/src2token.py"
click node_parser "https://github.com/peixe2b/unilogic/blob/main/Compiler/AST%20Gen/token2ast.py"
click node_ast "https://github.com/peixe2b/unilogic/blob/main/Compiler/SynTree%20Def/ast_nodes.py"
click node_normalize "https://github.com/peixe2b/unilogic/blob/main/Compiler/simplifycode.py"
click node_semantic "https://github.com/peixe2b/unilogic/blob/main/Compiler/Semantic/semcheck.py"
click node_project "https://github.com/peixe2b/unilogic/blob/main/Main.py"
click node_cgen "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2c.py"
click node_pygen "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2py.py"
click node_jsgen "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2js.py"
click node_llvmgen "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2llvm.py"
click node_wasm "https://github.com/peixe2b/unilogic/blob/main/Main.py"
click node_pyencode "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/py2ul.py"
click node_cencode "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/c2ul.py"
click node_ubiencode "https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/ul2ubi.py"
click node_gc "https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_gc.c"
click node_manual "https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_manual.c"
click node_refcount "https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_refcount.c"
click node_arena "https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_arena.c"
click node_profile "https://github.com/peixe2b/unilogic/blob/main/Main.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_lexer,node_parser,node_ast,node_normalize,node_semantic toneBlue
class node_cgen,node_pygen,node_jsgen,node_llvmgen,node_wasm,node_pyencode,node_cencode,node_ubiencode toneAmber
class node_gc,node_manual,node_refcount,node_arena toneMint
class node_driver,node_project,node_profile toneRose
class node_user toneIndigo
```

## Components

### Language Front End

- [Lexer](https://github.com/peixe2b/unilogic/blob/main/Compiler/Lexer/src2token.py): `Compiler/Lexer/src2token.py`
- [Parser](https://github.com/peixe2b/unilogic/blob/main/Compiler/AST%20Gen/token2ast.py): `Compiler/AST Gen/token2ast.py`
- [AST model](https://github.com/peixe2b/unilogic/blob/main/Compiler/SynTree%20Def/ast_nodes.py): `Compiler/SynTree Def/ast_nodes.py`
- [AST normalizer](https://github.com/peixe2b/unilogic/blob/main/Compiler/simplifycode.py): `Compiler/simplifycode.py`
- [Semantic checker](https://github.com/peixe2b/unilogic/blob/main/Compiler/Semantic/semcheck.py): `Compiler/Semantic/semcheck.py`

### Transcoding Targets

- [C generator](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2c.py): `Transcoder/Decoder/ul2c.py`
- [Python generator](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2py.py): `Transcoder/Decoder/ul2py.py`
- [JavaScript generator](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2js.py): `Transcoder/Decoder/ul2js.py`
- [LLVM generator](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Decoder/ul2llvm.py): `Transcoder/Decoder/ul2llvm.py`
- [WebAssembly target](https://github.com/peixe2b/unilogic/blob/main/Main.py): `Main.py`
- [Python encoder](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/py2ul.py): `Transcoder/Encoder/py2ul.py`
- [C encoder](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/c2ul.py): `Transcoder/Encoder/c2ul.py`
- [Bytecode encoder](https://github.com/peixe2b/unilogic/blob/main/Transcoder/Encoder/ul2ubi.py): `Transcoder/Encoder/ul2ubi.py`

### Runtime Memory

- [Garbage collector](https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_gc.c): `Compiler/Runtime/ul_gc.c`
- [Manual memory](https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_manual.c): `Compiler/Runtime/ul_manual.c`
- [Reference counting](https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_refcount.c): `Compiler/Runtime/ul_refcount.c`
- [Arena allocator](https://github.com/peixe2b/unilogic/blob/main/Compiler/Runtime/ul_arena.c): `Compiler/Runtime/ul_arena.c`

### Product Entry

- [CLI driver](https://github.com/peixe2b/unilogic/blob/main/Main.py): `Main.py`
- [Project commands](https://github.com/peixe2b/unilogic/blob/main/Main.py): `Main.py`
- [Profiler capability](https://github.com/peixe2b/unilogic/blob/main/Main.py): `Main.py`

### Other components

- **UL developer**

## Connections

- UL developer → CLI driver: invokes
- CLI driver → Lexer: tokenizes (evidence: `Main.py`)
- CLI driver → Parser: parses (evidence: `Main.py`)
- Parser → AST model: builds (evidence: `Compiler/AST Gen/token2ast.py`)
- CLI driver → AST normalizer: normalizes (evidence: `Main.py`)
- CLI driver → Semantic checker: checks (evidence: `Main.py`)
- Semantic checker → AST model: walks (evidence: `Compiler/Semantic/semcheck.py`)
- AST normalizer → AST model: rewrites (evidence: `Compiler/simplifycode.py`)
- CLI driver → C generator: generates C (evidence: `Main.py`)
- CLI driver → Python generator: generates Python (evidence: `Main.py`)
- CLI driver → JavaScript generator: generates JavaScript (evidence: `Main.py`)
- CLI driver → LLVM generator: generates LLVM (evidence: `Main.py`)
- CLI driver → WebAssembly target: targets WASM (evidence: `Main.py`)
- CLI driver → Python encoder: transpiles Python (evidence: `Main.py`)
- CLI driver → C encoder: transpiles C
- CLI driver → Bytecode encoder: emits bytecode (evidence: `Main.py`)
- C generator → AST model: walks (evidence: `Transcoder/Decoder/ul2c.py`)
- C generator → Semantic checker: uses type map (evidence: `Transcoder/Decoder/ul2c.py`)
- Python generator → AST model: walks (evidence: `Transcoder/Decoder/ul2py.py`)
- JavaScript generator → AST model: walks (evidence: `Transcoder/Decoder/ul2js.py`)
- LLVM generator → AST model: walks (evidence: `Transcoder/Decoder/ul2llvm.py`)
- Bytecode encoder → AST model: uses nodes (evidence: `Transcoder/Encoder/ul2ubi.py`)
- CLI driver → Project commands: offers commands (evidence: `Main.py`)
- CLI driver → Profiler capability: offers profiling (evidence: `Main.py`)
- C generator → Garbage collector: selects by DR
- C generator → Manual memory: selects by DR
- C generator → Reference counting: selects by DR
- C generator → Arena allocator: selects by DR
- Garbage collector → Manual memory
- Garbage collector → Reference counting
- Garbage collector → Arena allocator
