# pulkitjakhmola/compiler-pbl-4devs-6sem architecture

> Architecture diagram of the GitHub repository pulkitjakhmola/compiler-pbl-4devs-6sem, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulkitjakhmola/compiler-pbl-4devs-6sem
- Repository: https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem

## Overview

1. **What this repo is**
   `ams-lang` is a C++17-based language engine for AutomonScript (`.ams`). Its architecture is centered on a **transpile/build pipeline**: source scripts are parsed, converted into an internal representation, then compiled into a runnable executable with runtime support.

2. **Main top-level flow**
   The primary data path is:
   **`.ams` source → grammar/parser → AST/builder layer → compiler/generator → executable**
   The runtime and standard library headers provide the execution services that generated code depends on, especially for I/O and system utilities.

3. **Language front end**
   The `grammar/AMS.g4` file is the language specification. This strongly suggests an **ANTLR4-based parser front end**, with the grammar defining the tokenization and syntax rules for AMS. The custom support header `caseCaptilizeInputStream.hpp` indicates there is at least one specialized parsing/input adaptation layer.

4. **AST and build layer**
   `include/core/builder/AST.hpp` and `Builder.hpp` form the core structural layer between parsing and code generation. This is where parsed language constructs are represented as an AST or similar intermediate model, and where higher-level compilation/build logic likely normalizes source into compiler-friendly structures.

5. **Code generation layer**
   `include/core/compiler/Generator.hpp` is the output-oriented subsystem. Based on the repository description, this is the component that turns the internal model into “compiled execution” output. In an architecture diagram, this is the boundary where language semantics become deployable artifacts.

6. **Runtime subsystem**
   `include/runtime/runtime.hpp` is the runtime entry point. This is the execution support layer that generated programs rely on at runtime, separating language implementation concerns from the user’s script logic.

7. **Standard library**
   `include/stdlib` provides built-in functionality exposed to AMS scripts. The visible modules are:
   - `stdlib/io/console.hpp` for console I/O
   - `stdlib/utils/system.hpp` for system-level utilities  
   This subsystem is likely consumed by both generated code and runtime services, and it is an important boundary for script capabilities.

8. **CLI / driver**
   `src/driver/main.cpp` is the command-line entry point for the `ams` tool. The README describes it as managing the **build-and-run lifecycle**, so this is the orchestration layer that invokes parsing, compilation, and execution workflows.

9. **Packaging and build system**
   `CMakeLists.txt` indicates the project is built as a CMake-based C++ project. The install scripts (`ams_install_linux.sh`, `ams_install_windows.ps1`, plus dependency scripts) show that setup is automated for both Linux and Windows, so the repo supports cross-platform developer setup and tool installation.

10. **Examples and validation**
   `examples/hello_world.ams` and `examples/basic_operators.ams` act as reference inputs for the language pipeline. These examples are useful diagram anchors because they show the expected input to the compiler and the kind of runnable output the engine produces.

11. **Documentation and repo structure**
   `docs/PROJECT_STRUCTURE.md` and the README provide the main architectural map for contributors. The issue templates and `CONTRIBUTING.md` are supporting project infrastructure, not part of runtime execution, but they reinforce that this is a toolchain-style repository rather than an application runtime alone.

12. **Architectural boundary summary**
   A clean diagram should separate:
   - **Language definition**: grammar
   - **Compilation model**: AST/builder + generator
   - **Execution support**: runtime + stdlib
   - **User interface**: CLI driver
   - **Build/distribution**: CMake + install scripts  
   The most important flow is that the CLI coordinates the build, the parser and builder transform source into an internal model, and the generator/runtime combination produces and supports executable AMS programs.

Main entry points: [`src/driver/main.cpp`](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/src/driver/main.cpp) (ams CLI), [`CMakeLists.txt`](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/CMakeLists.txt) (CMake build), [`include/core/compiler/Generator.hpp`](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/compiler/Generator.hpp) (Generator), [`grammar/AMS.g4`](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/grammar/AMS.g4) (AMS grammar)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_frontend["Language front end"]
  node_node_grammar["AMS grammar<br/>antlr grammar<br/>[AMS.g4]"]
  node_node_input_stream["Case stream<br/>parse adapter"]
end

subgraph group_group_compile["Compile pipeline"]
  node_node_builder_ast["AST<br/>intermediate model<br/>[AST.hpp]"]
  node_node_builder["Builder<br/>build layer<br/>[Builder.hpp]"]
  node_node_generator["Generator<br/>codegen<br/>[Generator.hpp]"]
end

subgraph group_group_runtime["Execution support"]
  node_node_runtime["Runtime<br/>execution core<br/>[runtime.hpp]"]
  node_node_console["Console I/O<br/>stdlib io<br/>[console.hpp]"]
  node_node_system["System utils<br/>stdlib utils<br/>[system.hpp]"]
end

subgraph group_group_cli["Tooling"]
  node_node_cli(("ams CLI<br/>driver<br/>[main.cpp]"))
  node_node_cmake["CMake build<br/>build config<br/>[CMakeLists.txt]"]
  node_node_linux_install["Linux install<br/>installer script"]
  node_node_windows_install["Windows install<br/>installer script"]
  node_node_dep_linux["Deps Linux<br/>dependency script"]
  node_node_dep_windows["Deps Windows<br/>dependency script"]
end

subgraph group_group_docs["Project materials"]
  node_node_examples["Examples<br/>sample inputs<br/>[hello_world.ams]"]
  node_node_examples_ops["Operators<br/>sample inputs"]
  node_node_readme["README<br/>project docs<br/>[README.md]"]
  node_node_structure["Structure docs<br/>project docs"]
end

node_node_cli -->|"parses"| node_node_grammar
node_node_cli -->|"builds"| node_node_builder
node_node_grammar -->|"uses"| node_node_input_stream
node_node_grammar -->|"produces"| node_node_builder_ast
node_node_builder -->|"normalizes"| node_node_builder_ast
node_node_builder -->|"feeds"| node_node_generator
node_node_generator -->|"targets"| node_node_runtime
node_node_generator -->|"emits to"| node_node_console
node_node_generator -->|"uses"| node_node_system
node_node_runtime -->|"provides"| node_node_console
node_node_runtime -->|"provides"| node_node_system
node_node_examples -.->|"input to"| node_node_cli
node_node_examples_ops -.->|"input to"| node_node_cli
node_node_readme -.->|"documents"| node_node_cli
node_node_readme -.->|"documents"| node_node_builder
node_node_structure -.->|"documents"| node_node_grammar
node_node_cmake -->|"builds"| node_node_cli
node_node_linux_install -.->|"sets up"| node_node_cmake
node_node_windows_install -.->|"sets up"| node_node_cmake
node_node_dep_linux -.->|"supports"| node_node_cmake
node_node_dep_windows -.->|"supports"| node_node_cmake

click node_node_grammar "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/grammar/AMS.g4"
click node_node_input_stream "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/supports/caseCaptilizeInputStream.hpp"
click node_node_builder_ast "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/builder/AST.hpp"
click node_node_builder "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/builder/Builder.hpp"
click node_node_generator "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/compiler/Generator.hpp"
click node_node_runtime "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/runtime/runtime.hpp"
click node_node_console "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/stdlib/io/console.hpp"
click node_node_system "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/stdlib/utils/system.hpp"
click node_node_cli "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/src/driver/main.cpp"
click node_node_cmake "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/CMakeLists.txt"
click node_node_linux_install "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/ams_install_linux.sh"
click node_node_windows_install "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/ams_install_windows.ps1"
click node_node_dep_linux "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/install_dependency_linux.sh"
click node_node_dep_windows "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/install_dependency.ps1"
click node_node_examples "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/examples/hello_world.ams"
click node_node_examples_ops "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/examples/basic_operators.ams"
click node_node_readme "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/README.md"
click node_node_structure "https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/docs/PROJECT_STRUCTURE.md"

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_node_grammar,node_node_input_stream toneBlue
class node_node_builder_ast,node_node_builder,node_node_generator toneAmber
class node_node_runtime,node_node_console,node_node_system toneMint
class node_node_cli,node_node_cmake,node_node_linux_install,node_node_windows_install,node_node_dep_linux,node_node_dep_windows toneRose
class node_node_examples,node_node_examples_ops,node_node_readme,node_node_structure toneIndigo
```

## Components

### Language front end

Grammar and parsing support for AMS source files.

- [AMS grammar](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/grammar/AMS.g4): antlr grammar · Defines the AMS language syntax and tokens. · `grammar/AMS.g4`
- [Case stream](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/supports/caseCaptilizeInputStream.hpp): parse adapter · Specialized input stream support used during parsing. · `include/core/supports/caseCaptilizeInputStream.hpp`

### Compile pipeline

Internal model and code generation steps.

- [AST](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/builder/AST.hpp): intermediate model · Core abstract syntax representation for parsed AMS programs. · `include/core/builder/AST.hpp`
- [Builder](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/builder/Builder.hpp): build layer · Transforms parsed source into the compiler-friendly internal structure. · `include/core/builder/Builder.hpp`
- [Generator](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/core/compiler/Generator.hpp): codegen · Converts the internal model into compiled output. · `include/core/compiler/Generator.hpp`

### Execution support

Runtime services and standard library used by generated programs.

- [Runtime](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/runtime/runtime.hpp): execution core · Runtime entry point and execution support for generated programs. · `include/runtime/runtime.hpp`
- [Console I/O](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/stdlib/io/console.hpp): stdlib io · Built-in console input and output facilities. · `include/stdlib/io/console.hpp`
- [System utils](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/include/stdlib/utils/system.hpp): stdlib utils · Built-in system-level helper functions exposed to AMS scripts. · `include/stdlib/utils/system.hpp`

### Tooling

Command-line entry point and repository tooling.

- [ams CLI](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/src/driver/main.cpp): driver · Command-line entry point that orchestrates build and run workflows. · `src/driver/main.cpp`
- [CMake build](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/CMakeLists.txt): build config · Primary build configuration for the C++ project. · `CMakeLists.txt`
- [Linux install](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/ams_install_linux.sh): installer script · Linux setup and installation automation. · `ams_install_linux.sh`
- [Windows install](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/ams_install_windows.ps1): installer script · Windows setup and installation automation. · `ams_install_windows.ps1`
- [Deps Linux](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/install_dependency_linux.sh): dependency script · Linux dependency installation helper. · `install_dependency_linux.sh`
- [Deps Windows](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/install_dependency.ps1): dependency script · Windows dependency installation helper. · `install_dependency.ps1`

### Project materials

Examples, documentation, and contribution scaffolding.

- [Examples](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/examples/hello_world.ams): sample inputs · Reference AMS programs used to demonstrate the language pipeline. · `examples/hello_world.ams`
- [Operators](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/examples/basic_operators.ams): sample inputs · Example AMS program covering basic operators. · `examples/basic_operators.ams`
- [README](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/README.md): project docs · Primary repository overview and usage guide. · `README.md`
- [Structure docs](https://github.com/pulkitjakhmola/compiler-pbl-4devs-6sem/blob/main/docs/PROJECT_STRUCTURE.md): project docs · Repository structure and architecture notes. · `docs/PROJECT_STRUCTURE.md`

## Connections

- ams CLI → AMS grammar: parses · CLI starts the front-end parsing flow.
- ams CLI → Builder: builds · CLI coordinates compilation of AMS source.
- AMS grammar → Case stream: uses · Grammar parsing is adapted by the custom input stream layer.
- AMS grammar → AST: produces · Parsed language structures are represented in the AST.
- Builder → AST: normalizes · Builder shapes parsed constructs into the internal model.
- Builder → Generator: feeds · Builder passes the prepared model to code generation.
- Generator → Runtime: targets · Generated output is meant to run with runtime support.
- Generator → Console I/O: emits to · Generated programs rely on console facilities for I/O.
- Generator → System utils: uses · Generated programs can call system utilities from the stdlib.
- Runtime → Console I/O: provides · Runtime exposes console services to generated code.
- Runtime → System utils: provides · Runtime exposes system services to generated code.
- Examples → ams CLI: input to · Example scripts are representative inputs to the toolchain.
- Operators → ams CLI: input to · Example scripts are representative inputs to the toolchain.
- README → ams CLI: documents · README explains tool usage and workflow.
- README → Builder: documents · README describes the build pipeline.
- Structure docs → AMS grammar: documents · Structure docs map the language front end.
- CMake build → ams CLI: builds · CMake config compiles the driver and core components.
- Linux install → CMake build: sets up · Installer script prepares the project build environment on Linux.
- Windows install → CMake build: sets up · Installer script prepares the project build environment on Windows.
- Deps Linux → CMake build: supports · Dependency setup script supports Linux builds.
- Deps Windows → CMake build: supports · Dependency setup script supports Windows builds.
