Repository Public
1<!--2SP Lecture Studio3File: docs/ARCHITECTURE.md4Author: Simon-Pierre Boucher5Contact: contact@spboucher.ai6-->7# Architecture89## Capability matrix (audited 2026-11-18 on the build machine)10| Item | Found | Decision |11|---|---|---|12| 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 |13| 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 |14| Simulators | iOS 26.5 runtime only | Dedicated devices "SPLecture iPhone" (iPhone 17 Pro) and "SPLecture iPad" (iPad Pro 13" M5) |15| Signing | Developer ID Application + Apple Development identities, team 3YM54G49SN | macOS: Developer ID + notarization; iOS: automatic signing + App Store Connect |16| Notarization | keychain profile `MacLustr-Notarize` | used as is by `scripts/notarize-macos.sh` |17| App Store Connect | API key in `~/.appstoreconnect/private_keys`, ids in `~/.config/splecturestudio/asc.env` (outside the repo) | used for provisioning, export, validation, upload |18| Real devices | none attached | Apple Pencil, real iPhone/iPad microphones, lock screen, phone calls: not tested |1920## Layers21```22App (SwiftUI) ── ProjectSession (live lecture) ── EditorModel ── ExportCoordinator23 │ platform adapters: macOS InkCanvasNSView (mouse/tablet) · iOS PencilStageView (PencilKit) · CameraPreview24LectureCapture RecordingClock · MicrophoneSource · SegmentedAudioWriter · RecordingEngine · CameraRecorder · Preflight25LectureRender FrameCompositor · TimelineAudioReader · EditedAudioRenderer · VideoExporter · MediaVerifier26LecturePDF SlideDocument · StrokeRenderer · AnnotatedPDFExporter27LectureTranscription / LectureSync optional services behind protocols28LectureStorage ProjectPackage · EventLogWriter · ProjectRecovery · Library · ZipArchive29LectureCore MediaTime · Stroke · TimelineEvent · TimelineIndex · EditDecisionList · TimeMap · analysis · AutoPauseEngine30```31Dependencies point downward only. Core has no framework dependency beyond Foundation and is fully unit-tested.3233## Key decisions341. **One timeline, in recorded time.** The timeline advances only while recording. A pause has zero length on the timeline and is35 stored as a `pause` / `resume(gapSeconds)` event pair with its exact wall-clock gap. Sessions are appended one after another.362. **The audio sample clock is the authority.** `RecordingClock` is re-anchored on every audio buffer (host time of the buffer ↔37 timeline position of its first sample), so events cannot drift from audio however long the session. Without audio it runs on the host clock.383. **State is a function of time.** `TimelineIndex` answers "what is on screen at t": page, visible strokes with partial progress,39 pointer, viewport, camera. The live canvas, the editor preview, the exporter and the annotated PDF all read that one model.404. **Edits are data.** An `EditDecisionList` (cuts, suggestions, mutes, fades, gain, chapters, ink adjustments) with a persisted41 undo/redo history. `TimeMap` converts between source and output time. Nothing ever rewrites media.425. **Preview = export.** The editor preview draws with `FrameCompositor` and plays audio pulled from `EditedAudioRenderer`, the43 same objects the exporter uses.446. **Vector ink with our own renderer.** Strokes are time-coded points in page-normalized coordinates. PencilKit is the input45 device on iPad/iPhone; replay, export and PDF use `StrokeRenderer` (Core Graphics), which is identical on every platform.46 Consequence: PencilKit's live rendering of its ink types differs slightly from the exported look.477. **No third-party dependency.** ZIP (store/deflate, ZIP64), tus upload, loudness metering are implemented in the packages.4849## Honest limits of the platforms50- iOS/iPadOS: recording continues in the background through the `audio` background mode; the camera cannot run in the51 background (its segment is closed and restarted on return). Without audio the app is suspended in the background, so a PDF-only52 session is paused when the app leaves the foreground. Unrestricted background recording is not promised.53- External display: a "presentation" window scene shows a clean stage. On macOS it can be placed on any display; on iPadOS it54 depends on Stage Manager / external display support of the device. Not tested on hardware.55- Screen / window capture on Mac (ScreenCaptureKit) is **not implemented**. The canonical video never comes from screen capture.56- Apple Pencil hover, pressure and palm rejection are provided by PencilKit; none of it can be verified in the simulator.57