# aicell-lab/micro-farm-js architecture

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

- Interactive diagram: https://gitdiagram.com/aicell-lab/micro-farm-js
- Repository: https://github.com/aicell-lab/micro-farm-js

## Overview

##### Main Components

- Entry & Initialization
– Key files: index.html, src/main.ts
– Role: The HTML page bootstraps the application, while the main.ts file initializes critical systems such as asset loading (from the public directory after running setup-assets.sh), configuration, and starting the simulation loop.

- Asset Management
– Directory: src/assets
– Components: assetLoader.ts, animationLoader.ts, modelLoader.ts, etc.
– Role: Responsible for loading and organizing 3D assets, URDF files, textures, and animations prior to the simulation rendering.

- Controllers & Input Handling
– Directories: src/ctrl and src/io
– Key files: playerController.ts, cameraController.ts, eventMediator.ts, inputListener.ts, keyboard.ts, mouse.ts
– Role: Manage user interactions and control logic. They bridge input events (keyboard/mouse) to changes in scene state and physical simulation.

- Entity and Setup Management
– Directories: src/entity and src/setup
– Key files: entity.ts, armState.ts, actorFactory.ts, roomObjectFactory.ts, constants.ts
– Role: Define simulation objects (like robotic arms, bubbles, optics units) and provide factory functions and constants for proper entity initialization.

- Physics Simulation
– Directory: src/physics
– Key files: physicsSystem.ts, physicsWorld.ts, physicsSync.ts
– Role: Perform physics simulation using Ammo.js. This subsystem computes physical interactions, updates positions, and interacts with URDF-based objects (e.g., robotic arms) even though integration is a work-in-progress.

- System Coordination & Rendering
– Directory: src/system
– Key files: sceneSystem.ts, rendering.ts, thirdPersonCamera.ts, window.ts, playerOpacity.ts
– Role: Central coordination of the runtime environment. The SceneSystem, for example, organizes the simulation loop (runSimulationLoop) which calls input processing, physics updates, UI interactions, and renders the scene using Three.js.

- User Interface (UI)
– Directories: src/ui and src/css
– Key files: uiController.ts, dialogController.ts, and multiple CSS files (e.g., base.css, style.css)
– Role: Manage DOM interactions, overlays, dialogs, and other visual elements that support user control and system feedback.

##### Relationships and Interactions

- Flow from Initialization to Runtime:
– The entry point (index.html) loads main.ts, which kicks off the application by loading assets (via the asset management system) and initializing the simulation loop.

- Integration of Subsystems:
– The simulation loop in sceneSystem.ts orchestrates various subsystems:
- It drives input handling (via src/io) to capture keyboard and mouse events.
- Updates are forwarded to controllers (src/ctrl) to modify entity states (e.g., player, robotic arms, tables).
- The physics subsystem (src/physics) is stepped forward to update object dynamics.
- The rendering system (src/system and Three.js) refreshes the scene based on the new states.
- UI events and adjustments are managed in parallel (src/ui).

- Communication Patterns:
– Use of an event bus and mediator (src/io/eventBus and src/ctrl/eventMediator) suggests loose coupling between system modules.
– Data flows from input to controllers, then to the simulation state/physics, and finally to rendering.

##### Architectural Patterns and Technologies

- Modular design: The project is separated into distinct domains (assets, controllers, physics, UI, etc.) each encapsulated in its own directory.
- Simulation loop: The continuous “runSimulationLoop” method (requestAnimationFrame-driven) that integrates input, physics, and rendering.
- Event-driven communication: Both the “EventMediator” and “EventBus” components underscore a decoupled event-driven architecture.
- Use of Vite for fast bundling and development, ensuring that changes across these systems are quickly reflected during development.
- Three.js based rendering is foundational for the 3D visualization; Ammo.js provides the physics simulation (albeit with custom scripts and workarounds for URDF integration).

##### Summarize the Essential Elements

– Main entry: index.html and src/main.ts
– Initialization: Asset loading (src/assets), setup and factories (src/setup)
– Core simulation loop: SceneSystem (src/system/sceneSystem.ts) coordinating input, physics (src/physics), controllers (src/ctrl), and UI (src/ui)
– External interfaces: User inputs (src/io) and DOM based UI (HTML + CSS)
– Architectural patterns: Modular design, event-driven communication and simulation loop.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Subgraph: Initialization
    subgraph "Initialization"
        idx["index.html"]:::init
        main["src/main.ts"]:::init
        idx --> main
    end

    %% Subgraph: Asset Management
    subgraph "Asset Management"
        assets["src/assets"]:::asset
        assetLoader["AssetLoader (src/assets/assetLoader.ts)"]:::asset
        animLoader["AnimationLoader (src/assets/animationLoader.ts)"]:::asset
        modelLoader["ModelLoader (src/assets/modelLoader.ts)"]:::asset
        urdfLoader["URDF Loader (src/assets/urdf.ts)"]:::asset
        assets --> assetLoader
        assets --> animLoader
        assets --> modelLoader
        assets --> urdfLoader
    end

    %% Subgraph: Controllers & Input Handling
    subgraph "Controllers & Input Handling"
        subgraph "Controllers (src/ctrl)"
            playerCtrl["PlayerController (src/ctrl/playerController.ts)"]:::ctrl
            cameraCtrl["CameraController (src/ctrl/cameraController.ts)"]:::ctrl
            evtMediator["EventMediator (src/ctrl/eventMediator.ts)"]:::ctrl
        end
        subgraph "Input (src/io)"
            inputListener["InputListener (src/io/inputListener.ts)"]:::ctrl
            keyboard["Keyboard (src/io/keyboard.ts)"]:::ctrl
            mouse["Mouse (src/io/mouse.ts)"]:::ctrl
        end
    end

    %% Subgraph: Entity & Setup Management
    subgraph "Entity & Setup Management"
        subgraph "Entities (src/entity)"
            entity["Entity (src/entity/entity.ts)"]:::entity
            armState["ArmState (src/entity/armState.ts)"]:::entity
        end
        subgraph "Setup (src/setup)"
            actorFactory["ActorFactory (src/setup/actorFactory.ts)"]:::entity
            roomObjFactory["RoomObjectFactory (src/setup/roomObjectFactory.ts)"]:::entity
            constants["Constants (src/setup/constants.ts)"]:::entity
        end
    end

    %% Subgraph: Physics Simulation
    subgraph "Physics Simulation"
        subgraph "Physics (src/physics)"
            physicsSys["PhysicsSystem (src/physics/physicsSystem.ts)"]:::physics
            physicsWorld["PhysicsWorld (src/physics/physicsWorld.ts)"]:::physics
            physicsSync["PhysicsSync (src/physics/physicsSync.ts)"]:::physics
        end
    end

    %% Subgraph: System Coordination & Rendering
    subgraph "System Coordination & Rendering"
        subgraph "System (src/system)"
            sceneSystem["SceneSystem (src/system/sceneSystem.ts)"]:::system
            rendering["Rendering (src/system/rendering.ts)"]:::system
            thirdPersonCam["ThirdPersonCamera (src/system/thirdPersonCamera.ts)"]:::system
            windowSys["Window (src/system/window.ts)"]:::system
            playerOpacity["PlayerOpacity (src/system/playerOpacity.ts)"]:::system
        end
    end

    %% Subgraph: User Interface (UI)
    subgraph "User Interface (UI)"
        subgraph "UI Components (src/ui)"
            uiCtrl["UIController (src/ui/uiController.ts)"]:::ui
            dialogCtrl["DialogController (src/ui/dialogController.ts)"]:::ui
            uiMediator["UIMediator (src/ui/uiMediator.ts)"]:::ui
        end
        subgraph "CSS (src/css)"
            baseCSS["base.css (src/css/base.css)"]:::css
            dialogCSS["dialog.css (src/css/dialog.css)"]:::css
            overlayCSS["overlay.css (src/css/overlay.css)"]:::css
            physicsCSS["physics.css (src/css/physics.css)"]:::css
            styleCSS["style.css (src/css/style.css)"]:::css
            variablesCSS["variables.css (src/css/variables.css)"]:::css
        end
    end

    %% Main Flow Connections
    main --> assets
    main --> sceneSystem
    assets --> sceneSystem
    sceneSystem --> playerCtrl
    sceneSystem --> cameraCtrl
    sceneSystem --> evtMediator
    sceneSystem --> inputListener
    sceneSystem --> keyboard
    sceneSystem --> mouse
    sceneSystem --> physicsSys
    sceneSystem --> physicsWorld
    sceneSystem --> physicsSync
    sceneSystem --> uiCtrl
    sceneSystem --> dialogCtrl
    sceneSystem --> uiMediator
    sceneSystem --> entity
    sceneSystem --> armState
    sceneSystem --> actorFactory
    sceneSystem --> roomObjFactory
    sceneSystem --> constants

    %% Feedback Loop from Physics to Controllers
    physicsSys -->|"feedback"| playerCtrl

    %% Styling Classes
    classDef init fill:#d3a4ff,stroke:#333,stroke-width:1px;
    classDef asset fill:#a8e6cf,stroke:#333,stroke-width:1px;
    classDef ctrl fill:#77dd77,stroke:#333,stroke-width:1px;
    classDef entity fill:#cbea9e,stroke:#333,stroke-width:1px;
    classDef physics fill:#89CFF0,stroke:#333,stroke-width:1px;
    classDef system fill:#6495ED,stroke:#333,stroke-width:1px;
    classDef ui fill:#ffcccb,stroke:#333,stroke-width:1px;
    classDef css fill:#ffe5b4,stroke:#333,stroke-width:1px;

    %% Click Events for Initialization
    click idx "https://github.com/aicell-lab/micro-farm-js/blob/main/index.html"
    click main "https://github.com/aicell-lab/micro-farm-js/blob/main/src/main.ts"

    %% Click Events for Asset Management
    click assets "https://github.com/aicell-lab/micro-farm-js/tree/main/src/assets"
    click assetLoader "https://github.com/aicell-lab/micro-farm-js/blob/main/src/assets/assetLoader.ts"
    click animLoader "https://github.com/aicell-lab/micro-farm-js/blob/main/src/assets/animationLoader.ts"
    click modelLoader "https://github.com/aicell-lab/micro-farm-js/blob/main/src/assets/modelLoader.ts"
    click urdfLoader "https://github.com/aicell-lab/micro-farm-js/blob/main/src/assets/urdf.ts"

    %% Click Events for Controllers & Input Handling
    click playerCtrl "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ctrl/playerController.ts"
    click cameraCtrl "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ctrl/cameraController.ts"
    click evtMediator "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ctrl/eventMediator.ts"
    click inputListener "https://github.com/aicell-lab/micro-farm-js/blob/main/src/io/inputListener.ts"
    click keyboard "https://github.com/aicell-lab/micro-farm-js/blob/main/src/io/keyboard.ts"
    click mouse "https://github.com/aicell-lab/micro-farm-js/blob/main/src/io/mouse.ts"

    %% Click Events for Entity & Setup Management
    click entity "https://github.com/aicell-lab/micro-farm-js/blob/main/src/entity/entity.ts"
    click armState "https://github.com/aicell-lab/micro-farm-js/blob/main/src/entity/armState.ts"
    click actorFactory "https://github.com/aicell-lab/micro-farm-js/blob/main/src/setup/actorFactory.ts"
    click roomObjFactory "https://github.com/aicell-lab/micro-farm-js/blob/main/src/setup/roomObjectFactory.ts"
    click constants "https://github.com/aicell-lab/micro-farm-js/blob/main/src/setup/constants.ts"

    %% Click Events for Physics Simulation
    click physicsSys "https://github.com/aicell-lab/micro-farm-js/blob/main/src/physics/physicsSystem.ts"
    click physicsWorld "https://github.com/aicell-lab/micro-farm-js/blob/main/src/physics/physicsWorld.ts"
    click physicsSync "https://github.com/aicell-lab/micro-farm-js/blob/main/src/physics/physicsSync.ts"

    %% Click Events for System Coordination & Rendering
    click sceneSystem "https://github.com/aicell-lab/micro-farm-js/blob/main/src/system/sceneSystem.ts"
    click rendering "https://github.com/aicell-lab/micro-farm-js/blob/main/src/system/rendering.ts"
    click thirdPersonCam "https://github.com/aicell-lab/micro-farm-js/blob/main/src/system/thirdPersonCamera.ts"
    click windowSys "https://github.com/aicell-lab/micro-farm-js/blob/main/src/system/window.ts"
    click playerOpacity "https://github.com/aicell-lab/micro-farm-js/blob/main/src/system/playerOpacity.ts"

    %% Click Events for User Interface (UI)
    click uiCtrl "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ui/uiController.ts"
    click dialogCtrl "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ui/dialogController.ts"
    click uiMediator "https://github.com/aicell-lab/micro-farm-js/blob/main/src/ui/uiMediator.ts"
    click baseCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/base.css"
    click dialogCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/dialog.css"
    click overlayCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/overlay.css"
    click physicsCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/physics.css"
    click styleCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/style.css"
    click variablesCSS "https://github.com/aicell-lab/micro-farm-js/blob/main/src/css/variables.css"
```
