# uocazizah/tracey architecture

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

- Interactive diagram: https://gitdiagram.com/uocazizah/tracey
- Repository: https://github.com/uocazizah/tracey

## Overview

Tracey is a bootstrap-stage compiler for the `.trc` language. The intended user journey is to invoke the compiler on source code, which is loaded and processed through lexical, syntactic, and semantic analysis before code generation; assembler and linker components support producing native output. The README identifies these capabilities but does not document the precise runtime call graph, and the sampled source excerpts do not show those calls. Dashed, unevidenced edges mark the inferred workflow; other documented capabilities are represented without speculative connections.

Main entry points: [`index.cxx`](https://github.com/uocazizah/tracey/blob/master/index.cxx) (Compiler CLI), [`general/parser/parser.cxx`](https://github.com/uocazizah/tracey/blob/master/general/parser/parser.cxx) (Parser), [`general/semantic/semantic.cxx`](https://github.com/uocazizah/tracey/blob/master/general/semantic/semantic.cxx) (Semantic analysis), [`general/assembler/assembler.cxx`](https://github.com/uocazizah/tracey/blob/master/general/assembler/assembler.cxx) (Assembler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_compiler_cli["Compiler CLI<br/>[index.cxx]"]
  node_arguments["Arguments<br/>[argument.cxx]"]
end

subgraph group_frontend["Compiler front end"]
  node_source["Source loading<br/>[source.cxx]"]
  node_lexer["Lexer<br/>[lexer.cxx]"]
  node_parser["Parser<br/>[parser.cxx]"]
  node_semantic["Semantic analysis<br/>[semantic.cxx]"]
  node_ast["Syntax tree<br/>[ast.hxx]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.cxx]"]
end

subgraph group_backend["Native toolchain"]
  node_codegen["Code generation<br/>[codegen.cxx]"]
  node_assembler["Assembler<br/>[assembler.cxx]"]
  node_assembler_driver["Assembler driver<br/>[tracey-as.cxx]"]
  node_elf["ELF support<br/>[elf.cxx]"]
  node_linker["Linker<br/>[linker.cxx]"]
  node_linker_driver["Linker driver<br/>[tracey-ld.cxx]"]
end

subgraph group_support["Language support"]
  node_stdlib["Standard library"]
  node_runtime["Mini runtime"]
end

node_programmer(("Programmer"))

node_programmer -->|"invokes"| node_compiler_cli
node_compiler_cli -.->|"parses options"| node_arguments
node_compiler_cli -.->|"loads input"| node_source
node_source -.->|"provides source"| node_lexer
node_lexer -.->|"tokens"| node_parser
node_parser -.->|"builds tree"| node_ast
node_parser -.->|"analyzes syntax"| node_semantic
node_semantic -.->|"enables generation"| node_codegen
node_semantic -.->|"reports issues"| node_diagnostics
node_codegen -.->|"emits for"| node_assembler
node_assembler_driver -.->|"drives"| node_assembler
node_assembler -.->|"produces objects"| node_elf
node_linker_driver -.->|"drives"| node_linker
node_linker -.->|"handles binaries"| node_elf

click node_compiler_cli "https://github.com/uocazizah/tracey/blob/master/index.cxx"
click node_arguments "https://github.com/uocazizah/tracey/blob/master/general/argument/argument.cxx"
click node_source "https://github.com/uocazizah/tracey/blob/master/general/source/source.cxx"
click node_lexer "https://github.com/uocazizah/tracey/blob/master/general/lexer/lexer.cxx"
click node_parser "https://github.com/uocazizah/tracey/blob/master/general/parser/parser.cxx"
click node_semantic "https://github.com/uocazizah/tracey/blob/master/general/semantic/semantic.cxx"
click node_ast "https://github.com/uocazizah/tracey/blob/master/include/tracey/ast.hxx"
click node_diagnostics "https://github.com/uocazizah/tracey/blob/master/general/diagnostics/diagnostics.cxx"
click node_codegen "https://github.com/uocazizah/tracey/blob/master/general/codegen/codegen.cxx"
click node_assembler "https://github.com/uocazizah/tracey/blob/master/general/assembler/assembler.cxx"
click node_assembler_driver "https://github.com/uocazizah/tracey/blob/master/tools/tracey-as.cxx"
click node_elf "https://github.com/uocazizah/tracey/blob/master/general/elf/elf.cxx"
click node_linker "https://github.com/uocazizah/tracey/blob/master/general/linker/linker.cxx"
click node_linker_driver "https://github.com/uocazizah/tracey/blob/master/tools/tracey-ld.cxx"
click node_stdlib "https://github.com/uocazizah/tracey/tree/master/lib"
click node_runtime "https://github.com/uocazizah/tracey/tree/master/runtime"

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_compiler_cli,node_arguments toneBlue
class node_source,node_lexer,node_parser,node_semantic,node_ast,node_diagnostics toneAmber
class node_codegen,node_assembler,node_assembler_driver,node_elf,node_linker,node_linker_driver toneMint
class node_stdlib,node_runtime toneRose
class node_programmer toneIndigo
```

## Components

### User interface

- [Compiler CLI](https://github.com/uocazizah/tracey/blob/master/index.cxx): `index.cxx`
- [Arguments](https://github.com/uocazizah/tracey/blob/master/general/argument/argument.cxx): `general/argument/argument.cxx`

### Compiler front end

- [Source loading](https://github.com/uocazizah/tracey/blob/master/general/source/source.cxx): `general/source/source.cxx`
- [Lexer](https://github.com/uocazizah/tracey/blob/master/general/lexer/lexer.cxx): `general/lexer/lexer.cxx`
- [Parser](https://github.com/uocazizah/tracey/blob/master/general/parser/parser.cxx): `general/parser/parser.cxx`
- [Semantic analysis](https://github.com/uocazizah/tracey/blob/master/general/semantic/semantic.cxx): `general/semantic/semantic.cxx`
- [Syntax tree](https://github.com/uocazizah/tracey/blob/master/include/tracey/ast.hxx): `include/tracey/ast.hxx`
- [Diagnostics](https://github.com/uocazizah/tracey/blob/master/general/diagnostics/diagnostics.cxx): `general/diagnostics/diagnostics.cxx`

### Native toolchain

- [Code generation](https://github.com/uocazizah/tracey/blob/master/general/codegen/codegen.cxx): `general/codegen/codegen.cxx`
- [Assembler](https://github.com/uocazizah/tracey/blob/master/general/assembler/assembler.cxx): `general/assembler/assembler.cxx`
- [Assembler driver](https://github.com/uocazizah/tracey/blob/master/tools/tracey-as.cxx): `tools/tracey-as.cxx`
- [ELF support](https://github.com/uocazizah/tracey/blob/master/general/elf/elf.cxx): `general/elf/elf.cxx`
- [Linker](https://github.com/uocazizah/tracey/blob/master/general/linker/linker.cxx): `general/linker/linker.cxx`
- [Linker driver](https://github.com/uocazizah/tracey/blob/master/tools/tracey-ld.cxx): `tools/tracey-ld.cxx`

### Language support

- [Standard library](https://github.com/uocazizah/tracey/tree/master/lib): `lib`
- [Mini runtime](https://github.com/uocazizah/tracey/tree/master/runtime): `runtime`

### Other components

- **Programmer**

## Connections

- Programmer → Compiler CLI: invokes (evidence: `README`)
- Compiler CLI → Arguments: parses options
- Compiler CLI → Source loading: loads input
- Source loading → Lexer: provides source
- Lexer → Parser: tokens
- Parser → Syntax tree: builds tree
- Parser → Semantic analysis: analyzes syntax
- Semantic analysis → Code generation: enables generation
- Semantic analysis → Diagnostics: reports issues
- Code generation → Assembler: emits for
- Assembler driver → Assembler: drives
- Assembler → ELF support: produces objects
- Linker driver → Linker: drives
- Linker → ELF support: handles binaries