Ellex Architecture Models

Ellex Architecture Models

Welcome to the architecture reference for Ellex, a natural language programming environment designed for young learners. This page provides an overview of the system’s multi-language architecture, key components, and design principles that power Ellex.

System Overview

Ellex combines the safety and fault-tolerance of the BEAM VM with intuitive natural language syntax, targeting young learners (ages 6-16) while providing a pathway to full Elixir development. Its hybrid architecture leverages Rust for performance-critical components and Elixir for fault-tolerant web interfaces and supervision.

Multi-Language Architecture

Ellex is built using a combination of Rust and Elixir to balance performance, safety, and interactivity:

Rust Components

Located in the crates/ directory, these components handle core functionality with high performance:

• ellex_core: Core runtime, safety monitoring, turtle graphics, and execution engine.
• ellex_parser: Natural language syntax parser using libraries like Pest or Nom.
• ellex_cli: Command-line interface and REPL for interactive coding.
• ellex_repl: Interactive shell built with rustyline and crossterm for user input handling.
• ellex_web: Web server for the browser-based playground, based on the Axum framework.
• ellex_ai: AI assistance and pattern recognition to support learning.

Elixir Backend

Located in the elixir_backend/ directory, this provides a robust web interface and fault tolerance:

• Phoenix LiveView Application: Real-time web interface for interactive coding experiences.
• BEAM VM Integration: Ensures fault-tolerance and supervision for reliable operation.
• Rustler NIFs: Bridges Rust and Elixir components for seamless communication.

Key Design Principles

The architecture of Ellex is guided by the following principles:

• Safety First: Built-in execution limits, timeouts, and memory constraints to protect young users from crashes or infinite loops. Default limits in EllexConfig include a 5-second execution timeout, 64MB memory limit, 100 max recursion depth, and 10,000 max loop iterations.
• Modal Programming: Supports different interaction modes (@speak, @listen, @think, @build) to help structure the learning process.
• Natural Language Syntax: Commands like tell "Hello!" instead of print("Hello") to make coding intuitive.
• Progressive Learning: Starts with natural language and evolves into full Elixir syntax for advanced users.
• Real-time Feedback: Immediate execution results and turtle graphics visualization to keep learners engaged.

Visualizing Architecture with D2 Diagrams

To help understand the relationships between Ellex’s components, we’ve provided a D2 diagram below. This diagram illustrates how the Rust and Elixir components interact to form the complete Ellex environment.

D2 Diagram for Ellex Architecture

# Ellex System Architecture
direction: right

# Main Components
EllexSystem -> RustComponents: Performance Core
EllexSystem -> ElixirBackend: Fault-Tolerant Web

# Rust Components (crates/)
RustComponents -> ellex_core: Runtime & Safety
RustComponents -> ellex_parser: Syntax Parsing
RustComponents -> ellex_cli: CLI & REPL
RustComponents -> ellex_repl: Interactive Shell
RustComponents -> ellex_web: Web Playground
RustComponents -> ellex_ai: AI Assistance
ellex_core -> ellex_parser: Uses for parsing
ellex_cli -> ellex_core: Executes code
ellex_repl -> ellex_core: Executes interactively
ellex_web -> ellex_core: Serves runtime
ellex_ai -> ellex_core: Enhances learning

# Elixir Backend (elixir_backend/)
ElixirBackend -> PhoenixLiveView: Real-time UI
ElixirBackend -> BEAM_VM: Supervision
ElixirBackend -> Rustler_NIFs: Rust Bridge
PhoenixLiveView -> BEAM_VM: Runs on
Rustler_NIFs -> RustComponents: Communicates with

# Interaction Flow
User -> ellex_cli: Codes via terminal
User -> ellex_repl: Interacts in REPL
User -> ellex_web: Uses browser playground
User -> PhoenixLiveView: Accesses web UI
ellex_web -> PhoenixLiveView: Integrates (optional)

Note: The D2 diagram below is automatically rendered as an image during the build process. If you’re viewing this documentation locally, ensure you run npm run build or npm run render-diagrams to generate the images.

Core Configuration Details

Ellex is designed with safety and learning in mind. The default execution limits in EllexConfig are:

• Execution Timeout: 5 seconds to prevent long-running processes.
• Memory Limit: 64MB to avoid excessive resource usage.
• Max Recursion Depth: 100 levels to prevent stack overflows.
• Max Loop Iterations: 10,000 to stop infinite loops.
• Turtle Graphics: Enabled by default for visual feedback.
• AI Assistance: Enabled by default to support learning.

These settings ensure a safe coding environment for beginners while allowing customization for advanced users or educators.

Error Handling

Ellex provides kid-friendly error messages wrapped in the EllexError enum. These messages include emojis and helpful suggestions to guide young coders in fixing their code, reducing frustration and encouraging persistence.

Contributing to Architecture Development

If you’re interested in contributing to Ellex’s architecture, whether by enhancing the Rust components, Elixir backend, or bridging mechanisms, visit our GitHub repository for details on the project roadmap and contribution guidelines. Your expertise can help improve performance, add features, or refine the learning experience.

Check back for updates as we continue to evolve the architecture of Ellex to support natural language programming and educational goals!