# sharir/jai architecture

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

- Interactive diagram: https://gitdiagram.com/sharir/jai
- Repository: https://github.com/sharir/jai

## Overview

1. This repository is a native C++ implementation of an alternate Jai compiler. The architecture is centered in `csrc/`, with a small set of frontend/compiler components and a few support abstractions around files, tokens, and platform handling.

2. The top-level entry point is likely `csrc/jai.cpp`, which ties together the compilation pipeline. `build.sh` is the project-level build driver, and the repo is meant to be opened in Sublime Text with a local build task rather than deployed as a service.

3. Source input enters through the file layer in `csrc/file.cpp` and `csrc/file.h`. This looks like the boundary for reading source text from disk and representing source files before they are transformed by the compiler pipeline.

4. The preprocessing stage is split out explicitly in `csrc/preprocessor.cpp` and `csrc/preprocessor.h`. That suggests the compiler does not send raw source directly to parsing; instead it first expands or normalizes input, probably handling source-level directives or include-like behavior.

5. Lexing is handled separately in `csrc/lexer.cpp` and `csrc/lexer.h`. The lexer converts preprocessed character streams into tokens, and `csrc/token.h` defines the token data model shared by later stages.

6. Parsing is isolated in `csrc/parser.cpp` and `csrc/parser.h`. This stage consumes tokens and builds the language’s structural representation, likely producing an AST or similar intermediate form for the compiler to operate on.

7. `csrc/compiler.cpp` and `csrc/compiler.h` appear to orchestrate the overall compilation flow. In architectural terms, this is the coordination layer that connects preprocessing, lexing, parsing, and any later semantic or output-generation steps.

8. `csrc/os.h` provides a platform boundary, and `csrc/utils.cpp` / `csrc/utils.h` provide shared helper routines. These support modules keep OS-specific behavior and generic helpers out of the language-processing stages, which helps keep the frontend logic cleaner.

9. The `grammar/` directory is a language reference asset rather than runtime code. It likely documents or experiments with Jai syntax and serves as a specification aid for the parser and lexer implementation.

10. The `test/` directory contains small Jai source files such as `hello.jai`, `lexerror.jai`, and `multiline.jai`. These are likely used as manual or scripted validation inputs for the frontend pipeline, especially lexing and parsing behavior.

11. The main data flow is therefore: source file on disk → file loader → preprocessor → lexer → token stream → parser → compiler orchestration. Any architecture diagram for this repo should emphasize that it is primarily a compiler frontend with a clear stage-by-stage pipeline, plus thin cross-cutting support for files, utilities, and OS concerns.

12. The project is intentionally experimental and not positioned as a specification-perfect Jai compiler. That means the architecture is driven more by an incremental implementation of compiler stages than by a large runtime or toolchain ecosystem.

Main entry points: [`csrc/compiler.cpp`](https://github.com/sharir/jai/blob/master/csrc/compiler.cpp) (Compiler), [`csrc/lexer.cpp`](https://github.com/sharir/jai/blob/master/csrc/lexer.cpp) (Lexer), [`csrc/parser.cpp`](https://github.com/sharir/jai/blob/master/csrc/parser.cpp) (Parser), [`csrc/preprocessor.cpp`](https://github.com/sharir/jai/blob/master/csrc/preprocessor.cpp) (Preprocessor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_csrc["Compiler Core"]
  node_n_jai_main(("jai.cpp<br/>entrypoint<br/>[jai.cpp]"))
  node_n_compiler["Compiler<br/>orchestrator<br/>[compiler.cpp]"]
  node_n_file[("File I/O<br/>source loader<br/>[file.cpp]")]
  node_n_preprocessor["Preprocessor<br/>stage<br/>[preprocessor.cpp]"]
  node_n_lexer["Lexer<br/>stage<br/>[lexer.cpp]"]
  node_n_token["Token Model<br/>data model<br/>[token.h]"]
  node_n_parser["Parser<br/>stage<br/>[parser.cpp]"]
  node_n_os["OS Boundary<br/>platform layer<br/>[os.h]"]
  node_n_utils["Utils<br/>helpers<br/>[utils.cpp]"]
  node_n_file_h["file.h<br/>interface<br/>[file.h]"]
  node_n_preprocessor_h["preprocessor.h<br/>interface<br/>[preprocessor.h]"]
  node_n_lexer_h["lexer.h<br/>interface<br/>[lexer.h]"]
  node_n_parser_h["parser.h<br/>interface<br/>[parser.h]"]
  node_n_compiler_h["compiler.h<br/>interface<br/>[compiler.h]"]
  node_n_utils_h["utils.h<br/>interface<br/>[utils.h]"]
end

subgraph group_grp_assets["Language Assets"]
  node_n_grammar["Grammar<br/>reference"]
  node_n_test_hello["hello.jai<br/>sample input<br/>[hello.jai]"]
  node_n_test_lexerror["lexerror.jai<br/>sample input<br/>[lexerror.jai]"]
  node_n_test_multiline["multiline.jai<br/>sample input<br/>[multiline.jai]"]
end

subgraph group_grp_root["Project Root"]
  node_n_build["build.sh<br/>build driver<br/>[build.sh]"]
  node_n_readme["README<br/>docs<br/>[README.md]"]
end

node_n_jai_main -->|"starts"| node_n_compiler
node_n_compiler -->|"loads"| node_n_file
node_n_compiler -->|"runs"| node_n_preprocessor
node_n_preprocessor -->|"feeds"| node_n_lexer
node_n_lexer -->|"emits"| node_n_token
node_n_token -->|"consumed by"| node_n_parser
node_n_parser -->|"returns"| node_n_compiler
node_n_compiler -->|"uses"| node_n_os
node_n_compiler -->|"uses"| node_n_utils
node_n_build -->|"builds"| node_n_jai_main
node_n_readme -.->|"documents"| node_n_build
node_n_grammar -.->|"guides"| node_n_parser
node_n_test_hello -.->|"validates"| node_n_lexer
node_n_test_lexerror -.->|"validates"| node_n_lexer
node_n_test_multiline -.->|"validates"| node_n_parser
node_n_file_h -->|"declares"| node_n_file
node_n_preprocessor_h -->|"declares"| node_n_preprocessor
node_n_lexer_h -->|"declares"| node_n_lexer
node_n_parser_h -->|"declares"| node_n_parser
node_n_compiler_h -->|"declares"| node_n_compiler
node_n_utils_h -->|"declares"| node_n_utils

click node_n_jai_main "https://github.com/sharir/jai/blob/master/csrc/jai.cpp"
click node_n_compiler "https://github.com/sharir/jai/blob/master/csrc/compiler.cpp"
click node_n_file "https://github.com/sharir/jai/blob/master/csrc/file.cpp"
click node_n_preprocessor "https://github.com/sharir/jai/blob/master/csrc/preprocessor.cpp"
click node_n_lexer "https://github.com/sharir/jai/blob/master/csrc/lexer.cpp"
click node_n_token "https://github.com/sharir/jai/blob/master/csrc/token.h"
click node_n_parser "https://github.com/sharir/jai/blob/master/csrc/parser.cpp"
click node_n_os "https://github.com/sharir/jai/blob/master/csrc/os.h"
click node_n_utils "https://github.com/sharir/jai/blob/master/csrc/utils.cpp"
click node_n_build "https://github.com/sharir/jai/blob/master/build.sh"
click node_n_readme "https://github.com/sharir/jai/blob/master/README.md"
click node_n_grammar "https://github.com/sharir/jai/tree/master/grammar"
click node_n_test_hello "https://github.com/sharir/jai/blob/master/test/hello.jai"
click node_n_test_lexerror "https://github.com/sharir/jai/blob/master/test/lexerror.jai"
click node_n_test_multiline "https://github.com/sharir/jai/blob/master/test/multiline.jai"
click node_n_file_h "https://github.com/sharir/jai/blob/master/csrc/file.h"
click node_n_preprocessor_h "https://github.com/sharir/jai/blob/master/csrc/preprocessor.h"
click node_n_lexer_h "https://github.com/sharir/jai/blob/master/csrc/lexer.h"
click node_n_parser_h "https://github.com/sharir/jai/blob/master/csrc/parser.h"
click node_n_compiler_h "https://github.com/sharir/jai/blob/master/csrc/compiler.h"
click node_n_utils_h "https://github.com/sharir/jai/blob/master/csrc/utils.h"

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_n_jai_main,node_n_compiler,node_n_file,node_n_preprocessor,node_n_lexer,node_n_token,node_n_parser,node_n_os,node_n_utils,node_n_file_h,node_n_preprocessor_h,node_n_lexer_h,node_n_parser_h,node_n_compiler_h,node_n_utils_h toneBlue
class node_n_grammar,node_n_test_hello,node_n_test_lexerror,node_n_test_multiline toneAmber
class node_n_build,node_n_readme toneMint
```

## Components

### Compiler Core

Native C++ compiler frontend and orchestration code in csrc/

- [jai.cpp](https://github.com/sharir/jai/blob/master/csrc/jai.cpp): entrypoint · Program entrypoint; starts the compiler pipeline · `csrc/jai.cpp`
- [Compiler](https://github.com/sharir/jai/blob/master/csrc/compiler.cpp): orchestrator · Coordinates the overall compilation flow across stages · `csrc/compiler.cpp`
- [File I/O](https://github.com/sharir/jai/blob/master/csrc/file.cpp): source loader · Reads source text and models files before compilation · `csrc/file.cpp`
- [Preprocessor](https://github.com/sharir/jai/blob/master/csrc/preprocessor.cpp): stage · Normalizes or expands source before lexing · `csrc/preprocessor.cpp`
- [Lexer](https://github.com/sharir/jai/blob/master/csrc/lexer.cpp): stage · Converts character input into tokens · `csrc/lexer.cpp`
- [Token Model](https://github.com/sharir/jai/blob/master/csrc/token.h): data model · Shared token representation consumed by later stages · `csrc/token.h`
- [Parser](https://github.com/sharir/jai/blob/master/csrc/parser.cpp): stage · Consumes tokens and builds the language structure · `csrc/parser.cpp`
- [OS Boundary](https://github.com/sharir/jai/blob/master/csrc/os.h): platform layer · Platform-specific abstraction used by the compiler frontend · `csrc/os.h`
- [Utils](https://github.com/sharir/jai/blob/master/csrc/utils.cpp): helpers · Shared helper routines used across compiler stages · `csrc/utils.cpp`
- [file.h](https://github.com/sharir/jai/blob/master/csrc/file.h): interface · File layer interface · `csrc/file.h`
- [preprocessor.h](https://github.com/sharir/jai/blob/master/csrc/preprocessor.h): interface · Preprocessor interface · `csrc/preprocessor.h`
- [lexer.h](https://github.com/sharir/jai/blob/master/csrc/lexer.h): interface · Lexer interface · `csrc/lexer.h`
- [parser.h](https://github.com/sharir/jai/blob/master/csrc/parser.h): interface · Parser interface · `csrc/parser.h`
- [compiler.h](https://github.com/sharir/jai/blob/master/csrc/compiler.h): interface · Compiler orchestration interface · `csrc/compiler.h`
- [utils.h](https://github.com/sharir/jai/blob/master/csrc/utils.h): interface · Utilities interface · `csrc/utils.h`

### Language Assets

Reference grammar and sample Jai inputs used to guide and validate the compiler

- [Grammar](https://github.com/sharir/jai/tree/master/grammar): reference · Language reference and syntax asset for Jai · `grammar`
- [hello.jai](https://github.com/sharir/jai/blob/master/test/hello.jai): sample input · Basic frontend validation input · `test/hello.jai`
- [lexerror.jai](https://github.com/sharir/jai/blob/master/test/lexerror.jai): sample input · Lexing edge-case input · `test/lexerror.jai`
- [multiline.jai](https://github.com/sharir/jai/blob/master/test/multiline.jai): sample input · Multi-line source sample for frontend behavior · `test/multiline.jai`

### Project Root

Build and entrypoint files at the repository root

- [build.sh](https://github.com/sharir/jai/blob/master/build.sh): build driver · Repository-level build script · `build.sh`
- [README](https://github.com/sharir/jai/blob/master/README.md): docs · Project overview and usage notes · `README.md`

## Connections

- jai.cpp → Compiler: starts · Entrypoint launches the compilation pipeline
- Compiler → File I/O: loads · Compiler begins by reading source files
- Compiler → Preprocessor: runs · Compilation flow sends source through preprocessing
- Preprocessor → Lexer: feeds · Preprocessed text is handed to the lexer
- Lexer → Token Model: emits · Lexer produces shared token objects
- Token Model → Parser: consumed by · Tokens are consumed by the parser
- Parser → Compiler: returns · Parsed structure feeds back into orchestration
- Compiler → OS Boundary: uses · Compiler relies on platform abstractions
- Compiler → Utils: uses · Compiler shares generic helper routines
- build.sh → jai.cpp: builds · Build script compiles the native entrypoint
- README → build.sh: documents · Repository documentation describes build and usage
- Grammar → Parser: guides · Grammar asset informs parsing behavior
- hello.jai → Lexer: validates · Sample input exercises lexer behavior
- lexerror.jai → Lexer: validates · Edge-case sample targets lexing errors
- multiline.jai → Parser: validates · Sample input exercises multi-line parsing behavior
- file.h → File I/O: declares · File layer interface pairs with implementation
- preprocessor.h → Preprocessor: declares · Preprocessor interface pairs with implementation
- lexer.h → Lexer: declares · Lexer interface pairs with implementation
- parser.h → Parser: declares · Parser interface pairs with implementation
- compiler.h → Compiler: declares · Compiler interface pairs with implementation
- utils.h → Utils: declares · Utilities interface pairs with implementation
