# funsoftwaretechologies/planettech architecture

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

- Interactive diagram: https://gitdiagram.com/funsoftwaretechologies/planettech
- Repository: https://github.com/funsoftwaretechologies/planettech

## Overview

##### Main Components
- Core Engine: This is housed in the src/engine folder. It includes modules such as geometry, primitives, quadtree (for LOD), and threading. This core handles the planet generation logic and GPU-intensive calculations.
- Shader System: Found in the src/shaders directory, split between two shader language implementations (TSL and WGSL). These files (like functions.js, noise.js, utils.js) implement procedural noise and other visual effects which are applied by the GPU.
- Utilities: Located in src/utils, these offer support functions and miscellaneous helpers used across the project.
- Examples & Assets: The examples folder contains various demos (HTML, JS examples) that illustrate how to use the library in a simple webpage context. The assets folder holds media resources like logos.
- Project Integration & Configuration: The root directory with index.js, package.json, and additional configuration (like .gitignore, .vscode) files ties everything together.
- Service Worker Integration: The examples/coi-serviceworker.js file indicates that there’s support for progressive loading/offline capabilities through a service worker, which is significant when integrating PlanetTech into a broader application.

##### Relationships and Interactions
- The Core Engine interacts with the Shader System to efficiently generate and modify visuals on the GPU. For example, the quadtree from the engine drives the level-of-detail mechanisms that feed into shader functions.
- The Utilities support both engine and shader functionalities, providing common functions, error handling, or miscellaneous utilities.
- The examples serve as a front-end demonstration of how to integrate the engine (planet generation) and shaders into an HTML environment, possibly leveraging both THREE.js and React elements.
- For integration in end-user projects, there is an interaction between the library and a React UI (as mentioned in the README) that acts as an editor for planet properties.
- Although the README mentioned that WebWorkers are not required at this stage, there is a _worker.js file indicating that threading or worker processes might be set up for handling complex computations if needed.

##### Architectural Patterns and Design Principles
- Modularity: The project is cleanly separated into engine, shader, and utilities modules.
- GPU-Centric Design: Emphasize that nearly all heavy computations are offloaded to the GPU via shader code.
- Procedural Generation with Quadtree LOD: This design pattern helps in handling massive scale (from sky to ground) with progressive detail adjustment.
- Separation of Concerns: There is a clear divide between core generation logic (src/engine), rendering effects (src/shaders), and support functions (src/utils).

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "PlanetTech Engine (Core)"
    E1["Geometry"]:::engine
    E2["Primitives"]:::engine
    E3["Quadtree (LOD)"]:::engine
    E4["Threading"]:::engine
    W["Worker"]:::engine
    E4 -->|"spawn"| W
  end

  subgraph "Shader System"
    subgraph "TSL Implementation"
      S1["TSL Functions"]:::shader
      S2["TSL Noise"]:::shader
      S3["TSL Utils"]:::shader
    end
    subgraph "WGSL Implementation"
      S4["WGSL Noise"]:::shader
    end
  end

  subgraph "Utilities"
    U["Utilities"]:::utils
  end

  subgraph "Integration & Demo"
    R["React UI Editor"]:::integration
    EX["Examples"]:::integration
    A["Assets"]:::integration
    SW["Service Worker"]:::integration
    PI["Project Integration"]:::integration
  end

  %% Relationships
  %% Engine-to-Shader: LOD data flow from Quadtree to shader functions
  E3 -->|"LODflow"| S1
  
  %% Both Engine and Shader depend on Utilities
  E2 -->|"support"| U
  S3 -->|"support"| U
  
  %% React UI interaction (bidirectional) with Engine (using Geometry as representative)
  R <-->|"UIlink"| E1
  
  %% Examples serve as demos for all core components
  EX -->|"demo"| E1
  EX -->|"demo"| E2
  EX -->|"demo"| E3
  EX -->|"demo"| E4
  EX -->|"demo"| S1
  EX -->|"demo"| S2
  EX -->|"demo"| S3
  EX -->|"demo"| S4
  EX -->|"demo"| U
  
  %% Project integration links
  PI -->|"configures"| R
  PI -->|"configures"| EX
  
  %% Service Worker supports Examples for offline capabilities
  SW -->|"offline"| EX

  %% Click Events for PlanetTech Engine
  click E1 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/engine/geometry.js"
  click E2 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/engine/primatives.js"
  click E3 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/engine/quadtree.js"
  click E4 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/engine/threading.js"
  click W "https://github.com/funsoftwaretechologies/planettech/blob/main/src/engine/_worker.js"

  %% Click Events for Shader System (TSL & WGSL)
  click S1 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/shaders/tsl/functions.js"
  click S2 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/shaders/tsl/noise.js"
  click S3 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/shaders/tsl/utils.js"
  click S4 "https://github.com/funsoftwaretechologies/planettech/blob/main/src/shaders/wgsl/noise.js"

  %% Click Event for Utilities
  click U "https://github.com/funsoftwaretechologies/planettech/tree/main/src/utils"

  %% Click Events for Integration & Demo
  click EX "https://github.com/funsoftwaretechologies/planettech/tree/main/examples"
  click SW "https://github.com/funsoftwaretechologies/planettech/blob/main/examples/coi-serviceworker.js"
  click A "https://github.com/funsoftwaretechologies/planettech/tree/main/assets"
  click PI "https://github.com/funsoftwaretechologies/planettech/blob/main/index.js"

  %% Styling Classes
  classDef engine fill:#ffcc00,stroke:#333,stroke-width:2px,color:#000;
  classDef shader fill:#66ccff,stroke:#333,stroke-width:2px,color:#000;
  classDef utils fill:#ccffcc,stroke:#333,stroke-width:2px,color:#000;
  classDef integration fill:#ff99cc,stroke:#333,stroke-width:2px,color:#000;
```
