# delihiros/futhon architecture

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

- Interactive diagram: https://gitdiagram.com/delihiros/futhon
- Repository: https://github.com/delihiros/futhon

## Overview

Based on an analysis of the file tree and README, Futhon is a programming language geared toward Natural Language Processing and Machine Learning. Its design uses a classical interpreter architecture with a few clear components:

##### Project Overview
- Futhon is not a full-stack application but an interpreter/compiler for a domain-specific language.
- It includes a lexer/parser (with a grammar file “futhon.g” and a dedicated “futhon_parser.py”), an evaluator, an environment management layer, and support for language primitives and dynamic operations.
- The provided examples and tests illustrate sample usage and confirm that the interpreter is intended to be used interactively via a REPL, as highlighted by “src/repl.py.”

##### Key Components
a. Front-End (Parsing and Interpretation):
- futhon.g: The grammar definition for the language.
- futhon_parser.py: The module handling the parsing logic.
- These components work together to translate language source code (written in Futhon syntax) into an abstract representation.

b. Core Interpreter:
- evaluator.py: The core evaluation engine executing the parsed expressions.
- environment.py: Deals with the symbol table and scope handling.
- primitives.py and datatypes.py: Define the language's built-in data types and operations.
- dynamic.py: Likely handles dynamic aspects of the language (such as runtime behavior modifications or dynamic typing).

c. User Interface:
- repl.py: Provides the interactive read-evaluate-print-loop, which accepts user input, processes it through the parser and evaluator, and outputs results.

d. External and Supporting Infrastructure:
- examples directory: Contains sample programs (e.g., chainer_tutorial.fu) showcasing how Futhon can interface with ML libraries like Chainer and NumPy.
- Configuration and Build Files (e.g., setup.py, requirements.txt, .travis.yml): Indicate testing, continuous integration, and dependency management.
- Test folder: Contains unit tests that validate the core interpreter, parser, and evaluation logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        repl["src/repl.py"]
    end

    %% Front-End (Parsing and Interpretation) Layer
    subgraph "Front-End"
        grammar["src/futhon.g"]
        parser["src/futhon_parser.py"]
    end

    %% Core Interpreter Layer
    subgraph "Core Interpreter"
        evaluator["src/evaluator.py"]
        env["src/environment.py"]
        prim["src/primitives.py"]
        datatypes["src/datatypes.py"]
        dynamic["src/dynamic.py"]
    end

    %% External Integration (e.g., ML Libraries)
    external["External Libraries (Chainer,NumPy)"]

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        examples["examples"]
        resources["resources"]
        config["Configuration_Files"]
        tests["Tests"]
    end

    %% Connections between layers
    repl -->|"sends_code"| parser
    grammar -->|"defines_grammar"| parser
    parser -->|"outputs_AST"| evaluator
    evaluator -->|"lookup_scope"| env
    evaluator -->|"uses_primitives"| prim
    evaluator -->|"handles_datatypes"| datatypes
    evaluator -->|"manages_dynamic_ops"| dynamic
    prim -->|"calls_external_libs"| external
    tests -->|"validate"| evaluator

    %% Classes for styling
    class repl ui
    class grammar,parser frontend
    class evaluator,env,prim,datatypes,dynamic core
    class examples,resources,config,tests support
    class external external

    %% Style definitions
    classDef ui fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef frontend fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef support fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px;

    %% Click Events
    click repl "https://github.com/delihiros/futhon/blob/master/src/repl.py"
    click grammar "https://github.com/delihiros/futhon/blob/master/src/futhon.g"
    click parser "https://github.com/delihiros/futhon/blob/master/src/futhon_parser.py"
    click evaluator "https://github.com/delihiros/futhon/blob/master/src/evaluator.py"
    click env "https://github.com/delihiros/futhon/blob/master/src/environment.py"
    click prim "https://github.com/delihiros/futhon/blob/master/src/primitives.py"
    click datatypes "https://github.com/delihiros/futhon/blob/master/src/datatypes.py"
    click dynamic "https://github.com/delihiros/futhon/blob/master/src/dynamic.py"
    click examples "https://github.com/delihiros/futhon/tree/master/examples"
    click resources "https://github.com/delihiros/futhon/tree/master/resources"
    click config "https://github.com/delihiros/futhon/blob/master/setup.py"
    click tests "https://github.com/delihiros/futhon/blob/master/test/evaluator_test.py"
```
