# klebert-engineering/simfil architecture

> Architecture diagram of the GitHub repository klebert-engineering/simfil, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/klebert-engineering/simfil
- Repository: https://github.com/klebert-engineering/simfil

## Overview

##### Main Components

a) Core Library Components:
- Query Engine
- Parser
- Interpreter
- Expression Compiler
- Memory Management
- Arena/Pool System
- String Pool
- Model System
- Base Model Interface
- JSON Model Implementation
- Type System
- Function Registry
- Environment Handler

b) Supporting Components:
- REPL Interface
- Examples Integration
- Test Framework

**┌─ Application Layer ─────┐**
- REPL                 │
- Example Applications │
- ┘
- ↓
**┌─ Core Library Layer ────┐**
- ┌─ Query Engine ──┐    │
- Parser       │    │
- Compiler     │    │
- Interpreter  │    │
- ┘    │
- ┌─ Data Layer ────┐   │
- Model System │   │
- String Pool  │   │
- Arena       │    │
- ┘    │
- ┘
- ↓
**┌─ External Dependencies ─┐**
- nlohmann/json       │
- bitsery             │
- sfl-library         │
- fmt                 │
- ┘

##### Specific Implementation Details

- The separation between the query engine and data model
- The pluggable nature of the model system (showing JSON as an example implementation)
- The memory management system's central role
- The environment's role in managing the execution context

##### Key Architectural Patterns to Highlight

- Plugin Architecture: For model implementations
- Pool Pattern: For memory management
- Interpreter Pattern: For query execution
- Builder Pattern: For query compilation

##### Implementation Notes

- The separation of interface (include/simfil) and implementation (src)
- The model subsystem organization
- The test infrastructure
- The build system integration (CMake/Conan)

Remember to:
- Use consistent notation
- Version information
- Document key design decisions

- Simplicity
- Speed
- Memory efficiency

This system design should provide a clear understanding of how Simfil works as both a library and a query language implementation, while maintaining the balance between detail and abstraction.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Application
        REPL["REPL Interface"]
        Examples["Example Applications"]
    end

    subgraph Core["Core Library Layer"]
        subgraph QueryEngine["Query Engine"]
            Parser["Parser"]
            TokenSystem["Token System"]
            ExprSystem["Expression System"]
            Interpreter["Interpreter"]
        end

        subgraph Memory["Memory Management"]
            Arena["Arena System"]
            StringPool["String Pool"]
        end

        subgraph ModelSystem["Model System"]
            BaseModel["Base Model Interface"]
            JSONModel["JSON Implementation"]
            NodeSystem["Node System"]
        end

        subgraph Types["Type System"]
            CoreTypes["Core Types"]
            Values["Values"]
            TypeMeta["Type Metadata"]
        end

        FuncRegistry["Function Registry"]
        Env["Environment Handler"]
        ExceptionHandler["Exception Handler"]
        PublicAPI["Public API"]
    end

    subgraph External["External Dependencies"]
        JSON["nlohmann/json"]
        Bitsery["bitsery"]
        SFL["sfl-library"]
        FMT["fmt"]
    end

    %% Relationships
    REPL --> PublicAPI
    Examples --> PublicAPI

    PublicAPI --> QueryEngine
    PublicAPI --> ModelSystem
    PublicAPI --> Env

    Parser --> TokenSystem
    Parser --> ExprSystem
    Interpreter --> ExprSystem

    ModelSystem --> Memory
    BaseModel --> NodeSystem
    JSONModel --> BaseModel
    JSONModel --> JSON

    Env --> FuncRegistry
    Env --> ExceptionHandler
    Env --> Types

    %% Click events
    click Parser "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/parser.h"
    click TokenSystem "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/token.h"
    click ExprSystem "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/expression.h"
    click Arena "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/model/arena.h"
    click StringPool "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/model/string-pool.h"
    click BaseModel "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/model/model.h"
    click JSONModel "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/model/json.h"
    click NodeSystem "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/model/nodes.h"
    click CoreTypes "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/types.h"
    click Values "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/value.h"
    click TypeMeta "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/typed-meta-type.h"
    click FuncRegistry "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/function.h"
    click Env "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/environment.h"
    click ExceptionHandler "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/exception-handler.h"
    click REPL "https://github.com/klebert-engineering/simfil/blob/main/repl/repl.cpp"
    click Examples "https://github.com/klebert-engineering/simfil/tree/main/examples/minimal"
    click PublicAPI "https://github.com/klebert-engineering/simfil/blob/main/include/simfil/simfil.h"

    %% Styling
    classDef core fill:#dae8fc,stroke:#6c8ebf
    classDef memory fill:#d5e8d4,stroke:#82b366
    classDef model fill:#fff2cc,stroke:#d6b656
    classDef types fill:#e1d5e7,stroke:#9673a6
    classDef external fill:#f5f5f5,stroke:#666666
    classDef app fill:#ffe6cc,stroke:#d79b00

    class Parser,TokenSystem,ExprSystem,Interpreter core
    class Arena,StringPool memory
    class BaseModel,JSONModel,NodeSystem model
    class CoreTypes,Values,TypeMeta types
    class JSON,Bitsery,SFL,FMT external
    class REPL,Examples app
```
