# yubeenpark/placesound architecture

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

- Interactive diagram: https://gitdiagram.com/yubeenpark/placesound
- Repository: https://github.com/yubeenpark/placesound

## Overview

##### Project type and purpose
- This is a Unity-based mobile AR (Augmented Reality) application (“placesound”) for Android.

##### File structure
- Top-level scripts: ARFeatheredPlaneMeshVisualizer, ArScenceManger, FadePlaneOnBoundaryChange – these hook into Unity’s AR Foundation to detect and render planes.
- managers/: orchestrates high-level behaviors (ARmanager, UIManager, SceneManger, CloudAnchorSessionManager, AzureAnchor, saveModel).
- SpatialAnchor/: demos and base classes for placing anchors, handling input, and tying into Azure Spatial Anchors.
- File/SaveData, SaveObject/: local persistence of placed objects and their transforms.
- Music/: UI and code for selecting, playing, and adjusting 3D spatial audio.
- Utility/: enums and helper methods (serialization, touch extensions, scenery utilities).

##### Key insights from README
- Technologies: Unity3D, ARCore, XR Foundation, Azure Spatial Anchors, C#.
- Runtime flow: user selects model → selects sound → taps to anchor in real world → sound plays/attenuates based on distance → user can save/load scenes.

##### Components
- AR Foundation / ARCore subsystem
- Azure Spatial Anchors client (CloudAnchorSessionManager, AzureAnchor)
- Scene & UI managers (SceneManger, UIManager, AppStateManagers)
- Audio subsystem (NativeMusic, MusicButton, SliderB, AddToList)
- Persistence (SaveDataManager, SaveModelManager, local file I/O)
- Utility layer (SceneryUtil, SerialiseTransformUtil, TouchExtension)
b. External services
- Azure Spatial Anchors service (cloud database of anchor IDs and transforms)
c. Device sensors & platform
- Mobile camera & IMU (via ARCore)
- Local file system on device
d. Data flows / interactions
1. App initializes AR Session → AR Foundation communicates with device sensors.
2. User taps screen → TouchExtension → PlaceObjectPlane / InputInteractionBase → SceneManger → ARmanager creates or finds anchor.
3. If “Save” → CloudAnchorSessionManager sends anchor to Azure → receives cloud anchor ID → SaveModelManager & SaveDataManager serialize transform & metadata to local or remote store.
4. On load → Data read from local file (ReadFile) → anchors rehydrated via Azure → ARmanager re-instantiates models.
5. Audio subsystem tracks each model’s transform → NativeMusic / AudioSource plays 3D sound → volume attenuation based on distance computed in code (e.g., TransformComponentDTO, SceneryUtil).

##### Architectural patterns & design principles
- Modular managers: each responsibility (AR, UI, Audio, Persistence) is isolated behind a manager class.
- Dependency inversion: high-level controllers (SceneManger, UIManager) interact with abstracted services (CloudAnchorSessionManager, SaveDataManager).
- Event-driven user interactions: InputInteractionBase / DemoScriptBase patterns.
- Serialization layer separating DTOs (TransformComponentDTO) from Unity components.

##### Detail without overcomplication
- Managers and utility layers that play a role in the runtime flow.
- Both local file persistence and cloud persistence paths.
- 3D audio computation as a feedback loop driven by model transforms.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Device Sensors & AR Foundation
    subgraph "Device Sensors & AR Foundation"
        direction TB
        CameraIMU["Camera & IMU"]:::arfoundation
        subgraph "ARFoundation Module"
            direction TB
            PlaneVisualizer["ARFeatheredPlaneMeshVisualizer"]:::arfoundation
            FadePlane["FadePlaneOnBoundaryChange"]:::arfoundation
            ARSceneMgr["ArScenceManger"]:::arfoundation
        end
    end

    %% Unity Application Layers
    subgraph "Unity Application"    
        direction TB

        subgraph "Presentation Layer"
            direction TB
            UIManager["UIManager"]:::unity
            MusicBtn["MusicButton"]:::unity
            SliderControl["SliderB"]:::unity
            PlaylistMgr["AddToLIst"]:::unity
        end

        subgraph "Domain Logic"
            direction TB
            SceneMgr["SceneManger"]:::unity
            ARManager["ARmanager"]:::unity
        end

        subgraph "Spatial Anchors"
            direction TB
            CloudSessionMgr["CloudAnchorSessionManager"]:::unity
            AzureAnchor["AzureAnchor"]:::unity
            NearbyDemo["AzureSpatialAnchorsNearbyDemoScript"]:::unity
        end

        subgraph "Persistence Layer"
            direction TB
            SaveDataMgr["SaveDataManager"]:::unity
            SaveDataModel["SaveData"]:::unity
            ReadFile["ReadFile"]:::unity
            SaveModelMgr["SaveModelManager"]:::unity
            SaveableObj["SaveableObject"]:::unity
        end

        subgraph "Utility Layer"
            direction TB
            TransformDTO["TransformComponentDTO"]:::unity
            SceneryUtil["SceneryUtil"]:::unity
            SerializeUtil["SerialiseTransformUtil"]:::unity
            TouchExt["TouchExtension"]:::unity
        end

        subgraph "Audio Subsystem"
            direction TB
            NativeAudio["NativeMusic"]:::unity
        end
    end

    %% External Services
    AzureService["Azure Spatial Anchors Service"]:::external

    %% Data Flows
    CameraIMU -->|"sensor data"| PlaneVisualizer
    PlaneVisualizer --> ARSceneMgr
    FadePlane --> ARSceneMgr

    ARSceneMgr -->|"init session"| SceneMgr

    TouchExt -->|"OnTap event"| SceneMgr
    SceneMgr -->|"PlaceObject"| ARManager

    ARManager -->|"Save anchor"| CloudSessionMgr
    CloudSessionMgr -->|"create anchor"| AzureService
    AzureService -->|"anchor ID"| CloudSessionMgr
    CloudSessionMgr -->|"anchor ID"| SceneMgr

    SceneMgr -->|"serialize transform"| SaveModelMgr
    SaveModelMgr --> SaveDataMgr
    SaveModelMgr --> SaveDataModel
    SaveModelMgr --> SaveableObj
    SaveDataMgr -->|"write file"| SaveDataModel

    ReadFile -->|"load metadata"| SceneMgr
    SceneMgr --> CloudSessionMgr
    CloudSessionMgr --> AzureService

    SceneMgr -->|"model transform"| TransformDTO
    TransformDTO --> NativeAudio
    NativeAudio -->|"3D audio"| PlaylistMgr
    NativeAudio -->|"volume calc"| SceneryUtil

    PlaylistMgr --> NativeAudio
    MusicBtn --> NativeAudio
    SliderControl --> NativeAudio

    %% Click Events
    click PlaneVisualizer "https://github.com/yubeenpark/placesound/blob/main/ARFeatheredPlaneMeshVisualizer.cs"
    click FadePlane "https://github.com/yubeenpark/placesound/blob/main/FadePlaneOnBoundaryChange.cs"
    click ARSceneMgr "https://github.com/yubeenpark/placesound/blob/main/ArScenceManger.cs"
    click CloudSessionMgr "https://github.com/yubeenpark/placesound/blob/main/managers/CloudAnchorSessionManager.cs"
    click AzureAnchor "https://github.com/yubeenpark/placesound/blob/main/managers/AzureAnchor.cs"
    click NearbyDemo "https://github.com/yubeenpark/placesound/blob/main/SpatialAnchor/AzureSpatialAnchorsNearbyDemoScript.cs"
    click SceneMgr "https://github.com/yubeenpark/placesound/blob/main/managers/SceneManger.cs"
    click UIManager "https://github.com/yubeenpark/placesound/blob/main/managers/UIManager.cs"
    click AppStateManagers "https://github.com/yubeenpark/placesound/blob/main/managers/AppStateManagers.cs"
    click NativeAudio "https://github.com/yubeenpark/placesound/blob/main/Music/NativeMusic.cs"
    click MusicBtn "https://github.com/yubeenpark/placesound/blob/main/Music/MusicButton.cs"
    click SliderControl "https://github.com/yubeenpark/placesound/blob/main/Music/SliderB.cs"
    click PlaylistMgr "https://github.com/yubeenpark/placesound/blob/main/Music/AddToLIst.cs"
    click SaveDataMgr "https://github.com/yubeenpark/placesound/blob/main/File/SaveDataManager.cs"
    click SaveDataModel "https://github.com/yubeenpark/placesound/blob/main/File/SaveData.cs"
    click ReadFile "https://github.com/yubeenpark/placesound/blob/main/File/ReadFile.cs"
    click SaveModelMgr "https://github.com/yubeenpark/placesound/blob/main/File/SaveObject/SaveModelManager.cs"
    click SaveableObj "https://github.com/yubeenpark/placesound/blob/main/File/SaveObject/SaveableObject.cs"
    click TransformDTO "https://github.com/yubeenpark/placesound/blob/main/TransformComponentDTO.cs"
    click SceneryUtil "https://github.com/yubeenpark/placesound/blob/main/Utility/SceneryUtil.cs"
    click SerializeUtil "https://github.com/yubeenpark/placesound/blob/main/Utility/SerialiseTransformUtil.cs"
    click TouchExt "https://github.com/yubeenpark/placesound/blob/main/Utility/TouchExtension.cs"

    %% Styling
    classDef arfoundation fill:#d0e7ff,stroke:#0366d6,color:#0366d6
    classDef unity fill:#e6ffed,stroke:#28a745,color:#28a745
    classDef external fill:#fff4e6,stroke:#d2691e,color:#d2691e
```
