# khuethuc/co3005-ppl-hk232 architecture

> Architecture diagram of the GitHub repository khuethuc/co3005-ppl-hk232, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khuethuc/co3005-ppl-hk232
- Repository: https://github.com/khuethuc/co3005-ppl-hk232

## Overview

##### Main Components
- Input (ZCode source code) – starting point
- Lexical Analyzer (Lexer) – based on ANTLR (you see files and directories such as .antlr, ZCodeLexer.py, tokens, etc.)
- Parser – the parser is generated using the provided grammar (ZCode.g4) and includes ANTLR listener, visitor, and error modules.
- AST Generation – seen in assignment2 and later (files like ASTGeneration.py and AST.py); this is responsible for constructing the program’s AST.
- Static Checker – found in assignment3 and assignment4 (StaticCheck.py, StaticError.py) that performs semantic analysis.
- Code Generator – present in assignment3 and assignment4 (CodeGenerator.py, Emitter.py, Frame.py, MachineCode.py) to translate the AST into intermediate or target code.
- External Dependencies – note the presence of an external jar (jasmin.jar) which likely is used in assembling or further processing the generated code.
- Testing and Utilities – there are extensive test suites (LexerSuite, ParserSuite, ASTGenSuite, CheckSuite, CodeGenSuite, etc.) and supportive utility files.

##### Relationships and Data Flow
- Flow proceeds to the Lexical Analyzer that tokenizes input using ANTLR-generated components.
- Tokens then feed into the Parser, which builds a parse tree.
- An AST Generation phase walks the parse tree and constructs an abstract syntax tree.
- The AST flows to the Static Checker to ensure that semantic rules are satisfied.
- Upon passing semantic analysis, the AST is handed to the Code Generation phase to produce lower-level or machine code (with jasmin.jar assisting if assembly is required).
- Testing modules exist separately (under src/test and target/test) to validate each phase.

##### Architectural Patterns & Design Principles to Highlight
- Pipeline Pattern: The compiler’s phases (lexing, parsing, AST generation, static checking, code generation) directly follow one another in a pipeline.
- Layer Separation: Clearly distinct modules for each compiler phase, with well-defined responsibilities.
- Modularity: Each assignment directory reinforces unit testing and modular development. The use of ANTLR for the language front-end and external libraries for code generation (jasmin.jar) is also an architectural choice.
- Iterative Development: Multiple assignments indicate an evolution of the project where each component is refined over time.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Pipeline
    Input["Input (ZCode source)"]:::input
    RunModule["Run Module"]:::input
    Lexer["Lexer (ANTLR)"]:::frontend
    Parser["Parser (ZCode.g4)"]:::frontend

    subgraph "AST Generation"
        ASTGen["AST Generation (ASTGeneration.py)"]:::core
        ASTUtil["AST Utils (AST.py)"]:::core
        ASTGen -->|"generates"| ASTUtil
    end

    subgraph "Static Checker"
        SC["Static Check (StaticCheck.py)"]:::core
        SE["Static Error (StaticError.py)"]:::core
        SC -->|"handles"| SE
    end

    subgraph "Code Generation"
        CG["Code Generator (CodeGenerator.py)"]:::backend
        Emitter["Emitter (Emitter.py)"]:::backend
        Frame["Frame (Frame.py)"]:::backend
        Machine["Machine Code (MachineCode.py)"]:::backend
        CG -->|"triggers"| Emitter
        Emitter -->|"feeds"| Frame
        Frame -->|"assembles"| Machine
    end

    Jasmin["jasmin.jar (External Dependency)"]:::external

    Testing["Testing Suite(s)"]:::testing

    %% Pipeline Flow
    Input -->|"feeds"| RunModule
    RunModule -->|"invokes"| Lexer
    Lexer -->|"tokenizes"| Parser
    Parser -->|"builds parse tree"| ASTGen
    ASTUtil -->|"constructed AST"| SC
    SC -->|"validated AST"| CG
    Machine -->|"produces code"| Jasmin

    %% Testing Connection (dotted link)
    RunModule ---|"monitored by"| Testing

    %% Click Events
    click RunModule "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment1/src/run.py"
    click Lexer "https://github.com/khuethuc/co3005-ppl-hk232/tree/main/assignment1/src/main/zcode/parser/.antlr/"
    click Lexer "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment1/src/main/zcode/parser/ZCodeLexer.py"
    click Parser "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment1/src/main/zcode/parser/ZCode.g4"
    click ASTGen "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment2/src/main/zcode/astgen/ASTGeneration.py"
    click ASTUtil "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment2/src/main/zcode/utils/AST.py"
    click SC "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/checker/StaticCheck.py"
    click SE "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/checker/StaticError.py"
    click CG "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/codegen/CodeGenerator.py"
    click Emitter "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/codegen/Emitter.py"
    click Frame "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/codegen/Frame.py"
    click Machine "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/main/zcode/codegen/MachineCode.py"
    click Jasmin "https://github.com/khuethuc/co3005-ppl-hk232/blob/main/assignment3/src/external/jasmin.jar"
    click Testing "https://github.com/khuethuc/co3005-ppl-hk232/tree/main/assignment1/src/test"

    %% Styles
    classDef input fill:#FDB813,stroke:#333,stroke-width:2px;
    classDef frontend fill:#9be4ff,stroke:#333,stroke-width:2px;
    classDef core fill:#A2FAA3,stroke:#333,stroke-width:2px;
    classDef backend fill:#FF9999,stroke:#333,stroke-width:2px;
    classDef external fill:#E0E7FF,stroke:#333,stroke-width:2px;
    classDef testing fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
