# optozorax/portal architecture

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

- Interactive diagram: https://gitdiagram.com/optozorax/portal
- Repository: https://github.com/optozorax/portal

## Overview

##### Core Project Type and Purpose
- This is a graphical/visualization tool built in Rust.
- It focuses on rendering various “portal” scenes (as defined in numerous .ron files in the scenes folder) and provides a dynamic GUI (with plenty of UI modules in src/gui) for real-time interaction.
- The project leverages shader files (e.g., src/frag.glsl and src/library.glsl) to manage low-level rendering, and uses configuration files (RON formats in scenes/) to define scene parameters.

##### File Structure for Architectural Insights
- Top-Level Files:
- Cargo.toml and Cargo.lock indicate a standard Rust project.
- README files and several markdown files (e.g., description.easymarkup.*, welcome.easymarkup.*) serve for end-user documentation.
- .gitignore and a Cargo.toml show standard project scaffolding.
- Directories:
- The scenes directory holds multiple RON files. These contain scene-specific definitions like “monoportal”, “tripple_portal,” “hopf_link,” etc.
- The src directory contains the core Rust source code:
- src/main.rs acts as the main entry point.
- src/lib.rs provides the core library functionality.
- src/gui subdirectory is full of modules that deal with various aspects of the GUI, such as animation, camera control, material settings, and shader uniform handling.
- Additional source files like code_generation.rs, shader_error_parser.rs, and with_swapped.rs suggest auxiliary functions for scene generation, debugging shaders, or managing runtime state.
- Configuration & Resources:
- GLSL shader files (source/frag.glsl and src/library.glsl) drive rendering.
- Image assets in the img folder support documentation/media aspects shown in the README.

##### Identifying the Main System Components
- Scene Management / Configuration Loader:
- This component is responsible for reading and interpreting the RON scene files from the “scenes” directory.
- It acts as the “model” in a conceptual MVC setup – the raw data that drives visual scenes.
- Rendering Engine:
- Interacts with GPU resources; likely encapsulated in modules within src/lib.rs and possibly linked with the shader error parser for debugging.
- GUI & Interaction Layer:
- Modules in src/gui (e.g., camera, animation, matrix, texture, object management) constitute the frontend widgetry for user interactions.
- This layer includes components for camera control, dynamic animation, and user input handling (for scene rotation, zoom, navigation, etc.).
- Code Generation & Utility Modules:
- Files like code_generation.rs and shader_error_parser.rs indicate tooling components that generate code or help parse shader errors to feed back into the development cycle.
- Main Application Controller:
- The main.rs file ties everything together, handling initialization, event loops, and orchestrating interactions between the rendering engine, GUI, and scene loader.

##### Understand the Relationships and Data Flow
- The Main Application Controller (src/main.rs) initializes the system.
- It loads a scene from the “scenes” directory (using RON files) and passes the scene configuration to the Rendering Engine.
- The Rendering Engine compiles and applies shader programs (referenced by the GLSL files).
- The GUI layer (modules under src/gui) captures user interaction (like camera movements and animations) and updates the state within the Rendering Engine accordingly.
- Utility modules (e.g., code_generation and shader_error_parser) support both the rendering and debugging pipeline.

##### Architectural Patterns and Design Principles
- Modular Design:
- Separation into clearly defined modules (scene management, rendering engine, GUI, code generation) eases maintenance and future extensions.
- Data-Driven Configuration:
- The use of external RON files for scene descriptions allows new scenes to be added without modifying code.
- MVC-inspired or Layered Architecture:
- Even if not explicitly MVC, there’s a clear separation between the data (scenes), the application logic (rendering engine, main.rs), and the interaction/UI (src/gui).

##### Specific Inclusions
- Main Application (src/main.rs)
- Scene Loader/Parser (handles RON files in scenes/)
- Core Rendering Engine (integrated with GLSL shaders)
- GUI Subsystem (detailing modules: animation, camera, matrix, texture, etc.)
- Utility Modules (code_generation, shader_error_parser)
- The initialization flow from Main → Scene Loader
- Data flow from Scene Loader → Rendering Engine
- User interaction feedback from GUI → Rendering Engine
- Supporting tool communication (e.g., shader error messages) feeding back to developers.
- Distinguish external assets:
- Scenes (RON files)
- Image assets (img folder)
- Shader code files (GLSL files)

##### Final Advice
- Avoid oversimplification – represent even minor subsystems (like the code generation and shader parsing components) if they significantly impact the runtime or development process.
- Use annotations to describe external interfaces, for instance, how a user’s actions in the GUI lead to camera updates in the rendered scene.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Assets & Resources
    subgraph "Assets & Resources"
        SA["Scenes Assets (scenes directory)"]:::asset
        IA["Image Assets (img)"]:::asset
        DOC["Documentation (README.md)"]:::asset
    end

    %% Application Layer
    subgraph "Application Layer"
        MA["Main Application (src/main.rs)"]:::core
        SL["Scene Loader/Parser"]:::core
        RE["Core Rendering Engine (src/lib.rs)"]:::core
    end

    %% GUI Layer
    subgraph "GUI Layer"
        GUIC["Camera (src/gui/camera.rs)"]:::gui
        GUIA["Animation (src/gui/animation.rs)"]:::gui
        GUIM["Matrix (src/gui/matrix.rs)"]:::gui
        GUIT["Texture (src/gui/texture.rs)"]:::gui
        GUIO["Object (src/gui/object.rs)"]:::gui
        GUIU["Uniform (src/gui/uniform.rs)"]:::gui
    end

    %% Utility Layer
    subgraph "Utility Layer"
        UT1["Code Generation Utility (src/code_generation.rs)"]:::utility
        UT2["Shader Error Parser (src/shader_error_parser.rs)"]:::utility
    end

    %% Shader Files
    subgraph "Shader Files"
        SH1["Shader: frag.glsl"]:::shader
        SH2["Shader: library.glsl"]:::shader
    end

    %% Connections
    SA -->|"loads"| SL
    MA -->|"init"| SL
    MA -->|"initialize"| RE
    SL -->|"providesSceneData"| RE
    RE -->|"compiles"| SH1
    RE -->|"compiles"| SH2
    GUIC -->|"updates"| RE
    GUIA -->|"updates"| RE
    GUIM -->|"updates"| RE
    GUIT -->|"updates"| RE
    GUIO -->|"updates"| RE
    GUIU -->|"updates"| RE
    UT1 -->|"supports"| RE
    UT2 -->|"debugs"| RE

    %% Click Events
    click MA "https://github.com/optozorax/portal/blob/master/src/main.rs"
    click RE "https://github.com/optozorax/portal/blob/master/src/lib.rs"
    click SH1 "https://github.com/optozorax/portal/blob/master/src/frag.glsl"
    click SH2 "https://github.com/optozorax/portal/blob/master/src/library.glsl"
    click SL "https://github.com/optozorax/portal/tree/master/scenes"
    click GUIC "https://github.com/optozorax/portal/blob/master/src/gui/camera.rs"
    click GUIA "https://github.com/optozorax/portal/blob/master/src/gui/animation.rs"
    click GUIM "https://github.com/optozorax/portal/blob/master/src/gui/matrix.rs"
    click GUIT "https://github.com/optozorax/portal/blob/master/src/gui/texture.rs"
    click GUIO "https://github.com/optozorax/portal/blob/master/src/gui/object.rs"
    click GUIU "https://github.com/optozorax/portal/blob/master/src/gui/uniform.rs"
    click UT1 "https://github.com/optozorax/portal/blob/master/src/code_generation.rs"
    click UT2 "https://github.com/optozorax/portal/blob/master/src/shader_error_parser.rs"
    click IA "https://github.com/optozorax/portal/tree/master/img"
    click DOC "https://github.com/optozorax/portal/blob/master/README.md"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef gui fill:#98FB98,stroke:#006400,stroke-width:2px;
    classDef utility fill:#FFD700,stroke:#DAA520,stroke-width:2px;
    classDef asset fill:#D3D3D3,stroke:#696969,stroke-width:2px;
    classDef shader fill:#E6E6FA,stroke:#800080,stroke-width:2px;
```
