# liam-ilan/crumb architecture

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

- Interactive diagram: https://gitdiagram.com/liam-ilan/crumb
- Repository: https://github.com/liam-ilan/crumb

## Overview

##### Project type and purpose
- This is an interpreter for the Crumb programming language, written in C. It implements a full interpreter pipeline (lexing, parsing, AST, evaluation), a functional standard library, and a CLI. It also provides a “Loaf” template for building standalone binaries from Crumb programs.

##### File structure
- Top-level
- src/: all C modules of the interpreter
- examples/: sample .crumb programs
- loaf-template/: template.crumb used by Loaf to generate C code
- src/ modules
- main.c            – CLI entry point
- file.c/.h         – file I/O primitives
- lex.c/.h, tokens.c/.h
– lexical analysis, token definitions
- parse.c/.h, ast.c/.h
– parser, AST node representation
- eval.c/.h, run.c/.h
– AST evaluation, execution engine
- scope.c/.h        – dynamic scopes/environments
- stdlib.c/.h       – built-in functions (IO, math, list, string, events)
- generic.c/.h, list.c/.h, string.c/.h
– core data types & operations
- events.c/.h       – terminal event handling
- Configuration and build
- .gitignore
- README.md (project overview, syntax, stdlib docs)

##### Extract architectural clues from README
- Interpreter pipeline: code → tokens → AST → evaluator
- Dynamic typing, garbage­collection, dynamic scoping
- Standard library implemented as native C functions
- Loaf: uses loaf-template/template.crumb to generate a C “main.c” that wraps crumb interpreter + program entry

a. Main components
- CLI / Entry Point (main.c)
- File Loader (file module)
- Lexer (lex + tokens)
- Parser (parse)
- AST Model (ast)
- Evaluator / Runtime (eval + run)
- Scope Manager (scope)
- Standard Library (stdlib + generic + list + string + events)
- Garbage Collector (implicit within evaluator modules)
- Loaf Templating (loaf-template)
- Examples / User Code (.crumb files)
b. Relationships & Data Flow
1. User invokes “./crumb program.crumb”
2. main.c calls File Loader → source text
3. Lexer tokenizes text → token stream
4. Parser consumes token stream → AST
5. Evaluator traverses AST, consults Scope Manager → executes nodes
6. Evaluator calls into Standard Library modules for I/O, list, string operations, events
7. Results produce stdout/events, may read/write files or spawn shell
8. Loaf: template.crumb + used_files feed into template_main → generates C code → compiled with src/*.c into standalone binary
c. Architectural patterns & design principles
- Interpreter pipeline (classic compiler front-end + interpreter back-end)
- Modular decomposition by concern (lexing, parsing, AST, evaluation, stdlib)
- Dynamic scoping via central Scope Manager
- Functional core: all language constructs are functions; no side effects except I/O
- Extensibility: stdlib and loaftemplate can be extended or replaced
d. Key technologies, frameworks, libraries
- C99 (gcc, -Wall, -g, -lm)
- Valgrind, macOS leaks for debugging
- ANSI escape codes for terminal events

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Point and User Code
    EX["User Code (examples/)"]:::external
    CLI["CLI\n(src/main.c)"]:::frontend

    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        FL["File Loader\n(src/file.c/.h)"]:::frontend
        LE["Lexer\n(src/lex.c/.h + src/tokens.c/.h)"]:::frontend
        PA["Parser\n(src/parse.c/.h)"]:::frontend
    end

    %% Core Runtime Layer
    subgraph "Backend / Runtime"
        direction TB
        AST["AST Model\n(src/ast.c/.h)"]:::backend
        EV["Evaluator\n(src/eval.c/.h + src/run.c/.h)"]:::backend
        SM["Scope Manager\n(src/scope.c/.h)"]:::backend
    end

    %% Standard Library Layer
    subgraph "Standard Library" 
        direction TB
        SL_CORE["StdLib Core\n(src/stdlib.c/.h)"]:::stdlib
        SL_GEN["Generic Types\n(src/generic.c/.h)"]:::stdlib
        SL_LIST["List Module\n(src/list.c/.h)"]:::stdlib
        SL_STR["String Module\n(src/string.c/.h)"]:::stdlib
        SL_EVT["Events / Terminal I/O\n(src/events.c/.h)"]:::stdlib
    end

    %% Build Tools
    LOAF["Loaf Template\n(loaf-template/template.crumb)"]:::build

    %% Data Flow
    EX -->|".crumb file"| CLI
    CLI -->|invokes| FL
    FL -->|source text| LE
    LE -->|tokens| PA
    PA -->|"AST"| AST
    AST -->|"AST nodes"| EV
    EV -->|"executes"| SM
    EV -->|"calls"| SL_CORE
    EV -->|"calls"| SL_GEN
    EV -->|"calls"| SL_LIST
    EV -->|"calls"| SL_STR
    EV -->|"calls"| SL_EVT
    CLI -.->|optional build| LOAF

    %% Click Events
    click CLI "https://github.com/liam-ilan/crumb/blob/main/src/main.c"
    click FL "https://github.com/liam-ilan/crumb/blob/main/src/file.c"
    click FL "https://github.com/liam-ilan/crumb/blob/main/src/file.h"
    click LE "https://github.com/liam-ilan/crumb/blob/main/src/lex.c"
    click LE "https://github.com/liam-ilan/crumb/blob/main/src/lex.h"
    click LE "https://github.com/liam-ilan/crumb/blob/main/src/tokens.c"
    click LE "https://github.com/liam-ilan/crumb/blob/main/src/tokens.h"
    click PA "https://github.com/liam-ilan/crumb/blob/main/src/parse.c"
    click PA "https://github.com/liam-ilan/crumb/blob/main/src/parse.h"
    click AST "https://github.com/liam-ilan/crumb/blob/main/src/ast.c"
    click AST "https://github.com/liam-ilan/crumb/blob/main/src/ast.h"
    click EV "https://github.com/liam-ilan/crumb/blob/main/src/eval.c"
    click EV "https://github.com/liam-ilan/crumb/blob/main/src/eval.h"
    click EV "https://github.com/liam-ilan/crumb/blob/main/src/run.c"
    click EV "https://github.com/liam-ilan/crumb/blob/main/src/run.h"
    click SM "https://github.com/liam-ilan/crumb/blob/main/src/scope.c"
    click SM "https://github.com/liam-ilan/crumb/blob/main/src/scope.h"
    click SL_CORE "https://github.com/liam-ilan/crumb/blob/main/src/stdlib.c"
    click SL_CORE "https://github.com/liam-ilan/crumb/blob/main/src/stdlib.h"
    click SL_GEN "https://github.com/liam-ilan/crumb/blob/main/src/generic.c"
    click SL_GEN "https://github.com/liam-ilan/crumb/blob/main/src/generic.h"
    click SL_LIST "https://github.com/liam-ilan/crumb/blob/main/src/list.c"
    click SL_LIST "https://github.com/liam-ilan/crumb/blob/main/src/list.h"
    click SL_STR "https://github.com/liam-ilan/crumb/blob/main/src/string.c"
    click SL_STR "https://github.com/liam-ilan/crumb/blob/main/src/string.h"
    click SL_EVT "https://github.com/liam-ilan/crumb/blob/main/src/events.c"
    click SL_EVT "https://github.com/liam-ilan/crumb/blob/main/src/events.h"
    click LOAF "https://github.com/liam-ilan/crumb/blob/main/loaf-template/template.crumb"
    click EX "https://github.com/liam-ilan/crumb/tree/main/examples/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000;
    classDef backend fill:#90EE90,stroke:#000;
    classDef stdlib fill:#FFA500,stroke:#000;
    classDef build fill:#D3D3D3,stroke-dasharray: 5 5;
    classDef external fill:#ffffff,stroke:#000,stroke-dasharray: 2 2;
```
