# abdelkaderce/oker architecture

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

- Interactive diagram: https://gitdiagram.com/abdelkaderce/oker
- Repository: https://github.com/abdelkaderce/oker

## Overview

##### Project type and purpose
- Oker is a full‐stack interpreted programming language project.
- It combines a C++ compiler/interpreter backend (compiler pipeline + VM) with a web‐based frontend for interactive editing and testing.

##### File structure
- Top-level directories and files:
– OkerCompiler/src: C++ source for compiler pipeline (lexer, parser, semantic, codegen, VM, built-ins).
– OkerCompiler/tests: Unit tests for each compiler component.
– OkerCompiler/web: Frontend assets (HTML, CSS, JS) and Python HTTP server.
– Build scripts/config: CMakeLists.txt, build.sh.
– Examples and attached assets: sample .oker files, demos.
- Pattern: classic compiler pipeline on the backend + REST API microservice + SPA on the frontend.

##### README for additional insights
- Backend: C++17, CMake, pipeline stages (Lexer → Parser → Semantic → CodeGen → VM).
- Frontend: Vanilla JS SPA, served by Python HTTP server providing compilation endpoints.
- Data flows: user code → tokens → AST → bytecode → VM → output → JSON → UI.
- Testing: CMake‐integrated unit tests, integration via web interface.

a. Main components
1. Web Browser (User Interface)
– HTML/CSS/JS (web/index.html, style.css, app.js)
2. Python HTTP Server (web/server.py)
– Exposes REST endpoints for compile/run
3. Compiler Binary (built via CMake)
– CLI executable produced from src/main.cpp, invoked by server.py
4. Compiler Pipeline
– Lexer (lexer.cpp/.h)
– Parser (parser.cpp/.h)
– Semantic Analyzer (semantic.cpp/.h)
– Code Generator (codegen.cpp/.h)
– Virtual Machine (vm.cpp/.h)
– Built-ins (builtins.cpp/.h)
5. Test Framework
– Unit tests (tests/*.cpp)
– Build scripts (CMakeLists.txt, build.sh)
6. Examples and Assets
– test programs (.oker files), demos, attached_assets
b. Relationships and interactions
– User writes code in the browser → triggers app.js
– app.js issues HTTP POST to server.py
– server.py calls the compiler binary with source path
– Compiler binary runs pipeline: lex → parse → semantic → codegen → VM
– VM executes bytecode and returns stdout or JSON result
– server.py packages results (tokens, AST, bytecode, output) into JSON → HTTP response
– app.js parses JSON → updates UI
– Tests interact directly with compiler binary via CMake test targets
c. Architectural patterns and design principles
– Compiler pipeline pattern
– Separation of concerns: frontend SPA vs backend REST vs compiler core
– Modular design: each compiler stage is its own module
– Testability: unit tests for each stage, integration via SPA
– Build reproducibility: CMake + scripted build.sh
d. Key technologies and frameworks
– C++17, CMake, Address Sanitizer
– Python 3 HTTP server
– Vanilla JavaScript, HTML5, CSS3
– REST API over HTTP

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Web Frontend"
        direction TB
        HTML["index.html"]:::frontend
        CSS["style.css"]:::frontend
        JS["app.js"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Server["Python HTTP Server"]:::api
    end

    %% Compiler Core
    subgraph "Compiler Core"
        direction TB
        subgraph "Build & CLI"
            direction TB
            MainExec["Compiler CLI Binary"]:::compiler
            CMake["CMakeLists.txt"]:::compiler
            BuildSh["build.sh"]:::compiler
        end
        subgraph "Compiler Pipeline"
            direction TB
            Lexer["Lexer Module"]:::compiler
            Parser["Parser Module"]:::compiler
            Semantic["Semantic Analyzer"]:::compiler
            CodeGen["Code Generator"]:::compiler
            Optimizer["Optimizer Stage"]:::compiler
            VM["Virtual Machine"]:::compiler
            Builtins["Built-ins Module"]:::compiler
        end
    end

    %% Test Framework
    subgraph "Test Framework"
        direction TB
        TestLexer["test_lexer.cpp"]:::test
        TestParser["test_parser.cpp"]:::test
        TestSemantic["test_semantic.cpp"]:::test
        TestCodeGen["test_codegen.cpp"]:::test
    end

    %% Examples
    subgraph "Example Programs & Assets"
        direction TB
        Examples[".oker Examples"]:::examples
    end

    %% Data Flows
    JS -->|"HTTP POST /compile"| Server
    Server -->|"invokes CLI"| MainExec
    MainExec --> Lexer
    Lexer --> Parser
    Parser --> Semantic
    Semantic --> CodeGen
    CodeGen --> Optimizer
    Optimizer --> VM
    VM --> Builtins
    VM -->|"executes bytecode"| Server
    Server -->|"HTTP Response JSON"| JS

    %% Tests interactions
    TestLexer --> MainExec
    TestParser --> MainExec
    TestSemantic --> MainExec
    TestCodeGen --> MainExec

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B9F,color:#005B9F;
    classDef api fill:#DFF2D8,stroke:#2E7D32,color:#2E7D32;
    classDef compiler fill:#FFEACC,stroke:#E65100,color:#E65100;
    classDef test fill:#E0E0E0,stroke:#616161,color:#424242;
    classDef examples fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A;

    %% Click Events
    click HTML "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/web/index.html"
    click CSS "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/web/style.css"
    click JS "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/web/app.js"
    click Server "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/web/server.py"
    click MainExec "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/main.cpp"
    click CMake "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/CMakeLists.txt"
    click BuildSh "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/build.sh"
    click Lexer "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/lexer.cpp"
    click Parser "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/parser.cpp"
    click Semantic "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/semantic.cpp"
    click CodeGen "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/codegen.cpp"
    click Optimizer "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/optimizer.cpp"
    click VM "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/vm.cpp"
    click Builtins "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/src/builtins.cpp"
    click TestLexer "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/tests/test_lexer.cpp"
    click TestParser "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/tests/test_parser.cpp"
    click TestSemantic "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/tests/test_semantic.cpp"
    click TestCodeGen "https://github.com/abdelkaderce/oker/blob/working-state/OkerCompiler/tests/test_codegen.cpp"
    click Examples "https://github.com/abdelkaderce/oker/tree/working-state/OkerCompiler/examples"
```
