# shopify/tracky architecture

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

- Interactive diagram: https://gitdiagram.com/shopify/tracky
- Repository: https://github.com/shopify/tracky

## Overview

##### Project type and purpose
- This is a two-part AR capture and reconstruction tool:
- An iOS application (“Tracky”) written in Swift that uses ARKit, AVFoundation, and custom writer modules to record AR sessions into a single “.bren” container file.
- A Blender add-on written in Python (“bren_importer.py”) that parses the .bren file and rebuilds the recorded scene inside Blender.
- The README confirms its purpose: capture LiDAR depth, segmentation masks, orientation streams, stereo audio, and detected planes on an iPhone/iPad, then reconstruct the session in Blender for rapid AR prototyping.

##### File structure
- Top-level:
- .github – CI/CLA checks & Dependabot
- BlenderPlugin/bren_importer.py – the Python add-on for Blender
- Tracky/ – Xcode project and Swift source
- readme_images/ – tutorial assets
- Inside Tracky/Tracky:
- AppDelegate.swift, ViewController.swift – UI & app lifecycle
- DataSession.swift, VideoSession.swift – capture and write streams
- Bren.swift – likely handles serialization of all streams into .bren
- Assets.xcassets, Storyboards – UI & launch screens
- Configuration: Info.plist, Xcode workspace files.

##### Key insights from README
- Workflow: Launch app ➔ record AR session ➔ Files app export of .bren ➔ Blender import via plugin
- Dependencies:
- iOS: Xcode 14.2+, device with LiDAR
- Blender: 2.92+, Python add-on
- No built-in network or backend – purely local file I/O and desktop integration.

##### Main components
a. Mobile App (iOS)
- UIKit front end (ViewController + Storyboards)
- ARKit session for camera, LiDAR, and plane detection
- AVFoundation for stereo microphone audio capture
- DataSession & VideoSession classes orchestrate frame, depth, mask, orientation, and audio streams
- BrenWriter module (Bren.swift) serializes streams into a single .bren file on local storage
b. File Storage & Transfer
- Xcode sandbox / Files app on iOS
- User action to transfer .bren file to desktop (AirDrop, cloud, USB)
c. Blender Add-On (Desktop)
- Python script (bren_importer.py) – registered via Blender’s Add-Ons interface
- Parser for .bren container format
- Uses Blender’s bpy API to recreate scene:
- Meshes or point clouds from depth data
- Segmentation masks as materials or masks
- Audio as sound strips
- Animation keyframes from positional/orientation streams
d. Blender Runtime
- The actual Blender application where the scene is built and viewed

##### Relationships and data flow
1. User taps “Record” ➔ UI calls ARKit session
2. ARKit + AVFoundation ➔ raw frame, depth, mask, orientation, audio streams
3. Streams ➔ DataSession/VideoSession ➔ BrenWriter ➔ .bren file
4. .bren file ➔ exported via Files app ➔ Desktop file system
5. User opens Blender ➔ enables bren_importer add-on ➔ selects .bren file
6. Plugin parses ➔ creates Blender objects & timelines

##### Architectural patterns & design principles
- iOS side: MVC (ViewController + Storyboards), modular capture services (DataSession/VideoSession), single-responsibility for BrenWriter.
- Desktop side: plugin architecture following Blender’s add-on registration, separation of parsing logic and scene construction.
- File-based integration decouples mobile and desktop, no direct network dependencies.

##### Technologies & frameworks
- Swift, UIKit, ARKit, AVFoundation
- FileManager / Files app
- Python, Blender bpy API

- A sequencing or numbered data flow path to show how the user interaction triggers the full pipeline

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% iOS Application Subsystem
    subgraph "iOS App (Tracky)"
        direction TB
        MobileApp["Tracky iOS App"]:::mobile
        AppDelegate["AppDelegate.swift"]:::mobile
        ViewController["ViewController.swift"]:::mobile
        MainStoryboard["Main.storyboard"]:::mobile
        LaunchStoryboard["LaunchScreen.storyboard"]:::mobile
        Assets["Assets.xcassets"]:::mobile
        DataSession["DataSession.swift"]:::mobile
        VideoSession["VideoSession.swift"]:::mobile
        BrenWriter["Bren.swift"]:::mobile
        InfoPlist["Info.plist"]:::mobile
        EmptyUSDZ["empty.usdz"]:::mobile
    end

    %% External Frameworks for Mobile
    ARKit["ARKit"]:::external
    AVFoundation["AVFoundation"]:::external

    %% Storage
    BrenFile[".bren File"]:::storage

    %% File Transfer
    FilesApp["Files App / Transfer"]:::storage

    %% Blender Desktop Subsystem
    subgraph "Blender Desktop"
        direction TB
        BlenderApp["Blender Application"]:::desktop
        AddOn["bren_importer.py"]:::desktop
        Parser["Parser Module"]:::desktop
        BpyAPI["bpy API"]:::external
    end

    %% Mobile Data Flow
    MobileApp -->|"launches"| AppDelegate
    AppDelegate -->|"initializes UI"| ViewController
    ViewController -->|"start recording"| ARKit
    ViewController -->|"start audio capture"| AVFoundation
    ARKit -->|"depth, masks, orientation frames"| DataSession
    AVFoundation -->|"audio, video frames"| VideoSession
    DataSession -->|"streams data"| BrenWriter
    VideoSession -->|"streams audio/video"| BrenWriter
    BrenWriter -->|".bren container"| BrenFile
    BrenFile -->|"export .bren"| FilesApp
    FilesApp -->|"transfer file"| AddOn

    %% Desktop Import Flow
    AddOn -->|"parse .bren"| Parser
    Parser -->|"create meshes, masks, keyframes, audio strips"| BlenderApp
    Parser -->|"use bpy API"| BpyAPI
    BpyAPI -->|"build scene"| BlenderApp

    %% Click Events
    click MobileApp "https://github.com/shopify/tracky/blob/main/Tracky/Tracky.xcodeproj"
    click AppDelegate "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/AppDelegate.swift"
    click ViewController "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/ViewController.swift"
    click MainStoryboard "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/Base.lproj/Main.storyboard"
    click LaunchStoryboard "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/Base.lproj/LaunchScreen.storyboard"
    click Assets "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/Assets.xcassets"
    click DataSession "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/DataSession.swift"
    click VideoSession "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/VideoSession.swift"
    click BrenWriter "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/Bren.swift"
    click InfoPlist "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/Info.plist"
    click EmptyUSDZ "https://github.com/shopify/tracky/blob/main/Tracky/Tracky/empty.usdz"
    click AddOn "https://github.com/shopify/tracky/blob/main/BlenderPlugin/bren_importer.py"

    %% Styles
    classDef mobile fill:#AEDFF7,stroke:#000;
    classDef desktop fill:#C8E6A3,stroke:#000;
    classDef storage fill:#D3D3D3,stroke:#000,stroke-dasharray: 5 5;
    classDef external fill:#F5C78A,stroke:#000,stroke-dasharray: 2 2;
```
