# your-moon/cecile architecture

> Architecture diagram of the GitHub repository your-moon/cecile, 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/your-moon/cecile
- Repository: https://github.com/your-moon/cecile

## Overview

Based on our review of the file tree and README, the Cecile project is an implementation of a small programming language written in Rust. Its purpose is to serve both as a learning tool for compiler design and an interpreted language with a bytecode compiler and garbage-collected runtime. In addition, there is work in progress to support an online playground, which appears to be built using Next.js and integrates a Rust-compiled WASM module.

##### Main components
- Bytecode Compiler: Modules in “src/vm”, including src/vm/compiler.rs and src/vm/optimizer.rs, work on taking the AST and translating it into bytecode. This is also where any optimizations occur.
- Virtual Machine (VM): Located in “src/vm”, components such as chunk.rs, op.rs, and value.rs represent the runtime execution engine. This VM processes the compiled bytecode, manages execution control flow, and handles errors.
- Memory Management / Allocator: The “src/allocator” directory shows that dynamic memory allocation is managed explicitly, likely to support garbage collection in the runtime.
- REPL and CLI: With the “src/repl” and “src/cli” directories and the main entry point at “src/main.rs”, the project provides both an interactive REPL mode and a command-line interface for running Cecile code.
- Resources & Example Code: The “res” directory contains many .ce files that serve as sample programs or tests for different language features.
- Online Playground (WASM & Web Frontend): Under “playground/cecile_playground” there is a Next.js project, and within it a “rust/cecile_wasm” submodule. This indicates an experimental web playground that likely uses a WASM-compiled version of some or all of the language’s core functionality.

##### Relationships and interactions
- Source Input → Lexical Analysis → Parsing: The user code (or file) is fed into the lexer (src/cc_lexer) and then into the parser (src/cc_parser) where the AST is generated.
- AST → Compiler & Optimizer: The AST is processed by the compiler (src/vm/compiler.rs) and optionally optimized (src/vm/optimizer.rs), generating bytecode.
- Bytecode → Virtual Machine Execution: The bytecode is then executed by the VM, which interacts with memory management (src/allocator) and handles runtime functions.
- CLI/REPL Interface: Both the command-line interface and REPL act as conduits that capture user input, feed it to the compiler, and display output or errors.
- Online Playground: The web frontend (React/Next.js) communicates with the WASM module (compiled from Rust code in playground/cecile_playground/rust/cecile_wasm) to enable an interactive in-browser coding environment.

##### Architectural patterns/design principles
- Layered Architecture: The project is obviously layered – starting with source input, then the language’s frontend (lexer and parser), its compilation (compiler and optimizer), and finally its execution (virtual machine and runtime).
- Separation of Concerns: Components such as CLI, REPL, compiler, VM, and allocator are clearly separated into different modules and directories.
- Modularity and Extensibility: With a separate playground and tests, the project is set up to be extended (e.g., adding a module system, standard library, or self-hosting capabilities).

##### Technologies and Frameworks
- Rust: The entire project is built in Rust (as seen by Cargo.toml, build.rs, and directory structure).
- LALRPOP: Used for parser generation (src/cc_parser/grammar.lalrpop).
- Next.js & WASM: The playground component uses Next.js for the frontend and integrates a Rust-compiled WASM module (cecile_wasm) for language execution in the browser.
- GitHub Actions: The .github/workflows (e.g., rust.yml) indicate automated CI/CD pipelines using Rust.

##### Instructing the Principal Software Engineer
- Detail each module as a sub-component within the appropriate layer. For example, within “Language Processing,” denote “Lexer” (src/cc_lexer), “Parser” (src/cc_parser), and “AST/Bytecode Compiler” (src/vm/compiler, src/vm/optimizer).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        UI["CLI & REPL"]:::interface
    end

    subgraph "Language Processing Layer"
        LEX["Lexer (src/cc_lexer)"]:::compiler
        PAR["Parser (src/cc_parser)"]:::compiler
    end

    subgraph "Compilation Layer"
        COMP["Bytecode Compiler (src/vm/compiler.rs)"]:::compiler
    end

    subgraph "Execution Engine Layer"
        VM["Virtual Machine (src/vm)"]:::runtime
        ALLOC["Memory Management (src/allocator)"]:::runtime
    end

    subgraph "Resources & Examples"
        RES["Resources (res)"]:::resources
    end

    subgraph "Online Playground"
        WF["Web Frontend (Next.js)"]:::playground
        WASM["WASM Module (cecile_wasm)"]:::playground
    end

    UI -->|"input"| LEX
    LEX -->|"tokens"| PAR
    PAR -->|"AST"| COMP
    COMP -->|"bytecode"| VM
    VM -->|"calls"| ALLOC
    WF -->|"calls"| WASM

    %% Click Events
    click UI "https://github.com/your-moon/cecile/blob/master/src/main.rs"
    click LEX "https://github.com/your-moon/cecile/tree/master/src/cc_lexer"
    click PAR "https://github.com/your-moon/cecile/tree/master/src/cc_parser"
    click COMP "https://github.com/your-moon/cecile/blob/master/src/vm/compiler.rs"
    click VM "https://github.com/your-moon/cecile/blob/master/src/vm/chunk.rs"
    click ALLOC "https://github.com/your-moon/cecile/tree/master/src/allocator"
    click RES "https://github.com/your-moon/cecile/tree/master/res"
    click WF "https://github.com/your-moon/cecile/tree/master/playground/cecile_playground"
    click WASM "https://github.com/your-moon/cecile/tree/master/playground/cecile_playground/rust/cecile_wasm"

    %% Styles
    classDef interface fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef compiler fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef runtime fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef resources fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef playground fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
