SPB Git

Repository Public

ARCHITECTURE.md 4.7 KB

# Architecture

# Capability matrix (audited 2026-11-18 on the build machine)

Item Found Decision
Xcode / Swift Xcode 27.2 (27B52), Swift 6.4.2 Swift 6 language mode for the pure packages (Core, Storage); Swift 5 mode for the AVFoundation / PDFKit / UI code
SDKs macOS 27.2, iOS 27.2 Deployment targets macOS 15.0 and iOS 18.0: the newest APIs used (AVAudioFile.close(), onScrollGeometryChange, Observation) exist there, and the only installed simulator runtime (iOS 26.5) can run the app
Simulators iOS 26.5 runtime only Dedicated devices "SPLecture iPhone" (iPhone 17 Pro) and "SPLecture iPad" (iPad Pro 13" M5)
Signing Developer ID Application + Apple Development identities, team 3YM54G49SN macOS: Developer ID + notarization; iOS: automatic signing + App Store Connect
Notarization keychain profile MacLustr-Notarize used as is by scripts/notarize-macos.sh
App Store Connect API key in ~/.appstoreconnect/private_keys, ids in ~/.config/splecturestudio/asc.env (outside the repo) used for provisioning, export, validation, upload
Real devices none attached Apple Pencil, real iPhone/iPad microphones, lock screen, phone calls: not tested

# Layers

text
App (SwiftUI)  ── ProjectSession (live lecture) ── EditorModel ── ExportCoordinator
   │ platform adapters: macOS InkCanvasNSView (mouse/tablet) · iOS PencilStageView (PencilKit) · CameraPreview
LectureCapture   RecordingClock · MicrophoneSource · SegmentedAudioWriter · RecordingEngine · CameraRecorder · Preflight
LectureRender    FrameCompositor · TimelineAudioReader · EditedAudioRenderer · VideoExporter · MediaVerifier
LecturePDF       SlideDocument · StrokeRenderer · AnnotatedPDFExporter
LectureTranscription / LectureSync   optional services behind protocols
LectureStorage   ProjectPackage · EventLogWriter · ProjectRecovery · Library · ZipArchive
LectureCore      MediaTime · Stroke · TimelineEvent · TimelineIndex · EditDecisionList · TimeMap · analysis · AutoPauseEngine

Dependencies point downward only. Core has no framework dependency beyond Foundation and is fully unit-tested.

# Key decisions

  1. One timeline, in recorded time. The timeline advances only while recording. A pause has zero length on the timeline and is stored as a pause / resume(gapSeconds) event pair with its exact wall-clock gap. Sessions are appended one after another.
  2. The audio sample clock is the authority. RecordingClock is re-anchored on every audio buffer (host time of the buffer ↔ timeline position of its first sample), so events cannot drift from audio however long the session. Without audio it runs on the host clock.
  3. State is a function of time. TimelineIndex answers "what is on screen at t": page, visible strokes with partial progress, pointer, viewport, camera. The live canvas, the editor preview, the exporter and the annotated PDF all read that one model.
  4. Edits are data. An EditDecisionList (cuts, suggestions, mutes, fades, gain, chapters, ink adjustments) with a persisted undo/redo history. TimeMap converts between source and output time. Nothing ever rewrites media.
  5. Preview = export. The editor preview draws with FrameCompositor and plays audio pulled from EditedAudioRenderer, the same objects the exporter uses.
  6. Vector ink with our own renderer. Strokes are time-coded points in page-normalized coordinates. PencilKit is the input device on iPad/iPhone; replay, export and PDF use StrokeRenderer (Core Graphics), which is identical on every platform. Consequence: PencilKit's live rendering of its ink types differs slightly from the exported look.
  7. No third-party dependency. ZIP (store/deflate, ZIP64), tus upload, loudness metering are implemented in the packages.

# Honest limits of the platforms

  • iOS/iPadOS: recording continues in the background through the audio background mode; the camera cannot run in the background (its segment is closed and restarted on return). Without audio the app is suspended in the background, so a PDF-only session is paused when the app leaves the foreground. Unrestricted background recording is not promised.
  • External display: a "presentation" window scene shows a clean stage. On macOS it can be placed on any display; on iPadOS it depends on Stage Manager / external display support of the device. Not tested on hardware.
  • Screen / window capture on Mac (ScreenCaptureKit) is not implemented. The canonical video never comes from screen capture.
  • Apple Pencil hover, pressure and palm rejection are provided by PencilKit; none of it can be verified in the simulator.
Files main
Menu

Theme