# oframe/ogl architecture

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

- Interactive diagram: https://gitdiagram.com/oframe/ogl
- Repository: https://github.com/oframe/ogl

## Overview

##### Project type and purpose
- OGL is a minimal, modular WebGL library provided as ES6 modules with zero dependencies.
- It’s designed to give developers a thin abstraction layer over raw WebGL (similar in spirit to Three.js examples, but much lighter).
- It consists of three discrete areas: Math utilities, Core WebGL abstractions, and optional Extras.

##### File structure
- src/core contains the fundamental WebGL building blocks: Renderer, Camera, Transform (scene graph), Mesh, Geometry, Program (shader wrapper), Texture, RenderTarget.
- src/index.js aggregates and exports everything for distribution.
- examples/ demonstrates usage, shows how the library interacts with JSON/GLTF assets, custom shaders, compressed textures, and external WASM/JS “managers” (Draco/Basis).
- types/ mirrors src/ in TypeScript declaration files for consumers.
- package.json & bundling support for npm/CDN distribution.

##### Extract architectural insights from the README
- Confirms the three-layer modular architecture (Math, Core, Extras).
- Emphasizes ES6 modules, tree-shakable entry point, zero dependencies.
- Describes use cases: from full scene graphs with cameras and transforms to one-off fullscreen shaders.
- Mentions external CDN usage and npm packaging.

a. Main components
- Math Module
- Core Module
- Extras Module
- Entry Point (src/index.js → npm package or CDN)
- User Application / Examples
- WebGL Context (browser’s WebGLRenderingContext)
- External Services/Assets: Draco WASM, Basis WASM, GLTF/JSON assets
- Type Definitions (for TS users)

b. Relationships and interactions
- Math → consumed by Core & Extras for matrix/quaternion/vector operations.
- Core → provides fundamental classes (Renderer creates WebGL context; Camera computes projection matrices; Program wraps shaders; Geometry holds buffers; Mesh binds Geometry to Program; Texture and RenderTarget manage GPU textures).
- Extras → extend Core classes (e.g., GLTFLoader uses Geometry, Program, Texture; BasisManager and DracoManager load compressed textures/meshes via WASM).
- Entry Point (index.js) re-exports all Math, Core, Extras classes for consumption.
- User App / Examples import from the Entry Point, instantiate Renderer → get gl context → build scene graph (Camera, Transform, Mesh) → call renderer.render({scene, camera}).
- Examples also load external assets (via Extras) and feed them into Core classes.

c. Architectural patterns and design principles
- Modular layering: clear separation of concerns (Math vs Core vs Extras).
- Tree-shaking-friendly exports: single entry point but no hidden side effects.
- Low-level abstraction: Core gives minimal wrappers, Extras sit on top for convenience.
- Dependency flow always from top (Math) → mid (Core) → upper (Extras) → consumer.

d. Key technologies, frameworks, or libraries
- WebGL / WebGL2 context provided by the browser.
- ES6 modules; tree-shaking via bundlers (Rollup/Webpack).
- WASM decoders (Draco, Basis) loaded by Extras managers.
- JSON/GLTF assets for models.
- NPM package distribution and CDN (unpkg/jsdelivr/skypack).
- TypeScript declaration files for type safety.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    subgraph "User Application / Examples"
        direction TB
        App["Examples / User App"]:::app
    end

    %% Entry Point
    subgraph "Entry Point"
        direction TB
        Entry["src/index.js"]:::entry
    end

    %% Extras Layer
    subgraph "Extras Module" 
        direction TB
        Extras["Extras Module"]:::extras
        GLTF["GLTFLoader"]:::extras
        DracoMgr["DracoManager"]:::extras
        BasisMgr["BasisManager"]:::extras
        Orbit["OrbitControls"]:::extras
        Post["PostProcessing"]:::extras
        Primitives["Primitives"]:::extras
    end

    %% Core Layer
    subgraph "Core Module"
        direction TB
        Core["Core Module"]:::core
        Renderer["Renderer"]:::core
        Camera["Camera"]:::core
        Transform["Transform"]:::core
        Geometry["Geometry"]:::core
        Mesh["Mesh"]:::core
        Program["Program"]:::core
        Texture["Texture"]:::core
        RenderTarget["RenderTarget"]:::core
    end

    %% Math Layer
    subgraph "Math Module"
        direction TB
        Math["Math Module"]:::math
    end

    %% External WASM / JS
    subgraph "External WASM / JS Managers"
        direction TB
        DracoExt["Draco WASM/JS"]:::external
        BasisExt["Basis WASM/JS"]:::external
    end

    %% Type Definitions
    subgraph "Type Definitions"
        direction TB
        TypesMath["types/math"]:::types
        TypesCore["types/core"]:::types
        TypesExtras["types/extras"]:::types
    end

    %% Relationships
    App -->|"imports"| Entry
    Entry -->|"exports Math"| Math
    Entry -->|"exports Core"| Core
    Entry -->|"exports Extras"| Extras

    Core -->|"uses"| Math
    Extras -->|"uses Core"| Core
    Extras -->|"uses Math"| Math

    Extras -->|"loads via"| DracoExt
    Extras -->|"loads via"| BasisExt

    TypesMath -->|"mirrors"| Math
    TypesCore -->|"mirrors"| Core
    TypesExtras -->|"mirrors"| Extras

    %% Internal Core relationships
    Renderer -->|"creates WebGL Context"| Camera
    Renderer -->|"binds"| Geometry
    Renderer -->|"binds"| Program
    Mesh -->|"composes"| Geometry
    Mesh -->|"uses"| Program
    Program -->|"compiles shaders"| RenderTarget
    Geometry -->|"uses buffers"| RenderTarget
    Camera -->|"computes matrices via"| Math
    Transform -->|"scene graph transforms using"| Math

    %% Extras relationships
    GLTF -->|"uses"| Geometry
    GLTF -->|"uses"| Program
    GLTF -->|"uses"| Texture
    DracoMgr -->|"manages"| DracoExt
    BasisMgr -->|"manages"| BasisExt

    %% Click Events
    click Math "https://github.com/oframe/ogl/tree/master/src/math"
    click Core "https://github.com/oframe/ogl/tree/master/src/core"
    click Extras "https://github.com/oframe/ogl/tree/master/src/extras"
    click Entry "https://github.com/oframe/ogl/blob/master/src/index.js"
    click App "https://github.com/oframe/ogl/tree/master/examples/"
    click DracoExt "https://github.com/oframe/ogl/tree/master/examples/assets/libs/draco"
    click BasisExt "https://github.com/oframe/ogl/tree/master/examples/assets/libs/basis"
    click TypesMath "https://github.com/oframe/ogl/tree/master/types/math"
    click TypesCore "https://github.com/oframe/ogl/tree/master/types/core"
    click TypesExtras "https://github.com/oframe/ogl/tree/master/types/extras"

    %% Styles
    classDef math fill:#a4f9c8,stroke:#333,stroke-width:1px
    classDef core fill:#8cc8ff,stroke:#333,stroke-width:1px
    classDef extras fill:#ffb366,stroke:#333,stroke-width:1px
    classDef entry fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef app fill:#c28cff,stroke:#333,stroke-width:1px
    classDef external fill:transparent,stroke:#333,stroke-dasharray: 5 5
    classDef types fill:#f2f2f2,stroke:#333,stroke-width:1px
```
