# teal-language/tl architecture

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

- Interactive diagram: https://gitdiagram.com/teal-language/tl
- Repository: https://github.com/teal-language/tl

## Overview

##### Main Project Components
- Compiler Engine: This is the heart of the project and is primarily contained in the single-file core (tl.lua) and its Teal counterpart (tl.tl). It encapsulates the logic that reads, parses, type-checks, and compiles Teal code.
- Command-line Interface (CLI): Teal supports subcommands (such as run, check, gen, warnings) that enable users to invoke the compiler in different modes. This layer also deals with reading command-line arguments, configuration files (tlconfig.lua), and applying compiler options.
- Loader and Integration Module: The compiler supports on-the-fly Teal file compilation with the package loader (via tl.loader()). Represent this as a dedicated component that integrates with Lua’s require() mechanism.
- Build Tool Integration: Although not part of the core code, the README suggests integration with Cyan (a separate build tool designed for Teal). This external dependency layer can be noted as an optional tool that interacts with the compiler.
- Testing & Specification Framework: With a rich “spec” directory subdivided into various subdirectories (api, cli, lang, etc.), this part of the project ensures that each language component (lexer, parser, code generation, inference, subtyping, etc.) is thoroughly tested. It documents expected behavior for all compiler phases.

##### Detail of the Compiler Engine (Core Pipeline)
- Input: Teal source files (.tl) provided by the user.
- Lexical Analysis: Represent the lexer component (see spec/lang/lexer and related tests). It breaks down the input source code into tokens.
- Parsing: Show the parser module (spec/lang/parser) that converts tokens into an Abstract Syntax Tree (AST).
- Macro Expansion & Code Generation: Include components for macro expansion (spec/lang/macroexp) and code generation (spec/lang/code_gen), where the compiler converts the typed AST into plain Lua code (removing type annotations).
- Error Reporting: There is a dedicated element for error reporting (spec/lang/error_reporting), ensuring that syntax and type errors are well-captured.

##### Communication / Data Flow Among Components
- For the testing modules in the “spec” directory, indicate that these validate interactions between each of the components.

##### Architectural and Design Patterns
- The design is modular. Even though the core compiler begins as a single file, the extensive spec directory reflects a clear separation of concerns (e.g., separate modules for lexer, parser, and type system).
- The compiler’s integration as a loader for Lua represents an adapter-like pattern that plugs into Lua’s require mechanism.
- The use of subcommands in the CLI suggests a Command pattern for handling different user inputs.
- The testing framework is organized to mirror the compiler internals, indicating a design that values high-testability and modularity.

## Diagram (Mermaid)

```mermaid
graph TD
    Source("Teal Source (.tl)"):::input
    CLI("Command-line Interface"):::cli
    Config("Configuration (tlconfig.lua)"):::cli
    Loader("Loader & Integration"):::loader

    subgraph "Compiler Engine"
        LEX("Lexical Analysis"):::pipeline
        PAR("Parsing"):::pipeline
        TC("Type Analysis & Inference"):::pipeline
        ME("Macro Expansion"):::pipeline
        CG("Code Generation"):::pipeline
        ER("Error Reporting"):::pipeline
        CE_Lua("Compiler Core"):::core
        CE_Tl("Compiler Core"):::core
    end

    Output("Lua Output/Execution"):::output
    Cyan("Build Tool: Cyan"):::external
    Testing("Testing Framework"):::testing
    Docs("Docs & Community"):::docs

    Source --> CLI
    CLI --> Config
    Config --> CLI
    CLI --> Loader
    Loader --> LEX
    LEX --> PAR
    PAR --> TC
    TC --> ME
    ME --> CG
    CG --> ER
    ER --> CE_Lua
    CE_Lua --> CE_Tl
    CE_Tl --> Output
    CLI --- Cyan
    Testing --- LEX
    Testing --- PAR
    Testing --- TC
    Testing --- ME
    Testing --- CG
    Testing --- ER
    Docs --- CLI

    click CLI "https://github.com/teal-language/tl/tree/master/spec/cli"
    click Config "https://github.com/teal-language/tl/blob/master/docs/examples/files/tlconfig.lua"
    click Loader "https://github.com/teal-language/tl/blob/master/spec/lang/loader/loader_spec.lua"
    click CE_Lua "https://github.com/teal-language/tl/blob/master/tl.lua"
    click CE_Tl "https://github.com/teal-language/tl/blob/master/tl.tl"
    click Testing "https://github.com/teal-language/tl/tree/master/spec/"
    click Docs "https://github.com/teal-language/tl/tree/master/docs/"

    classDef input fill:#e0f7fa,stroke:#006064,stroke-width:2px;
    classDef cli fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px;
    classDef loader fill:#fff9c4,stroke:#f9a825,stroke-width:2px;
    classDef pipeline fill:#bbdefb,stroke:#0d47a1,stroke-width:2px;
    classDef core fill:#ffe082,stroke:#ff6f00,stroke-width:2px;
    classDef output fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
    classDef external fill:#ffccbc,stroke:#bf360c,stroke-width:2px;
    classDef testing fill:#f8bbd0,stroke:#880e4f,stroke-width:2px;
    classDef docs fill:#d7ccc8,stroke:#4e342e,stroke-width:2px;
```
