# sycrus/math-heroes architecture

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

- Interactive diagram: https://gitdiagram.com/sycrus/math-heroes
- Repository: https://github.com/sycrus/math-heroes

## Overview

##### Project Type and Purpose
- This is a Unity‐based augmented-reality (AR) learning app (“Math Heroes”) built on top of the Vuforia AR SDK.
- Purpose: enable tangible, physical math exercises by detecting printed targets (planes, objects) through the device camera, then augmenting them with 3D models, equations, weights, and interactive logic.

##### High-Level Architectural Components
a. Hardware Layer
- Mobile device (iOS/Android) with camera, accelerometer, gyroscope
b. Unity Engine (Core Runtime)
- Rendering, physics, input, lifecycle management
c. Vuforia AR SDK Plugin
- Camera feed acquisition → image target detection → pose estimation
- Comes under Assets/Plugins and Assets/StreamingAssets/Vuforia
d. Scene & Asset Layer
- Assets/Scenes/MathHeroes.unity
- 3D Models (Assets/Models), Materials, Shaders (Assets/Vuforia/Shaders)
- Prefabs (Assets/Prefabs): numeric and weight objects
e. Resource & Configuration
- VuforiaConfiguration.asset (Assets/Resources)
- math_objects dataset (Assets/StreamingAssets/Vuforia)
f. Logic & Controllers
- Trackable event handlers (Assets/Vuforia/Scripts)
- Custom MonoBehaviour scripts (Assets/Scripts/Controllers & CollidersTriggers)
- EquationDisplay, TrackableList
g. Physics & Interaction
- Unity Physics (Asset PhysicsMaterials, colliders/triggers)
- WeightController, ZeroPairController, etc.
h. UI & Feedback
- On-screen equation text, rotation controls, visual highlights

##### Component Interactions and Data Flow
1. Device Camera → Unity’s ARCamera object (in scene)
2. ARCamera forwards video frames → Vuforia Plugin
3. Vuforia detects ImageTargets → raises OnTrackableFound/Lost events
4. DefaultTrackableEventHandler (Vuforia) → invokes custom controllers
5. Custom Controllers (EquationController, WeightController, etc.)
– Instantiate or update Prefabs (numbers, weights)
– Update UI via EquationDisplay
– Trigger physics simulations (add/remove weight objects)
6. Unity Physics Engine → resolves collisions/triggers → feedback loops back to scripts
7. Render pipeline → draws augmented 3D models blended with camera feed

##### Architectural Patterns & Principles
- Component-Based Architecture (Unity’s GameObject + MonoBehaviour)
- Event-Driven Design (trackable found/lost, trigger enter/exit)
- Separation of Concerns:
- Vuforia handles CV and pose estimation
- Unity core handles rendering & physics
- Custom scripts handle game logic

##### Technologies & Key Libraries
- Unity 2018+ (ProjectSettings, Packages/manifest.json)
- Vuforia Engine (Assets/Plugins, Assets/StreamingAssets)
- C# MonoBehaviour scripts
- Unity Physics & Cinemachine (implicit via Unity engine)
- Standard Unity UI system

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Hardware Layer"
        Device["Mobile Device (Camera, Accelerometer, Gyroscope)"]:::hardware
    end

    subgraph "Unity Engine (Core Runtime)"
        UnityCore["Unity Engine\n(Rendering, Physics, Input)"]:::unity
    end

    subgraph "Vuforia AR SDK Plugin"
        VuforiaPlugin["Vuforia AR SDK\n(Camera Feed Acquisition & Tracking)"]:::vuforia
        VuforiaEditor["Vuforia Editor Extensions"]:::vuforia
        VuforiaTextures["Vuforia ImageTarget Textures"]:::vuforia
        VuforiaData["Vuforia Targetset Data"]:::vuforia
        VuforiaShaders["Vuforia Runtime Shaders"]:::vuforia
        VuforiaScripts["DefaultTrackableEventHandler"]:::vuforia
        VuforiaInit["DefaultInitializationErrorHandler"]:::vuforia
        VuforiaStreaming["StreamingAssets Datasets"]:::vuforia
    end

    subgraph "Assets & Resources"
        Scene["MathHeroes.unity (Scene)"]:::assets
        Models["3D Models"]:::assets
        Materials["Materials & PhysicsMaterials"]:::assets
        Prefabs["Prefabs"]:::assets
        VuforiaConfig["VuforiaConfiguration.asset"]:::assets
    end

    subgraph "Scripts & Logic"
        Controllers["Custom Controllers\n(EquationController, WeightController, ZeroPairController, Rotate, XValue)"]:::logic
        Colliders["Collider/Trigger Scripts"]:::logic
        TrackableList["TrackableList"]:::logic
        EquationDisplay["EquationDisplay"]:::logic
    end

    subgraph "Physics & UI"
        Physics["Unity Physics Engine\n(Colliders, Rigidbodies)"]:::physics
        UI["UI & Feedback\n(On-screen Text, Highlights)"]:::physics
    end

    %% Data Flow
    Device --> UnityCore
    UnityCore --> VuforiaPlugin
    VuforiaPlugin --> Controllers
    VuforiaScripts --> Controllers
    VuforiaPlugin --> VuforiaInit
    Controllers --> Prefabs
    Controllers --> EquationDisplay
    Controllers --> Physics
    Physics --> Controllers
    UnityCore --> UI
    Scene -.-> UnityCore
    Models -.-> Prefabs
    Materials -.-> Physics
    VuforiaConfig --> VuforiaPlugin
    VuforiaStreaming --> VuforiaPlugin

    %% Click Events
    click VuforiaPlugin "https://github.com/sycrus/math-heroes/tree/master/Assets/Vuforia"
    click VuforiaEditor "https://github.com/sycrus/math-heroes/tree/master/Assets/Editor/Vuforia"
    click VuforiaTextures "https://github.com/sycrus/math-heroes/tree/master/Assets/Editor/Vuforia/ImageTargetTextures"
    click VuforiaData "https://github.com/sycrus/math-heroes/tree/master/Assets/Editor/Vuforia/TargetsetData"
    click VuforiaShaders "https://github.com/sycrus/math-heroes/tree/master/Assets/Vuforia/Shaders"
    click VuforiaScripts "https://github.com/sycrus/math-heroes/blob/master/Assets/Vuforia/Scripts/DefaultTrackableEventHandler.cs"
    click VuforiaInit "https://github.com/sycrus/math-heroes/blob/master/Assets/Vuforia/Scripts/DefaultInitializationErrorHandler.cs"
    click VuforiaStreaming "https://github.com/sycrus/math-heroes/blob/master/Assets/StreamingAssets/Vuforia/math_objects.dat"
    click Scene "https://github.com/sycrus/math-heroes/blob/master/Assets/Scenes/MathHeroes.unity"
    click Models "https://github.com/sycrus/math-heroes/tree/master/Assets/Models"
    click Materials "https://github.com/sycrus/math-heroes/tree/master/Assets/Materials"
    click Prefabs "https://github.com/sycrus/math-heroes/tree/master/Assets/Prefabs"
    click VuforiaConfig "https://github.com/sycrus/math-heroes/blob/master/Assets/Resources/VuforiaConfiguration.asset"
    click Controllers "https://github.com/sycrus/math-heroes/tree/master/Assets/Scripts/Controllers"
    click Colliders "https://github.com/sycrus/math-heroes/tree/master/Assets/Scripts/CollidersTriggers"
    click EquationDisplay "https://github.com/sycrus/math-heroes/blob/master/Assets/Scripts/EquationDisplay.cs"
    click TrackableList "https://github.com/sycrus/math-heroes/blob/master/Assets/Scripts/TrackableList.cs"

    %% Styles
    classDef hardware fill:#d3d3d3,stroke:#555,stroke-width:1px,rx:5,ry:5;
    classDef unity fill:#blue,stroke:#000,stroke-width:1px;
    classDef vuforia fill:#a5d6a7,stroke:#090,stroke-width:1px;
    classDef assets fill:#fff59d,stroke:#999,stroke-width:1px;
    classDef logic fill:#ffcc80,stroke:#f60,stroke-width:1px;
    classDef physics fill:#ce93d8,stroke:#705,stroke-width:1px;
```
