# pfalcon/scratchablock architecture

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

- Interactive diagram: https://gitdiagram.com/pfalcon/scratchablock
- Repository: https://github.com/pfalcon/scratchablock

## Overview

##### Main Components

a. Input Processing Layer:
- PseudoC IR input handling
- Decoupling from specific architectures
- Parser components (parser.py)

b. Core Analysis Engine:
- Graph processing components (graph.py)
- Data flow analysis system (dataflow.py)
- Control flow analysis (xform_cfg.py)
- SSA transformation system (xform_ssa.py)

c. Transformation Pipeline:
- Expression transformations (xform_expr.py)
- Basic block transformations (xform_bblock.py)
- Interprocedural analysis (xform_inter.py)

d. Output Generation:
- Multiple output formats (PseudoC, C, dot, YAML)
- Visualization components (dot.py)

**[Input Layer]**

- v
**[Core Analysis Engine] <-> [Analysis Components]**
- Graph Analysis
- Data Flow Analysis
- Control Flow Analysis
- v
**[Transformation Pipeline] <-> [Transformation Passes]**
- Expression Transforms
- Block Transforms
- SSA Transforms
- v
**[Output Generation]**

##### Key Elements to Highlight

- Blue: Input processing components
- Green: Analysis components
- Yellow: Transformation components
- Purple: Output generation components

##### Implementation Details

a. Core Components:
- Relationship between core.py and other modules
- How xform_*.py modules interact

b. Testing Infrastructure:
- Test framework integration
- How verification is performed

##### Documentation

- Component responsibilities
- Key file relationships

##### Additional Notes

- Human-readable IR aspect
- How the system maintains debugging capabilities
- Where architecture-specific components could be added
- Areas for potential future expansion

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef input fill:#a8d1f0,stroke:#000
    classDef core fill:#90ee90,stroke:#000
    classDef transform fill:#ffeb99,stroke:#000
    classDef output fill:#dda0dd,stroke:#000
    classDef analysis fill:#ffa07a,stroke:#000

    %% Input Processing Layer
    subgraph InputLayer
        Parser["Parser"]
        ArchSupport["Architecture Support"]
        ArchUtils["Architecture Utilities"]
    end

    %% Core Analysis Engine
    subgraph CoreEngine
        Core["Core Engine"]
        GraphProc["Graph Processing"]
        DataFlow["Data Flow Analysis"]
        CFAnalysis["Control Flow Analysis"]
        SSATransform["SSA Transformation"]
    end

    %% Analysis Components
    subgraph AnalysisComponents
        DomAnalysis["Dominance Analysis"]
        DCE["Dead Code Elimination"]
        InterDataFlow["Inter-procedural Analysis"]
        CFGUtils["Graph Utilities"]
    end

    %% Transformation Pipeline
    subgraph TransformPipeline
        ExprTransform["Expression Transforms"]
        BBlockTransform["Basic Block Transforms"]
        InterProcAnalysis["Interprocedural Analysis"]
        ExprInfer["Expression Inference"]
        ExprBasic["Basic Expression Transforms"]
    end

    %% Output Generation
    subgraph OutputGen
        DotOutput["Dot Graph Output"]
        CPrinter["C Code Printer"]
        ASMPrinter["Assembly Printer"]
    end

    %% Relationships
    InputLayer --> CoreEngine
    CoreEngine <--> AnalysisComponents
    CoreEngine --> TransformPipeline
    TransformPipeline --> OutputGen

    %% Component Classes
    class Parser,ArchSupport,ArchUtils input
    class Core,GraphProc,DataFlow,CFAnalysis,SSATransform core
    class ExprTransform,BBlockTransform,InterProcAnalysis,ExprInfer,ExprBasic transform
    class DotOutput,CPrinter,ASMPrinter output
    class DomAnalysis,DCE,InterDataFlow,CFGUtils analysis

    %% Click Events
    click Parser "https://github.com/pfalcon/ScratchABlock/blob/master/parser.py"
    click ArchSupport "https://github.com/pfalcon/ScratchABlock/blob/master/arch.py"
    click ArchUtils "https://github.com/pfalcon/ScratchABlock/blob/master/archutils.py"
    click Core "https://github.com/pfalcon/ScratchABlock/blob/master/core.py"
    click GraphProc "https://github.com/pfalcon/ScratchABlock/blob/master/graph.py"
    click DataFlow "https://github.com/pfalcon/ScratchABlock/blob/master/dataflow.py"
    click CFAnalysis "https://github.com/pfalcon/ScratchABlock/blob/master/xform_cfg.py"
    click SSATransform "https://github.com/pfalcon/ScratchABlock/blob/master/xform_ssa.py"
    click ExprTransform "https://github.com/pfalcon/ScratchABlock/blob/master/xform_expr.py"
    click BBlockTransform "https://github.com/pfalcon/ScratchABlock/blob/master/xform_bblock.py"
    click InterProcAnalysis "https://github.com/pfalcon/ScratchABlock/blob/master/xform_inter.py"
    click ExprInfer "https://github.com/pfalcon/ScratchABlock/blob/master/xform_expr_infer.py"
    click ExprBasic "https://github.com/pfalcon/ScratchABlock/blob/master/xform_expr_basic.py"
    click DotOutput "https://github.com/pfalcon/ScratchABlock/blob/master/dot.py"
    click CPrinter "https://github.com/pfalcon/ScratchABlock/blob/master/cprinter.py"
    click ASMPrinter "https://github.com/pfalcon/ScratchABlock/blob/master/asmprinter.py"
    click DomAnalysis "https://github.com/pfalcon/ScratchABlock/blob/master/dom.py"
    click DCE "https://github.com/pfalcon/ScratchABlock/blob/master/dce.py"
    click InterDataFlow "https://github.com/pfalcon/ScratchABlock/blob/master/inter_dataflow.py"
    click CFGUtils "https://github.com/pfalcon/ScratchABlock/blob/master/cfgutils.py"

    %% Legend
    subgraph Legend
        L1["Input Processing"]:::input
        L2["Core Analysis"]:::core
        L3["Transformations"]:::transform
        L4["Output Generation"]:::output
        L5["Analysis Components"]:::analysis
    end
```
