HyperbasisHyperbasisDocs
Home

Architecture

Understand how Hyperbasis organizes and persists spatial data.

Overview

┌─────────────────────────────────────────────────────────────┐
│                      Your AR App                            │
├─────────────────────────────────────────────────────────────┤
│                    Hyperbasis SDK                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   HBSpace   │  │  HBAnchor   │  │     HBStorage       │  │
│  │  (Model)    │  │   (Model)   │  │  (Persistence API)  │  │
│  └─────────────┘  └─────────────┘  └──────────┬──────────┘  │
│                                               │              │
│  ┌─────────────┐  ┌─────────────┐             │              │
│  │ HBTimeline  │  │   HBDiff    │─────────────┤              │
│  │ (History)   │  │ (Changes)   │             │              │
│  └─────────────┘  └─────────────┘             │              │
│                    ┌──────────────────────────┼───────────┐  │
│                    │                          │           │  │
│              ┌─────▼─────┐            ┌───────▼───────┐   │  │
│              │HBLocalStore│           │ HBCloudStore  │   │  │
│              │(FileManager)│          │  (Supabase)   │   │  │
│              └─────┬─────┘            └───────┬───────┘   │  │
│                    │                          │           │  │
│              ┌─────▼──────────────────────────▼─────┐     │  │
│              │          HBCompression (zlib)        │     │  │
│              └──────────────────────────────────────┘     │  │
└─────────────────────────────────────────────────────────────┘

Core Components

Models

ComponentPurpose
HBSpaceContainer for ARWorldMap + metadata
HBAnchor3D transform + custom metadata for placed objects
AnyCodableValueType-erased value for flexible metadata
HBAnchorEventImmutable record of anchor changes
HBTimelineHistory navigation and state reconstruction
HBDiffComparison between two points in time

Storage

ComponentPurpose
HBStorageMain persistence API
HBLocalStoreFileManager-based local persistence
HBCloudStoreSupabase cloud sync (optional)
HBCompressionZlib compression utilities

Data Flow

Save Flow

ARWorldMap → HBSpace.serialize() → HBCompression.compress()
→ HBLocalStore.saveSpace() → [optional] HBCloudStore.uploadSpace()
  1. •ARWorldMap is serialized using NSKeyedArchiver
  2. •Data is compressed with zlib (~40% size reduction)
  3. •Saved to local file system
  4. •Optionally synced to cloud

Load Flow

HBLocalStore.loadSpace() → HBCompression.decompress()
→ HBSpace.deserialize() → ARWorldMap → ARSession.run(initialWorldMap:)
  1. •Load compressed data from local storage
  2. •Decompress
  3. •Deserialize to ARWorldMap
  4. •Use for relocalization

Anchor Flow

simd_float4x4 → HBAnchor.flatten() → JSON encode
→ HBLocalStore.saveAnchor() → [optional] HBCloudStore.uploadAnchor()

Anchors store transforms as flat arrays of 16 floats (column-major order).

Event Flow

Every anchor modification is recorded:

save(anchor) → detect change type → append HBAnchorEvent → save anchor state
              │                    │
              ├─ new anchor       → created event
              ├─ transform changed → moved event
              ├─ metadata changed → updated event
              ├─ deleted          → deleted event
              └─ restored         → restored event

Events are stored in append-only JSONL files (one per space).

File Structure

Local storage location:

~/Documents/Hyperbasis/
├── spaces/
│   ├── {uuid}.json           # Space metadata + compressed worldMapData
│   └── ...
├── anchors/
│   ├── {uuid}.json           # Anchor data
│   └── ...
├── events/                   # Event logs for versioning
│   └── {spaceId}/
│       └── events.jsonl      # Append-only event log
├── pending_operations.json   # Queue for failed cloud operations
└── sync_metadata.json        # Last sync timestamp

Key Design Decisions

Why Flat Transform Arrays?

The 4x4 transformation matrix is stored as 16 floats rather than nested arrays because:

  • •Direct mapping to simd_float4x4 memory layout
  • •Efficient JSON serialization
  • •Column-major order matches GPU conventions

Why Soft Delete for Anchors?

Anchors use soft delete (deletedAt timestamp) rather than hard delete to:

  • •Enable undo functionality
  • •Support sync conflict resolution
  • •Allow historical queries

Why Compress World Maps?

ARWorldMap data is typically 5-50MB. Compression provides:

  • •~40% size reduction
  • •Faster cloud upload/download
  • •Reduced storage costs

Why Event Sourcing for Versioning?

Events provide:

  • •Immutable history - Events are append-only, never modified
  • •Small storage - Events are 200-500 bytes vs 5-50MB snapshots
  • •Flexible queries - Reconstruct state at any point in time
  • •Audit trail - Know exactly what changed and when

Next Steps