StokApp Technical Overview
System Architecture, Data Pipelines, & Integration Specification
The shape of the app for an engineer getting oriented — architecture, data flow, and integrations at a level that explains the design without doubling as a build spec.
Platform & Tech Stack
Core technologies powering StokApp across Apple platforms:
SwiftUI Codebase
Single unified codebase for macOS 14+, iOS 17+, iPadOS 17+ with narrowly-scoped #if os() platform branches.
SwiftData + CloudKit
All user data stored in SwiftData backed by CloudKit — one shared container per iCloud account.
Anthropic Messages API
Powers scan ranking, Chat, Deep Dive lenses, and Batch synthesis. Uses web_search tool for Research lens.
Pluggable Provider Layer
Decoupled market data interface supporting EODHD, Twelve Data, Finnhub, Alpha Vantage, and TASE Data Hub.
Zero Server Overhead
No third-party UI framework or bundled backend server; client talks directly to APIs, Gmail SMTP, and Webhooks.
Architecture at a Glance
StokApp follows a clean reactive architecture centered around a single shared AppState environment object. AppState owns a set of thin SwiftData reader/writer Stores and thin API client Services. No SwiftUI view talks to CloudKit or Anthropic directly.
Sync & Persistence Matrix
Where each data type lives and how it syncs across devices:
| Data Type | Sync Channel | Channel Detail & Security |
|---|---|---|
| Logged actions, positions (derived), watchlist (derived) | SwiftData / CloudKit | Synced automatically with last-write-wins conflict resolution across user devices. |
| Portfolio rules, target weights, universe, deep dives, batch reports, chat, briefs | SwiftData / CloudKit | Persisted in shared iCloud container for full read/write access everywhere. |
| App settings — model choice, enabled markets, delivery toggles | iCloud Key-Value Store | Lightweight settings sync across all signed-in iCloud devices. |
| Anthropic API key, provider credentials, SMTP password, webhook URL | iCloud Keychain | Encrypted using Safari-grade Keychain security, never stored in plain text. |
| Whole-market symbol pool, screener sweep cache, price history cache | Local Disk Only | Large, rebuildable caches stored locally per device and never synced over network. |
External Integrations
Direct integration endpoints used by StokApp:
| System | Used For | Notes & Capabilities |
|---|---|---|
| Anthropic Messages API | Scan ranking, Chat, Deep Dive, Batch synthesis | User-supplied key; Research lens & Batch use web_search tool |
| Market Data Providers (EODHD, Twelve Data, Finnhub, Alpha Vantage, TASE) | Quotes, historical price data, dividends | One credential per provider; auto-detects EOD vs Live capability |
| Gmail SMTP | Scheduled morning and close briefs | App-specific password, direct SMTP, no third-party email server |
| User Webhook | Optional brief delivery automation | Off by default; routes briefs into user's personal webhooks |
| Sparkle Framework | macOS app updates | EdDSA-signed appcast pointing to secure distribution binaries |
Constraints & Non-Goals
Single-User by Design
Sync is built exclusively for one person's own devices. No multi-user merge UI is required.
No Background Execution on iOS/iPadOS
Scheduled briefs are Mac-only. Phones and tablets run scans on-demand.
Never Executes a Trade
Intentionally contains zero brokerage integrations and zero order-placement code.
Provider-Dependent Data Quality
Coverage and field accuracy depend on the user's chosen market data provider.