# osv22/spatial-vacuum architecture

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

- Interactive diagram: https://gitdiagram.com/osv22/spatial-vacuum
- Repository: https://github.com/osv22/spatial-vacuum

## Overview

##### Project Type and Purpose
- Spatial Vacuum is an AR/VR iOS app (built with SwiftUI + RealityKit/ARKit) whose goal is to let users “vacuum” virtual coins in their real environment.
- It follows an MVVM‑style front end entwined with RealityKit’s ECS (Entity‑Component-System).

##### File Structure
- Top‑level:
- SpatialSweeper.xcodeproj + Info.plist → standard Xcode project files.
- SpatialSweeper/… → application code (SwiftUI views, view model, RealityKit controller, systems).
- Packages/RealityKitContent → a Swift Package containing 3D assets (.usdz, .usda), audio, materials, and the Package.swift manifest.
- AssetProjects/… → source .blend files for 3D models.
- Key patterns: MVVM in SwiftUI, RealityKit’s ECS for 3D content, use of a separate Swift Package for RealityKit assets.

##### README
- Confirms MVVM/RealityKit: mentions “SweeperRealityController,” hand‑tracking maintenance notes, and the coin‑collection logic.
- Credits point to external tutorials and asset origins but no additional sub‑services.

##### Main Components
a. SwiftUI Layer (Views + ViewModel)
- ContentView, HomeView, AboutView, custom View Components (buttons, selectors).
- AppViewModel: publishes UI state (selected vacuum type, score).
b. RealityKit / ARKit Layer
- SweeperRealityController: manages ARSession, anchors, entity creation/destruction.
- RotateSystem / RotateComponent: RealityKit ECS system for animating models.
- Hand‑tracking subsystem: processes ARFrame data, computes transforms for hand visualization.
c. Asset Package
- RealityKitContent Swift Package: holds assets (models, materials, sounds).
- Loaded at runtime by SweeperRealityController.
d. iOS Platform Services
- ARKit & camera feed
- Device sensors (motion, depth if available)
e. External Dependencies
- No remote web services; all logic and assets reside locally.

##### Model Interactions and Data Flow
- User taps PlayButton in SwiftUI → AppViewModel updates “isSessionRunning”
- AppViewModel notifies SweeperRealityController → starts ARSession
- SweeperRealityController loads assets from RealityKitContent → instantiates Entities in AR Scene
- ARKit delivers ARFrame to SweeperRealityController → hand tracking logic updates entity transforms (RotateSystem)
- Collision events (coin collected) → RealityKit notifies controller → AppViewModel increments score → SwiftUI updates scoreboard
- On ‘Real’ vacuum selection → scoreboard anchored to head instead of world.

##### Architectural Patterns
- MVVM: separation of View ↔ ViewModel ↔ Model/Controller
- RealityKit Entity‑Component‑System: discrete systems (RotateSystem) operate on components (RotateComponent)
- Modular asset distribution via Swift Package (RealityKitContent)

##### Essential Elements
- Annotations for special cases (e.g., “if Real vacuum: attach scoreboard to head anchor”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        direction TB
        AppEntry["SpatialSweeperApp"]:::ui
        ContentView["ContentView"]:::ui
        HomeView["HomeView"]:::ui
        AboutView["AboutView"]:::ui
        AboutButton["AboutButton"]:::ui
        CenteredTitle["CenteredTitle"]:::ui
        Faq["Faq"]:::ui
        PlayButton["PlayButton"]:::ui
        VacuumTypeSelection["VacuumTypeSelection"]:::ui
        AppViewModel["AppViewModel"]:::ui
    end

    subgraph "AR Core" 
        direction TB
        SweeperRealityController["SweeperRealityController"]:::core
        RotateSystem["RotateSystem"]:::core
        RotateComponent["RotateComponent"]:::core
        ARSession["ARSession"]:::core
    end

    subgraph "Assets & Platform Services"
        direction TB
        RealityKitPackage["RealityKitContent Package"]:::assets
        RealityKitLoader["RealityKitContent.swift"]:::assets
        AssetsDir["RealityKitContent.rkassets"]:::assets
        ARKitSensors[(ARKit & Sensors)]:::assets
    end

    %% UI Launch Flow
    AppEntry -->|"launches"| ContentView
    PlayButton -->|"startSession()"| AppViewModel
    AppViewModel -->|"startSession()"| SweeperRealityController

    %% AR Session & Asset Loading
    SweeperRealityController -->|"loadAssets()"| RealityKitLoader
    RealityKitLoader -->|"provides assets from"| AssetsDir

    %% AR Frame Updates
    ARKitSensors -.->|"onFrameUpdate()"| SweeperRealityController

    %% ECS Registration & Animation
    SweeperRealityController -->|"registerSystems()"| RotateSystem
    RotateSystem -->|"animates Entities with"| RotateComponent

    %% Collision & Score Update
    SweeperRealityController -->|"onCollision()"| AppViewModel
    AppViewModel -->|"scoreUpdate"| ContentView

    %% Bindings
    AppViewModel -->|"updates UI"| HomeView
    AppViewModel -->|"updates UI"| AboutView

    %% Click Events
    click ContentView "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/ContentView.swift"
    click HomeView "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/Views/HomeView.swift"
    click AboutView "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/Views/AboutView.swift"
    click AboutButton "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/View Components/AboutButton.swift"
    click CenteredTitle "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/View Components/CenteredTitle.swift"
    click Faq "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/View Components/Faq.swift"
    click PlayButton "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/View Components/PlayButton.swift"
    click VacuumTypeSelection "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/View Components/VacuumTypeSelection.swift"
    click AppEntry "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/SpatialSweeperApp.swift"
    click AppViewModel "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/AppViewModel.swift"
    click SweeperRealityController "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/SweeperRealityController.swift"
    click RotateSystem "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/RotateSystem.swift"
    click RotateComponent "https://github.com/osv22/spatial-vacuum/blob/main/SpatialSweeper/RotateComponent.swift"
    click RealityKitPackage "https://github.com/osv22/spatial-vacuum/blob/main/Packages/RealityKitContent/Package.swift"
    click RealityKitLoader "https://github.com/osv22/spatial-vacuum/blob/main/Packages/RealityKitContent/Sources/RealityKitContent/RealityKitContent.swift"
    click AssetsDir "https://github.com/osv22/spatial-vacuum/blob/main/Packages/RealityKitContent/Sources/RealityKitContent/RealityKitContent.rkassets"

    %% Styles
    classDef ui fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef core fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef assets fill:#FFE0B2,stroke:#F57C00,color:#E65100
```
