# sh0g0-1758/scarlet architecture

> Architecture diagram of the GitHub repository sh0g0-1758/scarlet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sh0g0-1758/scarlet
- Repository: https://github.com/sh0g0-1758/scarlet

## Overview

##### Project & Architectural Overview
- Scarlet is a compiler built in C++, and its file hierarchy clearly separates the logical phases of compilation (lexical analysis, parsing, semantic analysis, code generation, and backend optimizations).
- The README confirms that the primary goal is to deepen our understanding of compiler construction while providing the platform for future machine learning projects.

##### Main Architectural Components
- Compiler Driver:
- The “driver” directory holds the central “driver.cc” that orchestrates the entire compilation process.
- This as the entry point that invokes each compiler phase.

- Frontend: Scanning & Parsing
- Lexer: Located under the “lexer” directory, responsible for reading source code and generating tokens.
- Parser: Found in the “parser” directory, it consumes tokens and constructs the Abstract Syntax Tree (AST).
- Token Module: Under “token” directory, which supports token data structures and definitions.
- AST: The “ast” directory holds implementations (ast.cc, ast.hh) representing syntax trees.
- Additional Submodules such as “binary_operations” and “unary_operations” help manage expression nodes and operator behaviors.

- Semantic Analysis:
- Inside the “parser” directory, the subdirectory “semantic_analysis” suggests that type checking and variable resolution are integrated.

- Backend / Code Generation:
- Code generation is implemented in the “codegen” directory. This component converts the AST to lower-level representations or direct assembly.
- That additional directories such as “codegen/scargen” and “codegen/scasmgen” indicate detailed sub-phases for pretty-printing, generating pseudo assembly, and fixing register issues.

- Supporting Modules & Tools:
- “cmd” may include command-line interface abstraction.
- “regex” is available for lexing pattern matching.
- “numloc.py” might be used to handle numeric literals or locations, which is a utility component.

- Test & Validation Infrastructure:
- There are extensive test directories (“tests”, “test_framework”, “stress”) that encapsulate unit tests, integration tests, and stress/memory tests.
- As secondary modules that interact with the core compiler pipeline for validation and continuous integration (the GitHub workflows reflect multiple OS/compiler configurations).

##### Data Flow & Relationships
- Within or immediately after Parser the Semantic Analysis phase, which refines the AST.
- Finally, illustrate the transformation into assembly or machine code along with a connection to the underlying linking (handled externally through system tools like GCC) as mentioned in the README.
- Compiler Driver as a controller connecting these phases.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Compiler Pipeline Subgraphs
    subgraph "Compiler Pipeline"
        direction TB
        SRC["Source Code"]:::input
        DRV["Compiler Driver"]:::main
        SRC --> DRV

        subgraph "Frontend"
            direction TB
            LEX["Lexer"]:::frontend
            TOK["Token Module"]:::frontend
            PAR["Parser & AST"]:::frontend
            LEX --> TOK
            TOK --> PAR
        end

        subgraph "Semantic Analysis"
            direction TB
            SEM["Semantic Analysis"]:::semantic
        end

        subgraph "Backend"
            direction TB
            CG["Code Generation"]:::backend
            SCAR["Scargen (Pretty-printing)"]:::backend
            SCASM["Scasmgen (Register Fixing)"]:::backend
            ASM["Executable Code"]:::backend
            LNK["Linker (GCC/Clang)"]:::backend
            CG --> SCAR
            CG --> SCASM
            CG --> ASM
            ASM --> LNK
        end

        %% Connections along the pipeline
        DRV -->|"invokes"| LEX
        PAR -->|"generates AST"| SEM
        SEM -->|"annotated AST"| CG
    end

    %% Supporting Modules Subgraph
    subgraph "Supporting Modules"
        direction TB
        CLI["Command-Line Interface"]:::util
        REG["Regex Support"]:::util
        TOOLS["Auxiliary Tools & Utilities"]:::util
        TEST["Testing & Validation"]:::test
    end

    %% Connections from Compiler Driver to Supporting Modules
    DRV -->|"uses"| CLI
    DRV -->|"uses"| REG
    DRV -->|"uses"| TOOLS
    DRV -->|"triggers"| TEST

    %% Class Definitions for color coding
    classDef input fill:#FFC0CB,stroke:#333,stroke-width:2px;
    classDef main fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef semantic fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef backend fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef util fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef test fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events for Component Mapping
    click DRV "https://github.com/sh0g0-1758/scarlet/blob/main/driver/driver.cc"
    click LEX "https://github.com/sh0g0-1758/scarlet/blob/main/lexer/lexer.cc"
    click TOK "https://github.com/sh0g0-1758/scarlet/blob/main/token/token.cc"
    click PAR "https://github.com/sh0g0-1758/scarlet/blob/main/parser/parser.cc"
    click SEM "https://github.com/sh0g0-1758/scarlet/tree/main/parser/semantic_analysis/"
    click CG "https://github.com/sh0g0-1758/scarlet/blob/main/codegen/codegen.cc"
    click SCAR "https://github.com/sh0g0-1758/scarlet/tree/main/codegen/scargen/"
    click SCASM "https://github.com/sh0g0-1758/scarlet/tree/main/codegen/scasmgen/"
    click CLI "https://github.com/sh0g0-1758/scarlet/blob/main/cmd/cmd.hh"
    click REG "https://github.com/sh0g0-1758/scarlet/blob/main/regex/regex.cc"
    click TOOLS "https://github.com/sh0g0-1758/scarlet/tree/main/tools/"
    click TEST "https://github.com/sh0g0-1758/scarlet/tree/main/tests/"
```
