# trafexofive/satori architecture

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

- Interactive diagram: https://gitdiagram.com/trafexofive/satori
- Repository: https://github.com/trafexofive/satori

## Overview

##### Project Type and Purpose
- Satori is a language implementation: a statically‐typed scripting language interpreter with a bytecode VM.
- Purpose: compile `.sat` source files into bytecode and execute them with zero-magic, high-clarity runtime behavior.

##### File Structure
- Top‐level:
- Makefile & scripts/ – build/test/install automation
- infra/docker-compose.dev.yml & infra/env – dev environment setup
- docs/, ARCHITECTURE.md – design and spec documentation
- examples/ – sample programs
- benchmarks/ – performance comparisons across shells and Go
- tests/ – unit/integration tests for lexer, parser, VM, stdlib
- src/ – core implementation
- stdlib/ – standalone or extended built-in modules
- src/ layered according to ARCHITECTURE.md:
- core/ (layer 0) – value system, memory, table, object
- frontend/ (layer 1) – lexer, parser, AST, typechecker
- backend/ (layer 2) – code generator (AST → bytecode)
- runtime/ (layer 3) – VM, module loader, GC hooks
- stdlib/ (layer 4) – native bindings (io, string, etc.)

##### README for Additional Insights
- Confirms the 5‐layer architecture
- Highlights module system, type inference, control flow, operators
- Lists in‐progress and planned features

- CLI Driver (`src/main.c`, argument parsing)
- Frontend Layer – Lexer, Parser, AST builder, Typechecker (src/frontend)
- Core IR Layer – in‐memory AST & value tables (src/core)
- Backend Layer – Bytecode Code Generator (src/backend)
- Runtime Layer – Bytecode VM, module loader, memory manager (src/runtime)
- Standard Library Modules – Native C I/O, string, math, net, etc. (src/stdlib + stdlib/)
- Host OS & External Services – File system, network, time (via stdlib modules)

1. User invokes `bin/satori` → CLI Driver
2. CLI reads `.sat` file → Frontend Module
3. Lexer → Parser → Typechecker → produces AST
4. Backend codegen compiles AST → Bytecode format
5. VM loads Bytecode → executes opcodes
6. During execution, VM calls into stdlib modules → OS services
7. Output back to console or network

c. Architectural Patterns & Principles
- Layered Pipeline: strict separation of concerns (frontend → backend → runtime)
- Modular Stdlib: each module as plugin, lazy‐loaded via module system
- Zero Magic: explicit call graphs, no hidden runtime transforms
- Test harness and benchmark harness as consumers of every layer

d. Key Technologies & Frameworks
- Language: C (gcc/clang, POSIX)
- Build: Makefile, shell scripts
- Containerized Dev: Docker Compose + .env
- Testing: custom C test runners, `.sat` test suites
- Benchmarks: Bash vs Go comparisons

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Driver
    CLI["CLI Driver"]:::cli
    click CLI "https://github.com/trafexofive/satori/blob/main/src/main.c"

    %% Frontend Layer
    subgraph "Frontend Layer"
        FE_Lex["Lexer"]:::frontend
        FE_Par["Parser"]:::frontend
        FE_AST["AST Builder"]:::frontend
        FE_TC["Typechecker"]:::frontend
    end
    click FE_Lex "https://github.com/trafexofive/satori/blob/main/src/frontend/lexer.c"
    click FE_Lex "https://github.com/trafexofive/satori/blob/main/src/frontend/lexer.h"
    click FE_Par "https://github.com/trafexofive/satori/blob/main/src/frontend/parser.c"
    click FE_Par "https://github.com/trafexofive/satori/blob/main/src/frontend/parser.h"
    click FE_AST "https://github.com/trafexofive/satori/blob/main/src/frontend/ast.c"
    click FE_AST "https://github.com/trafexofive/satori/blob/main/src/frontend/ast.h"
    click FE_TC "https://github.com/trafexofive/satori/blob/main/src/frontend/typechecker.c"
    click FE_TC "https://github.com/trafexofive/satori/blob/main/src/frontend/typechecker.h"

    %% Core IR Layer
    subgraph "Core IR Layer"
        CR_Mem["Memory"]:::core
        CR_Obj["Object"]:::core
        CR_Tab["Table"]:::core
        CR_Val["Value"]:::core
        CR_Com["Common"]:::core
    end
    click CR_Mem "https://github.com/trafexofive/satori/blob/main/src/core/memory.c"
    click CR_Mem "https://github.com/trafexofive/satori/blob/main/src/core/memory.h"
    click CR_Obj "https://github.com/trafexofive/satori/blob/main/src/core/object.c"
    click CR_Obj "https://github.com/trafexofive/satori/blob/main/src/core/object.h"
    click CR_Tab "https://github.com/trafexofive/satori/blob/main/src/core/table.c"
    click CR_Tab "https://github.com/trafexofive/satori/blob/main/src/core/table.h"
    click CR_Val "https://github.com/trafexofive/satori/blob/main/src/core/value.c"
    click CR_Val "https://github.com/trafexofive/satori/blob/main/src/core/value.h"
    click CR_Com "https://github.com/trafexofive/satori/blob/main/src/core/common.h"

    %% Backend Layer
    subgraph "Backend Layer"
        BE_CG["Bytecode Code Generator"]:::backend
        BE_Com["Common"]:::backend
    end
    click BE_CG "https://github.com/trafexofive/satori/blob/main/src/backend/codegen.c"
    click BE_CG "https://github.com/trafexofive/satori/blob/main/src/backend/codegen.h"
    click BE_Com "https://github.com/trafexofive/satori/blob/main/src/backend/common.h"

    %% Runtime Layer
    subgraph "Runtime Layer"
        RT_VM["Bytecode VM"]:::runtime
        RT_Mod["Module Loader"]:::runtime
    end
    click RT_VM "https://github.com/trafexofive/satori/blob/main/src/runtime/vm.c"
    click RT_VM "https://github.com/trafexofive/satori/blob/main/src/runtime/vm.h"
    click RT_Mod "https://github.com/trafexofive/satori/blob/main/src/runtime/module.c"
    click RT_Mod "https://github.com/trafexofive/satori/blob/main/src/runtime/module.h"

    %% Standard Library Modules
    subgraph "Standard Library"
        subgraph "Native Bindings (src/stdlib)"
            SL_IO["I/O"]:::stdlib
            SL_Str["String"]:::stdlib
        end
        subgraph "Extended Modules (stdlib)"
            EM_Ag["agent.c"]:::extstdlib
            EM_Col["collections.c"]:::extstdlib
            EM_Doc["docker.c"]:::extstdlib
            EM_IO2["io.c"]:::extstdlib
            EM_Json["json.c"]:::extstdlib
            EM_Math["math.c"]:::extstdlib
            EM_Net["net.c"]:::extstdlib
            EM_OS["os.c"]:::extstdlib
            EM_Str2["string.c"]:::extstdlib
            EM_Time["time.c"]:::extstdlib
            EM_Wf["workflows.c"]:::extstdlib
            EM_Yaml["yaml.c"]:::extstdlib
        end
    end
    click SL_IO "https://github.com/trafexofive/satori/blob/main/src/stdlib/io.c"
    click SL_IO "https://github.com/trafexofive/satori/blob/main/src/stdlib/io.h"
    click SL_Str "https://github.com/trafexofive/satori/blob/main/src/stdlib/string.c"
    click SL_Str "https://github.com/trafexofive/satori/blob/main/src/stdlib/string.h"
    click EM_Ag "https://github.com/trafexofive/satori/blob/main/stdlib/agent.c"
    click EM_Col "https://github.com/trafexofive/satori/blob/main/stdlib/collections.c"
    click EM_Doc "https://github.com/trafexofive/satori/blob/main/stdlib/docker.c"
    click EM_IO2 "https://github.com/trafexofive/satori/blob/main/stdlib/io.c"
    click EM_Json "https://github.com/trafexofive/satori/blob/main/stdlib/json.c"
    click EM_Math "https://github.com/trafexofive/satori/blob/main/stdlib/math.c"
    click EM_Net "https://github.com/trafexofive/satori/blob/main/stdlib/net.c"
    click EM_OS "https://github.com/trafexofive/satori/blob/main/stdlib/os.c"
    click EM_Str2 "https://github.com/trafexofive/satori/blob/main/stdlib/string.c"
    click EM_Time "https://github.com/trafexofive/satori/blob/main/stdlib/time.c"
    click EM_Wf "https://github.com/trafexofive/satori/blob/main/stdlib/workflows.c"
    click EM_Yaml "https://github.com/trafexofive/satori/blob/main/stdlib/yaml.c"

    %% OS External
    OS["Host OS & Services"]:::external

    %% Scripts and Env
    subgraph "Build & Test Scripts"
        SCR_Build["build.sh"]:::scripts
        SCR_Test["test.sh"]:::scripts
        SCR_Inst["install.sh"]:::scripts
    end
    click SCR_Build "https://github.com/trafexofive/satori/blob/main/scripts/build.sh"
    click SCR_Test "https://github.com/trafexofive/satori/blob/main/scripts/test.sh"
    click SCR_Inst "https://github.com/trafexofive/satori/blob/main/scripts/install.sh"

    subgraph "Dev Environment"
        INF_DC["docker-compose.dev.yml"]:::infra
        INF_ENV[".dev.env"]:::infra
    end
    click INF_DC "https://github.com/trafexofive/satori/blob/main/infra/docker-compose.dev.yml"
    click INF_ENV "https://github.com/trafexofive/satori/blob/main/infra/env/.dev.env"

    %% Docs, Tests, Examples, Benchmarks
    DOC["ARCHITECTURE.md & docs/"]:::docs
    click DOC "https://github.com/trafexofive/satori/blob/main/ARCHITECTURE.md"
    click DOC "https://github.com/trafexofive/satori/tree/main/docs/"

    TESTS["tests/"]:::tests
    click TESTS "https://github.com/trafexofive/satori/tree/main/tests/"

    EX["examples/"]:::examples
    click EX "https://github.com/trafexofive/satori/tree/main/examples/"

    BM["benchmarks/"]:::benchmarks
    click BM "https://github.com/trafexofive/satori/tree/main/benchmarks/"

    %% Data Flow
    CLI -->|"reads .sat"| FE_Lex
    FE_Lex -->|"tokens"| FE_Par
    FE_Par -->|"parse tree"| FE_AST
    FE_AST -->|"typed AST"| FE_TC
    FE_TC -->|"AST"| CR_Mem
    CR_Mem -->|"IR value tables"| BE_CG
    BE_CG -->|"Bytecode"| RT_VM
    RT_VM -->|"loads modules"| RT_Mod
    RT_Mod -->|"native calls"| SL_IO
    RT_VM -->|"OS services"| OS
    RT_VM -->|"executes opcodes"| OS
    SL_IO --> OS
    SL_Str --> OS
    EM_IO2 --> OS

    %% Side Hooks
    TESTS --> FE_Lex
    TESTS --> FE_Par
    TESTS --> FE_TC
    TESTS --> RT_VM

    SCR_Build --> CLI
    SCR_Test --> TESTS
    INF_DC --> SCR_Build
    DOC --> CLI

    EX --> CLI
    BM --> CLI

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px;
    classDef frontend fill:#bbdefb,stroke:#1e88e5,stroke-width:1px;
    classDef core fill:#b3e5fc,stroke:#0288d1,stroke-width:1px;
    classDef backend fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;
    classDef runtime fill:#ffcdd2,stroke:#c62828,stroke-width:1px;
    classDef stdlib fill:#fff9c4,stroke:#fbc02d,stroke-width:1px;
    classDef extstdlib fill:#fff176,stroke:#f9a825,stroke-width:1px;
    classDef external fill:#e0e0e0,stroke:#616161,stroke-width:1px;
    classDef scripts fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px;
    classDef infra fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px;
    classDef docs fill:#d7ccc8,stroke:#4e342e,stroke-width:1px;
    classDef tests fill:#f8bbd0,stroke:#ad1457,stroke-width:1px;
    classDef examples fill:#eceff1,stroke:#607d8b,stroke-width:1px;
    classDef benchmarks fill:#cfd8dc,stroke:#455a64,stroke-width:1px;
```
