# dstogov/simple architecture

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

- Interactive diagram: https://gitdiagram.com/dstogov/simple
- Repository: https://github.com/dstogov/simple

## Overview

##### Main Components
- Frontend (Language Parsing): At the beginning of the pipeline, the “Parser” (found in each chapter’s com/seaofnodes/simple package) converts the Simple source code into an initial IR. This includes the recursive descent parser and the AST-to-IR conversion.
- Intermediate Representation (IR) & Node System: The “node” package (embedded in nearly every chapter) defines the core IR classes. This is the heart of the Sea‑of‑Nodes approach, where each node represents an operation (e.g., AddNode, IfNode, LoopNode). Also include supporting “type” classes (e.g., TypeInteger, TypeTuple) that annotate the IR.
- Optimizations and Transformations: Multiple chapters showcase optimizations. Illustrate components such as:
– Peephole optimizers (e.g., IterPeeps, constant folding algorithms)
– Control Flow Graph (CFG) and SSA transformations – restructuring, dead code elimination, and global value numbering.
– Global Code Motion and Scheduling: Modules like GlobalCodeMotion and the scheduling tests are shown here.
- Backend / Code Generation:
– Evaluator: Early chapters show an interpreter (Evaluator) that “executes” the IR.
– Code Generation: In later chapters (e.g., Chapters 19 and 20), the IR is transformed via instruction selection (CodeGen) and then register allocation (RegAlloc) for target machines (with submodules for RISC-V, x86_64, ARM, etc.).
- Testing / Transpiling Module: There is also a “transpile-tests” module that demonstrates another angle by translating IR constructs into another language (Rust, for example) and verifies them using JUnit tests.

##### Relationships and Workflow
– Data flows from source programs written in Simple into the Parser.
– Parsed results are used to build the IR (nodes and control flow graphs).
– The IR proceeds through several layers of optimization (peephole, CFG transformations, SSA optimizations) and may be visualized via GraphVisualizer/IRPrinter.
– Finally, the IR is either interpreted directly, transformed into target specific intermediate code via CodeGen, and then advanced (e.g., register allocation in Chapter 20) for eventual execution.
– Alongside these processing stages, testing frameworks validate each chapter’s implementation.

##### Architectural Patterns & Design Principles
- Layered/Modular Design: The system naturally splits into frontend, middle-end (IR manipulation and optimization), and backend.
- Separation of Concerns: While the IR and node system encapsulate the program’s core, optimizations, code generation, and debugging are treated as clearly distinct modules that interact through well-defined interfaces.

##### Relevant Technologies and Artifacts
– Technologies: The project is implemented in Java, and uses Maven (noted by the multiple pom.xml files). Testing is done via the JUnit framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        S("Simple Source"):::frontend
        P("Parser"):::frontend
    end

    subgraph "IR Construction"
        IRN("IR Node System"):::ir
        IRT("IR Types"):::ir
    end

    subgraph "Optimizations"
        OP1("IterPeeps"):::opt
        OP2("Global Code Motion"):::opt
    end

    subgraph "Backend"
        E("Evaluator"):::backend
        CG("Code Generation"):::backend
        RA("RegAlloc"):::backend
    end

    subgraph "Visualization & Debugging"
        GV("GraphVisualizer"):::vis
        IRP("IRPrinter"):::vis
    end

    subgraph "Testing / Transpiling"
        T("Transpile Tests"):::test
    end

    S -->|"source"| P
    P -->|"AST"| IRN
    P -->|"AST"| IRT
    IRN -->|"optimizes"| OP1
    IRN -->|"optimizes"| OP2
    OP1 -->|"refines"| CG
    OP2 -->|"refines"| CG
    IRN -->|"execution"| E
    IRN -->|"codegen"| CG
    CG -->|"allocation"| RA
    IRN -->|"visualized"| GV
    IRN -->|"visualized"| IRP
    IRN -->|"tested"| T

    click P "https://github.com/dstogov/simple/blob/main/chapter01/src/main/java/com/seaofnodes/simple/Parser.java"
    click IRN "https://github.com/dstogov/simple/tree/main/chapter01/src/main/java/com/seaofnodes/simple/node"
    click IRT "https://github.com/dstogov/simple/blob/main/chapter02/src/main/java/com/seaofnodes/simple/type/TypeInteger.java"
    click OP1 "https://github.com/dstogov/simple/blob/main/chapter09/src/main/java/com/seaofnodes/simple/IterPeeps.java"
    click OP2 "https://github.com/dstogov/simple/blob/main/chapter11/src/main/java/com/seaofnodes/simple/GlobalCodeMotion.java"
    click E "https://github.com/dstogov/simple/blob/main/chapter08/src/main/java/com/seaofnodes/simple/GraphEvaluator.java"
    click CG "https://github.com/dstogov/simple/blob/main/chapter20/src/main/java/com/seaofnodes/simple/codegen/CodeGen.java"
    click RA "https://github.com/dstogov/simple/blob/main/chapter20/src/main/java/com/seaofnodes/simple/codegen/RegAlloc.java"
    click GV "https://github.com/dstogov/simple/blob/main/chapter02/src/main/java/com/seaofnodes/simple/GraphVisualizer.java"
    click IRP "https://github.com/dstogov/simple/blob/main/chapter07/src/main/java/com/seaofnodes/simple/IRPrinter.java"
    click T "https://github.com/dstogov/simple/tree/main/transpile-tests/src/main/java/com/seaofnodes/simple/transpile"

    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef ir fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef opt fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef backend fill:#f28c8c,stroke:#000,stroke-width:2px;
    classDef vis fill:#ffffcc,stroke:#000,stroke-width:2px;
    classDef test fill:#dda0dd,stroke:#000,stroke-width:2px;
```
