# ahmedaziz703/ahmedgames3d architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedaziz703/ahmedgames3d
- Repository: https://github.com/ahmedaziz703/ahmedgames3d

## Overview

##### Project Type and Purpose
- Folio 2025 is a front-end–only, interactive 3D portfolio built with Three.js and Vite.
- It uses Node.js + Vite for bundling/dev, and serves a Single-Page Application (SPA) that renders a WebGL scene, loads 3D models (GLB via DRACO), shaders (GLSL), textures, and sounds.

##### Key Architectural Components
a. Build & Deployment Pipeline
- Vite Development Server (npm run dev)
- Vite Bundler → transforms ES modules, inlines shaders, copies static assets to dist/
- Production Build (npm run build) → dist/ folder
b. Runtime (Browser)
- index.html → main.js (entry point)
- Application.js → Initializes Three.js Renderer, Scene, Camera, Controls
- Resources Manager → loads models (GLTFLoader + DRACOLoader), shaders, textures, sounds
- World Module → organizes scene graph into Areas, Sections, Objects, Physics, Sounds, EasterEggs
- Geometries & Materials → custom geometry and material classes pairing GLSL shaders with mesh data
- Post-processing Passes → Blur, Glow, Shadow passes
- Utils → EventEmitter (pub/sub for inter-module events), Sizes, Time, Loader helpers

##### Relationships & Data Flows
- Browser loads index.html → main.js → Application.initialize()
- Application hooks Time.tick() → update loop →
- Resources Manager ensures assets are loaded
- World.update():
– Controls → user input → modifies camera/physics
– Physics → collision checks using imported meshes (collision.glb)
– Objects/EasterEggs → change state or fire events via EventEmitter
– Sounds → triggered by events or physics results
- Render Passes: Scene rendered by Three.js Renderer → post-processing pipeline → canvas
- Static assets (models/, sounds/, favicons/) served by Vite or copied to dist/

##### Architectural Patterns & Principles
- Modularity: Clear separation of concerns (Loader, World, Geometries, Materials, Passes, Utils)
- Pub/Sub: EventEmitter decouples modules (e.g., World triggers sound events)
- Data-driven Scene Graph: World → Areas → Sections → Objects loaded from static models
- Pipeline Stages: Asset loading → Scene setup → Update loop → Render → Post-process

1. “Vite Dev & Build” (purple)
– npm run dev → dev server
– npm run build → dist/
– models/ (GLB + collision meshes)
– sounds/ (MP3/WAV)
– shaders/ (.glsl partials & modules)
3. “Resources Manager” (blue)
– Loader.js + EventEmitter
– DRACOLoader (WASM) & GLTFLoader
– Fetches assets over HTTP
4. “Application Core” (blue)
– Application.js: sets up Three.js renderer, scene, camera, loop
– Time.js & Sizes.js for frame/timing
5. “World” (blue)
– Areas, Sections, Objects, Physics, Sounds, EasterEggs
– organizes scene graph hierarchy
6. “Materials & Geometries” (blue/orange)
– Custom classes pairing Three.js Mesh + ShaderMaterial + geometry data
7. “Post-Processing Passes” (orange)
– Blur, Glow, Shadow passes feeding off renderer output
8. “Renderer & Canvas” (orange)
– Three.js WebGLRenderer → output to HTMLCanvasElement
9. “Controls & Events” (blue)
– Controls.js → user input → camera/physics → EventEmitter events → World modules

## Diagram (Mermaid)

```mermaid
graph TD
    %% Build & Deployment Pipeline
    subgraph "Build & Deployment Pipeline"
        B1["vite.config.js"]:::build
        B2["package.json"]:::build
        B3["src/index.html"]:::build
        B4["src/index.js"]:::build
    end

    %% Static Assets
    subgraph "Static Assets"
        A1["src/shaders/"]:::assets
        A2["static/draco/"]:::assets
        A3["static/models/"]:::assets
        A4["static/sounds/"]:::assets
        A5["src/favicon/"]:::assets
        A6["static/favicon/"]:::assets
        A7["src/images/"]:::assets
    end

    %% Runtime Modules
    subgraph "Runtime Modules"
        subgraph "Resources Manager"
            R1["src/javascript/Resources.js"]:::code
            R2["src/javascript/Utils/Loader.js"]:::code
            R3["src/javascript/Utils/EventEmitter.js"]:::code
        end

        subgraph "Application Core"
            C1["src/javascript/Application.js"]:::code
            C2["src/javascript/Camera.js"]:::code
            C3["src/javascript/Utils/Time.js"]:::code
            C4["src/javascript/Utils/Sizes.js"]:::code
        end

        subgraph "World Module"
            W1["src/javascript/World/index.js"]:::code
            W2["src/javascript/World/Area.js"]:::code
            W3["src/javascript/World/Controls.js"]:::code
            W4["src/javascript/World/Physics.js"]:::code
            W5["src/javascript/World/Sounds.js"]:::code
            W6["src/javascript/World/EasterEggs.js"]:::code
        end

        subgraph "Geometries & Materials"
            G1["src/javascript/Geometries/"]:::code
            G2["src/javascript/Materials/"]:::code
        end

        subgraph "Post-Processing Passes"
            P1["src/javascript/Passes/Blur.js"]:::pipeline
            P2["src/javascript/Passes/Glows.js"]:::pipeline
        end

        subgraph "Renderer & Canvas"
            D1["src/javascript/ThreejsJourney.js"]:::pipeline
            D2["HTMLCanvasElement"]:::pipeline
        end

        subgraph "Controls & Events"
            E1["src/javascript/World/Controls.js"]:::code
            E2["src/javascript/Utils/EventEmitter.js"]:::code
        end
    end

    %% Data Flows
    B4 -->|"serves"| A1
    B4 -->|"serves"| A2
    B4 -->|"serves"| A3
    B4 -->|"serves"| A4
    B4 -->|"serves"| A5
    B4 -->|"serves"| A6
    B4 -->|"serves"| A7

    A1 -->|"GLSL"| R1
    A2 -->|"WASM DRACO"| R1
    A3 -->|"GLB"| R1
    A4 -->|"MP3/WAV"| R1

    R1 -->|"assets"| W1
    R2 -->|"helper"| R1
    R3 -->|"pub/sub"| W1

    C1 -->|"init"| D1
    C1 -->|"tick"| C3
    C3 -->|"delta time"| W1
    C4 -->|"viewport"| D1

    W1 -->|"scene graph"| D1
    W3 -->|"input events"| W1
    W4 -->|"collision data"| W1
    W5 -->|"trigger sounds"| E2

    D1 -->|"render"| P1
    P1 -->|"blurred output"| P2
    P2 -->|"final image"| D2

    %% Click Events
    click B1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/vite.config.js"
    click B2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/package.json"
    click B3 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/index.html"
    click B4 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/index.js"
    click R1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Resources.js"
    click R2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Utils/Loader.js"
    click R3 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Utils/EventEmitter.js"
    click C1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Application.js"
    click C2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Camera.js"
    click C3 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Utils/Time.js"
    click C4 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Utils/Sizes.js"
    click W1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/index.js"
    click W2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/Area.js"
    click W3 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/Controls.js"
    click W4 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/Physics.js"
    click W5 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/Sounds.js"
    click W6 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/EasterEggs.js"
    click G1 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/src/javascript/Geometries/"
    click G2 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/src/javascript/Materials/"
    click P1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Passes/Blur.js"
    click P2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Passes/Glows.js"
    click D1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/ThreejsJourney.js"
    click E1 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/World/Controls.js"
    click E2 "https://github.com/ahmedaziz703/ahmedgames3d/blob/main/src/javascript/Utils/EventEmitter.js"
    click A1 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/src/shaders/"
    click A2 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/static/draco/"
    click A3 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/static/models/"
    click A4 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/static/sounds/"
    click A5 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/src/favicon/"
    click A6 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/static/favicon/"
    click A7 "https://github.com/ahmedaziz703/ahmedgames3d/tree/main/src/images/"

    %% Styles
    classDef build fill:#DCC6E0,stroke:#805D93;
    classDef assets fill:#C6E2A9,stroke:#5E8C31;
    classDef code fill:#A9D0F5,stroke:#3465A4;
    classDef pipeline fill:#F5C6A9,stroke:#A45B31;
```
