# raunak-sapariya/interpreter architecture

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

- Interactive diagram: https://gitdiagram.com/raunak-sapariya/interpreter
- Repository: https://github.com/raunak-sapariya/interpreter

## Overview

##### Main Components
- Entry Point: The main program is in app/main.py. This file is the starting point that kicks off the interpreter process.
- Scanner/Lexer: Responsible for tokenizing the input source code.
- Parser: Converts tokens into an Abstract Syntax Tree (AST).
- AST Evaluator/Interpreter: Walks the AST to execute statements.
- External Shell Scripts & Configuration:
- your_program.sh: Acts as the wrapper to run the interpreter.
- The .codecrafters directory (including compile.sh and run.sh) and codecrafters.yml: These files/configurations likely assist with testing, deployment, or submission to the CodeCrafters platform.
- Environment Configuration:
- Pipfile and Pipfile.lock: Indicate dependency management.
- Other config files (.gitignore, .gitattributes) ensure proper repository behavior.

##### Relationships and Execution Flow
- Source Code Input: Users provide the Lox program text (for example, through files or standard input).
- your_program.sh/Entry Script: This shell script calls the Python interpreter, which starts with app/main.py.
- app/main.py: Acts as controller by reading the user input and orchestrating the interpreter stages (scanning, parsing, execution).
- Data flows from the input (file or command line) to the Scanner.
- The Scanner’s output (tokens) feeds into the Parser.
- The Parser builds an AST, which is then executed/evaluated by the Interpreter component.
- External Services/Deployment: Optionally, note that .codecrafters and configuration files serve for automated testing/submission to CodeCrafters.

##### Architectural Patterns and Technologies
- Modular Design: Emphasize that the interpreter is designed in modules that eventually separate concerns (tokenization, parsing, and evaluation are distinct stages).
- Python-Based: Note the dependency on Python (version 3.12) and use of Pipfile for dependency management.
- Shell Integration: Highlight the integration of shell scripts (your_program.sh, compile.sh, run.sh) to facilitate deployment/CLI usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Interpreter Pipeline"
        A["User Input: Lox Source Code"]:::external
        B["Shell Script Wrapper (your_program.sh)"]:::shell
        C["Interpreter Entry Point (app/main.py)"]:::core
        D["Scanner/Lexer (Planned)"]:::core
        E["Parser (Planned)"]:::core
        F["AST Evaluator/Interpreter (Planned)"]:::core

        A -->|"triggers"| B
        B -->|"starts"| C
        C -->|"tokenizes"| D
        D -->|"producesTokens"| E
        E -->|"buildsAST"| F
    end

    subgraph "Deployment & Configuration"
        G["Shell Script Wrapper (your_program.sh)"]:::shell
        H["Compile Script (.codecrafters/compile.sh)"]:::shell
        I["Run Script (.codecrafters/run.sh)"]:::shell
        J["Deployment Config (codecrafters.yml)"]:::config
        K["Pipfile"]:::config
        L["Pipfile.lock"]:::config

        G -->|"executes"| H
        H -->|"runs"| I
        I -->|"configures"| J
        J -->|"definesDeps"| K
        K -->|"locksDeps"| L
    end

    click C "https://github.com/raunak-sapariya/interpreter/blob/master/app/main.py"
    click B "https://github.com/raunak-sapariya/interpreter/blob/master/your_program.sh"
    click G "https://github.com/raunak-sapariya/interpreter/blob/master/your_program.sh"
    click H "https://github.com/raunak-sapariya/interpreter/blob/master/.codecrafters/compile.sh"
    click I "https://github.com/raunak-sapariya/interpreter/blob/master/.codecrafters/run.sh"
    click J "https://github.com/raunak-sapariya/interpreter/blob/master/codecrafters.yml"
    click K "https://github.com/raunak-sapariya/interpreter/tree/master/Pipfile"
    click L "https://github.com/raunak-sapariya/interpreter/blob/master/Pipfile.lock"

    classDef external fill:#B3E5FC,stroke:#039BE5,stroke-width:2px;
    classDef shell fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef core fill:#FFCDD2,stroke:#E53935,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#43A047,stroke-width:2px;
```
