System Overview
A local-first capture and publishing flow for documenting work activity. Realwork records selected windows, then lets you choose which work records to share. A published link is evidence of the captured process—not a guarantee of authorship or a cryptographic attestation.
Architecture
Component Interaction Matrix
Realwork separates the recording engine (ScreenCaptureKit) from the main interface. Capture load varies with the selected window, app, macOS version, and hardware; benchmark your own workflow rather than treating a fixed CPU figure as a guarantee.
User Interface (AppKit)
Manages windows and user commands. The FloatingPanel stays visible without stealing focus from your active apps.
Logic Layer (Core)
The SessionManager handles video capture, security hashing, and file saving. It acts as the single source of truth for all recordings.
Recording Pipeline
Frame Capture & Processing
Instead of recording a continuous video stream, the Mac app samples the selected window at roughly one-second intervals. Sampling makes the record lighter, but it also means gaps can exist and each frame should not be treated as independently verified.
// ScreenRecorder.swift: Discrete Frame Capture
private func setupStream() {
let config = SCStreamConfiguration()
config.width = Int(window.frame.width * 2) // Retina sampling
config.height = Int(window.frame.height * 2)
config.minimumFrameInterval = CMTime(value: 1, timescale: 1) // 1.0 Hz
config.pixelFormat = kCVPixelFormatType_32BGRA
// ... SCStream initialization
}- 01Window Isolation: Using SCContentFilter, we isolate only the target window ID. Notifications, wallpapers, and other apps are physically excluded from the buffer.
- 02Frame evidence: Frames are encoded into a local video artifact. The current published flow does not promise a hash for every frame, so viewers should treat the video as visual evidence rather than a frame-by-frame integrity proof.
- 03Temporal Compression: Frames are passed to AVAssetWriter configured with H.264 at a variable bitrate optimized for high-text-density content.
Security
Verification & Integrity
Security Model
Local Key Generation
The app captures a selected window locally. Published records may include metadata about that capture, but a local capture is not automatically a durable device identity.
Block-Level Signing
When you publish, media and session metadata are uploaded to storage. The upload confirms that a record was sent; it does not by itself prove that the media was never changed.
Verification boundary
A verifier should only use a “server-verified” label when the published manifest contains the required hashes, signatures, key metadata, and an explicit server result. Otherwise the honest status is “Captured record.”
{
"status": "captured",
"artifactHash": null,
"manifestHash": null,
"deviceKeyId": null,
"serverVerification": "not-verified"
}Data Persistence
Local File System Structure
Realwork keeps everything local by default. Data is stored in your computer's Application Support folder and is only uploaded when you choose to publish it.
Note: .rwd files are local video containers. Do not assume that a local file is encrypted or tamper-resistant; publish only the windows and sessions you are comfortable sharing.
Network Protocols
Upload & Authentication
Local Authentication
The app opens your system browser (Chrome/Safari) for account sign-in rather than asking for your password inside the desktop UI.
- App opens a temporary local port
- You log in securely in the browser
- Browser returns the login result to the app
- App saves the token and closes the port
Direct Uploads
When you publish, the app uploads media directly to object storage using a short-lived upload URL. The published privacy setting determines who should be able to discover the record; keep sensitive windows out of public captures.
Header: short-lived upload authorization