Architecture

Phase 12 evidence boundary

Physical validation is stored outside research datasets in a versioned, public-safe package. Shared models enforce exact states and evidence requirements; DatasetManager validates summaries and release gates. Human confirmation is required to change a result, and Passed states require evidence. Automated tests cannot write a physical Passed result. Original footage, signing assets, pairing secrets, and precise locations are excluded.

Phase 11 hardening boundaries

SharedModels owns Sendable diagnostic, privacy, benchmark, resource-policy, and typed-error values. DatasetManager supplies actor-isolated bounded queues, injected storage quotas, safeguard simulation, fixture orchestration, and redacted diagnostic export. SharedUI renders status but contains no core validation logic. Machine-readable boundaries prevent prohibited framework and ownership drift. Original media remains immutable and physical results never default to Passed.

Phase 10 keeps device-specific logic in CameraSources: recorded-media and optional connection adapters emit versioned SharedModels, while catalog persistence, analysis, annotations, experiments, and SwiftUI remain separate. Raw telemetry and immutable sources are preserved beside derived normalized samples, synchronization transforms, calibration/profile references, validation findings, and proxies.

Phase 9 extends the existing dependency direction without replacing prior storage: SharedModels owns experiment contracts; FeatureExtraction owns deterministic extractors and transparent fusion; DatasetManager owns ground-truth selection, splits, metrics, cache, state, and atomic experiment storage; ExportEngine owns classical-ML and research reports; PluginSDK defines bounded research extension interfaces; and SharedUI presents iPad/macOS research workspaces plus the iPhone monitor.

Phase 6 review layer

ResearchDashboardModels defines summaries, bookmarks, warnings, timeline events, inspector summaries, run differences, typed dashboard errors, and screenshot metadata. ResearchDashboardServices aggregates existing catalog and analysis indexes without changing their formats. ResearchDashboardView consumes those boundaries for adaptive iPad/macOS presentation. Deterministic demonstration data is opt-in and never reads private user storage.

The original session and source video remain immutable. Bookmarks and verification are review metadata. Dashboard summaries, charts, timelines, and comparisons are derived views. Screenshot validation belongs to DatasetManager; the native screenshot renderer depends on SharedUI but no app module depends on the renderer.

OrganicVision uses local Swift Package Manager modules behind public protocols. SharedModels owns stable value types. CameraSources exposes source adapters that produce VisionFrame metadata. DetectionEngine emits observations, TrackingEngine stabilizes identities, and FeatureExtraction creates research features. DatasetManager owns actor-isolated state; AnnotationEngine validates edits; ExportEngine serializes snapshots. Networking and PluginSDK define extension seams, while SharedUI supplies injected, platform-specific foundation screens.

Pixel data is deliberately referenced rather than embedded in shared models. Platform capture implementations can own CVPixelBuffer lifetimes and pass durable references into the research pipeline without making the core depend on AVFoundation.

Extension points

• Implement VisionDetector for Vision or Core ML inference.
• Implement VisionPlugin to package experimental detectors with metadata.
• Implement FrameTransport for peer or server delivery.
• Serialize DatasetSnapshot for durable storage and reproducible exports.

AppDependencies.phaseOne is the composition root demonstrated by the three apps. It registers visible status descriptors without hiding production behavior behind mocks. Phase 1 hardware adapters return CapabilityResult.unsupported, while deterministic simulators return available.

Phase 2 recording flow

CameraNodeViewModel composes SessionRecordingCoordinator with a CameraRecordingService, SensorCollecting, and ResearchSessionStore. Device builds receive PhysicalCameraRecordingService and PhysicalSensorCollector; simulator builds receive deterministic adapters. The coordinator owns legal recording transitions and finalizes a versioned manifest. The store actor owns incremental JSONL writes, path validation, recovery, available-space policy, export, and active-session deletion protection.

AVFoundation/Core Location/Core Motion remain inside CameraSources. This is an important Phase 3 boundary: networking may consume finalized SessionPackage metadata and relative files, but must not import camera frameworks or mutate active package files.

Phase 3 networking

Networking owns Bonjour discovery/advertising, Network.framework byte transport, CryptoKit identity agreement and authenticated encryption, Keychain abstractions, the versioned message envelope, pairing/trust, capability negotiation, heartbeat/reconnect policy, telemetry throttling, remote authorization, and preview-quality adaptation. SharedUI composes these services into iPhone connection status and the iPad Research Console.

The physical socket layer sends bounded, length-framed messages sealed with ChaChaPoly under a Curve25519-derived key after explicit code-verified pairing. It does not invent cryptographic primitives or bypass system trust. Private keys and persistent pairing records use device-only Keychain storage. The deterministic simulator lab uses the same state, policy, protocol, and crypto components without requiring external networking.

Networking controls recording only through AuthoritativeRecordingControlling. It has no dependency on CameraSources or DatasetManager and cannot delete or rewrite sessions. Connection loss changes console state while the authoritative iPhone recording continues.

Phase 7 annotation boundary

SharedModels defines annotation projects, human records, revisions, review comments, corrected tracks, interpolation metadata, datasets, splits, privacy options, and validation reports. AnnotationEngine owns geometry validation, edit history, undo/redo, track correction, JSONL autosave, and recovery. ExportEngine owns deterministic group-aware splitting, extraction records, validation, and training export representations. Human records reference AI identifiers but never mutate AI results or source media.

Phase 8 assistance boundary

SharedModels owns versioned suggestion, provenance, prompt, mask, quality, priority, disagreement, job, metrics, model, and export-origin values. AnnotationEngine creates deterministic suggestions and owns explicit review transitions, mask editing and integrity, temporal propagation suggestions, explainable prioritization, disagreement calculations, quality rules, batch revision events, and job checkpoints. It cannot mutate source media, AI analysis, or historical revisions.

PluginSDK exposes type-specific, cancelable async suggestion and quality protocols. Outputs are bounded and validated before use; plugins never receive a verified-storage writer. ExportEngine filters approved annotations by default and emits an origin manifest. SharedUI renders platform-appropriate tools but does not own persistence or inference.

Phase 4 dataset boundary

DatasetCatalog is an actor in DatasetManager; camera and networking code never own it. A versioned JSON repository stores metadata atomically and backs up before migration. Package validation, indexing, integrity, duplicate assessment, export, and deletion guards are separate services. Networking carries finalized-package chunks and checkpoints only; catalog insertion happens after transfer assembly, SHA-256 verification, and validation.

The catalog receives time, identifiers, hashing, storage reporting, transfer, and background scheduling through protocols. It does not import AVFoundation, Network.framework, Core Motion, Core Location, Vision, or Core ML.

Phase 5 analysis boundary

DetectionEngine owns detector/model-registry abstractions and conditional Vision/Core ML conversion. TrackingEngine consumes framework-independent normalized observations. FeatureExtraction produces region measurements and replaceable score fusion. DatasetManager stores shared analysis models and JSONL only; it imports no Vision, Core ML, AVFoundation, Accelerate, or Metal. SharedUI renders semantic overlays but contains no pipeline implementation.

Live analysis is sampled and resource-aware. Offline analysis uses .processing directories and hash-bound checkpoints, then atomically finalizes immutable runs. Networking sends bounded observation/track/status batches through the existing authenticated protocol and never owns result storage.