System Overview
A secure, local-first engine for tracking work activity. Realwork runs in the background, creating a cryptographically signed proof of your hours without invading your privacy.
Architecture
Component Interaction Matrix
Realwork separates the recording engine (ScreenCaptureKit) from the main interface. This ensures recording has almost zero impact on system performance—using less than 0.3% CPU on Apple Silicon.
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, we capture high-quality snapshots at 1-second intervals. This allows us to verify each frame securely before saving it.
// 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 Fingerprinting: Before encoding, the raw CMSampleBuffer is hashed (SHA256). This hash is added to the session manifest.
- 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
When you first start the app, it creates a unique private key inside your Mac's secure hardware (Secure Enclave). This key identifies your device and never leaves it.
Block-Level Signing
Every 5 minutes, a SessionBlock is saved. The app uses your private key to digitally sign this block, proving it hasn't been tampered with.
Unbreakable Chain
Each block contains the ID of the previous block, forming a chain. If any past block is deleted or changed, the entire chain becomes invalid.
struct SessionBlock: Codable {
let sequenceID: Int
let timestamp: Date
let duration: TimeInterval
// Integrity
let contentHash: String // SHA256 of video segment
let prevBlockHash: String // Hash of block[n-1]
let signature: Data // ECDSA-P256 signature
}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 secure video containers. They are encrypted so they can only be played back within the Realwork app, ensuring the verification data stays attached to the video.
Network Protocols
Upload & Authentication
Local Authentication
To keep your credentials secure, the app opens your system browser (Chrome/Safari) to log you in, rather than asking for your password directly in the app.
- App opens a temporary local port
- You log in securely in the browser
- Browser sends the secure token back to the app
- App saves the token and closes the port
Direct Uploads
We use Cloudflare R2 for fast global storage. When you publish, your files are uploaded directly from your Mac to the storage server—they never pass through our main web server.
Header: Authorization: AWS4-HMAC-SHA256