# moise7000/mini-python-compiler architecture

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

- Interactive diagram: https://gitdiagram.com/moise7000/mini-python-compiler
- Repository: https://github.com/moise7000/mini-python-compiler

## Overview

##### Project Type and Purpose
- This is a compiler tool (“Pytator Compiler”) for a Mini-Python dialect.
- Core functionality:
- Lexical analysis → token stream
- Syntactic analysis → syntax tree
- AST generation (exported in DOT format)
- (Future: ASM code generation)
- Two “front ends”:
- CLI Java application (java -jar pytator.jar …)
- Web interface (Flask app packaging the JAR via Docker)

##### High-Level Components
a. Frontends
- Java CLI runner (Main.java)
- Python Flask web UI (utils/web_interface/app.py + templates)
b. Compiler Core (all under src/)
1. Lexical Analyzer (src/analysis/lexical)
2. Syntax Analyzer (src/analysis/syntaxic)
3. Token definitions (src/analysis/tokens/…)
4. Common utilities & symbol table (src/analysis/common)
5. AST representation & DOT conversion
c. Resources
- Grammar definitions (resources/grammaires)
- Example and test source files (resources/fichier_tests, examples/)
d. Post-processing
- Graphviz → SVG converter (utils/graphviz_code_to_svg.py)
e. Infrastructure
- Docker compose file (utils/web_interface/compose.yaml + Dockerfile)
- JAR packaging metadata (resources/META-INF/MANIFEST.MF)
f. Tests
- JUnit tests (tests/analysis/…)

##### Data Flow and Interactions
- Input Stage
- User provides a .py file via CLI or Web UI
- Grammar files loaded at startup by the Syntax Analyzer
- Processing Stage (Java runtime)
1. Main.java parses command-line flags
2. LexicalAnalyzer reads characters → TokenManager → Token stream
3. SyntaxAnalyzer consumes tokens + grammar → parses → builds AST (AbstractSyntaxTree)
4. DotToAssertConverter (and PrettyPrinter) serializes AST to DOT format
- Output Stage
- DOT file generated to disk or returned via HTTP
- Graphviz converter (Python) reads DOT → outputs SVG/PNG
- Web UI serves front-end HTML that displays SVG

##### Architectural Patterns & Principles
- Pipeline pattern: clear separation of lexer, parser, AST builder
- Modular token definitions via subpackages (delimiters, operators, keywords)
- Strategy pattern for token helpers (identhelpers)
- Layered design: CLI/Web UI layer → Compiler core → Post-processing → Presentation
- Dependency injection of grammar files

##### Final Checklist
- [ ] All core modules are represented
- [ ] Data flows are directional and annotated
- [ ] External dependencies (Docker, Graphviz) are included
- [ ] Labels are clear and components are named exactly as in the codebase

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(["User"]):::external

    subgraph "UI Layer"
        CLI["CLI Java Runner"]:::java
        WEB["Web Interface (Flask)"]:::python
        INDEX["index.html (Template)"]:::datastore
    end

    User --> CLI
    User --> WEB
    WEB -->|"spawns jar"| CLI
    WEB -->|"serves HTML"| INDEX

    CLI --> LA

    LA["Lexical Analyzer"]:::java
    TT["Token Definitions"]:::java
    CU["Common Utilities & Symbol Table"]:::java
    SA["Syntax Analyzer"]:::java
    ASTAST["AbstractSyntaxTree"]:::java
    ASTST["SyntaxTree"]:::java
    DOTCONV["DotToAssertConverter"]:::java
    PP["PrettyPrinter"]:::java
    DOT["AST.dot"]:::datastore

    subgraph "Compiler Core (Java 17)"
        TT --> LA
        LA --> SA
        SA --> ASTAST
        SA --> ASTST
        ASTAST --> DOTCONV
        ASTST --> PP
        DOTCONV --> DOT
        PP --> DOT
        SA --> GRAM
    end

    DOT --> GraphConv
    GraphConv["Graphviz Converter"]:::external --> SVG["SVG/PNG"]:::datastore

    subgraph "Resources"
        GRAM["Grammar Definitions"]:::datastore
        EX["Example Source Files"]:::datastore
        TESTF["Test Source Files"]:::datastore
        MAN["JAR Packaging Metadata"]:::datastore
    end

    subgraph "Infrastructure"
        DOCKER["docker-compose"]:::external
        Dockfile["Dockerfile"]:::external
    end

    TESTS["JUnit Tests"]:::external

    TESTS --> LA
    TESTS --> SA

    click CLI "https://github.com/moise7000/mini-python-compiler/blob/main/src/Main.java"
    click WEB "https://github.com/moise7000/mini-python-compiler/blob/main/utils/web_interface/app.py"
    click INDEX "https://github.com/moise7000/mini-python-compiler/blob/main/utils/web_interface/templates/index.html"
    click LA "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/lexical/LexicalAnalyzer.java"
    click TT "https://github.com/moise7000/mini-python-compiler/tree/main/src/analysis/tokens"
    click CU "https://github.com/moise7000/mini-python-compiler/tree/main/src/analysis/common"
    click SA "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/syntaxic/SyntaxAnalyzer.java"
    click ASTAST "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/syntaxic/AbstractSyntaxTree.java"
    click ASTST "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/syntaxic/SyntaxTree.java"
    click DOTCONV "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/syntaxic/DotToAssertConverter.java"
    click PP "https://github.com/moise7000/mini-python-compiler/blob/main/src/analysis/syntaxic/PrettyPrinter.java"
    click GRAM "https://github.com/moise7000/mini-python-compiler/tree/main/resources/grammaires"
    click EX "https://github.com/moise7000/mini-python-compiler/tree/main/examples"
    click TESTF "https://github.com/moise7000/mini-python-compiler/tree/main/resources/fichier_tests"
    click MAN "https://github.com/moise7000/mini-python-compiler/blob/main/resources/META-INF/MANIFEST.MF"
    click GraphConv "https://github.com/moise7000/mini-python-compiler/blob/main/utils/graphviz_code_to_svg.py"
    click DOCKER "https://github.com/moise7000/mini-python-compiler/blob/main/utils/web_interface/compose.yaml"
    click Dockfile "https://github.com/moise7000/mini-python-compiler/tree/main/utils/web_interface/Dockerfile"
    click TESTS "https://github.com/moise7000/mini-python-compiler/tree/main/tests/analysis"

    classDef java fill:#ADD8E6,stroke:#000
    classDef python fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef datastore fill:#E6E6FA,stroke:#000
```
