# eliaperantoni/koi architecture

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

- Interactive diagram: https://gitdiagram.com/eliaperantoni/koi
- Repository: https://github.com/eliaperantoni/koi

## Overview

##### Main Components

A. Compiler/Interpreter Pipeline Components:
- Lexer (src/lexer/)
- Parser (src/parser/)
- AST (src/ast/)
- Interpreter (src/interp/)

B. Web Interface:
- Web Frontend (web/)
- Code Snippets System (web/snippets/)

##### Component Relationships and Flow

**[Source Code Input] → [Lexer] → [Parser] → [AST] → [Interpreter] → [Program Output]**

##### Detailed Component Breakdown

Lexer Component:
- Submodules: Raw Lexer, Peek Buffer, Record System

Parser Component:
- Submodules: Command Parser, Expression Parser, Function Parser, Statement Parser
- How these components interact with the AST generation

Interpreter Component:
- Environment Management
- Function Handling
- Native Functions Support
- Command Execution System
- Value System

Web Interface:
- Connection to the core interpreter
- Snippet management system
- Firebase deployment configuration

##### Implementation Details to Highlight

- Token handling system
- Environment management
- Function call mechanism
- Native function integration
- Command execution pipeline

##### Architectural Patterns

Emphasize:
- Pipeline architecture of the compiler
- Visitor pattern for AST traversal
- Environment hierarchy
- Module system design

Remember to:
- Both compile-time and runtime components clearly separated
- Test coverage and golden test integration points
- Public APIs and interfaces
- Error handling flow

This will create a comprehensive system design that accurately represents the Koi language implementation while maintaining clarity and usefulness for development purposes.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        L1[Component]:::component
        L2[(Database)]:::database
        L3[/API/]:::api
        L4{{Runtime}}:::runtime
        L5[Web Interface]:::web
    end

    classDef component fill:#3498db,stroke:#2980b9,color:white
    classDef database fill:#e74c3c,stroke:#c0392b,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef runtime fill:#f1c40f,stroke:#f39c12,color:black
    classDef web fill:#9b59b6,stroke:#8e44ad,color:white

    subgraph "Compiler Pipeline"
        Input[Source Code Input]:::component
        
        subgraph "Lexer System"
            RawLexer[Raw Lexer]:::component
            PeekBuffer[Peek Buffer]:::component
            RecordSystem[Record System]:::component
            MainLexer[Main Lexer]:::component
        end

        subgraph "Parser System"
            CmdParser[Command Parser]:::component
            ExprParser[Expression Parser]:::component
            FuncParser[Function Parser]:::component
            StmtParser[Statement Parser]:::component
            MainParser[Main Parser]:::component
        end

        AST[Abstract Syntax Tree]:::component
    end

    subgraph "Runtime Environment"
        subgraph "Interpreter"
            EnvMgmt[Environment Management]:::runtime
            FuncHandler[Function Handler]:::runtime
            NativeFuncs[Native Functions]:::runtime
            CmdExec[Command Execution]:::runtime
            ValueSystem[Value System]:::runtime
            MethodSystem[Method System]:::runtime
        end
    end

    subgraph "Web Layer"
        Frontend[Web Frontend]:::web
        Snippets[Code Snippets]:::web
        Firebase[(Firebase)]:::database
    end

    subgraph "Testing"
        GoldenTests[Golden Tests]:::component
        ModuleTests[Module System Tests]:::component
    end

    Input --> RawLexer
    RawLexer --> PeekBuffer
    PeekBuffer --> RecordSystem
    RecordSystem --> MainLexer
    MainLexer --> MainParser
    MainParser --> |Parsing| AST
    AST --> EnvMgmt
    EnvMgmt --> FuncHandler
    FuncHandler --> NativeFuncs
    NativeFuncs --> CmdExec
    ValueSystem --> MethodSystem
    Frontend --> Firebase
    Snippets --> Firebase

    click RawLexer "https://github.com/eliaperantoni/koi/blob/master/src/lexer/raw.rs"
    click PeekBuffer "https://github.com/eliaperantoni/koi/blob/master/src/lexer/peek.rs"
    click RecordSystem "https://github.com/eliaperantoni/koi/blob/master/src/lexer/record.rs"
    click MainLexer "https://github.com/eliaperantoni/koi/blob/master/src/lexer/mod.rs"
    click CmdParser "https://github.com/eliaperantoni/koi/blob/master/src/parser/cmd.rs"
    click ExprParser "https://github.com/eliaperantoni/koi/blob/master/src/parser/expr.rs"
    click FuncParser "https://github.com/eliaperantoni/koi/blob/master/src/parser/func.rs"
    click StmtParser "https://github.com/eliaperantoni/koi/blob/master/src/parser/stmt.rs"
    click MainParser "https://github.com/eliaperantoni/koi/blob/master/src/parser/mod.rs"
    click AST "https://github.com/eliaperantoni/koi/blob/master/src/ast/mod.rs"
    click EnvMgmt "https://github.com/eliaperantoni/koi/blob/master/src/interp/env.rs"
    click FuncHandler "https://github.com/eliaperantoni/koi/blob/master/src/interp/func.rs"
    click NativeFuncs "https://github.com/eliaperantoni/koi/blob/master/src/interp/native.rs"
    click CmdExec "https://github.com/eliaperantoni/koi/blob/master/src/interp/cmd/mod.rs"
    click ValueSystem "https://github.com/eliaperantoni/koi/blob/master/src/interp/value.rs"
    click MethodSystem "https://github.com/eliaperantoni/koi/blob/master/src/interp/method.rs"
    click GoldenTests "https://github.com/eliaperantoni/koi/tree/master/src/interp/golden/"
    click ModuleTests "https://github.com/eliaperantoni/koi/tree/master/examples/module/"
    click Frontend "https://github.com/eliaperantoni/koi/tree/master/web/"
    click Snippets "https://github.com/eliaperantoni/koi/tree/master/web/snippets/"
    click Firebase "https://github.com/eliaperantoni/koi/blob/master/web/firebase.json"
```
