How pocket/pocket-ios works
Project Type & Purpose
This is a full-stack native iOS client for the Pocket service. It includes:
• The main Pocket iOS app (UIKit + SwiftUI)
• Multiple internal frameworks (“kits”) for UI, data sync, styling, analytics, share extension, etc.
• Several Apple extension targets (Share Extension, Push Notification Service, Notification Content, Widget, iMessage).
• A GraphQL API layer (Apollo) and offline storage layer (Core Data via Sync).
• An analytics pipeline (Snowplow).
Key Architectural Components
A. App Targets (Containers)
• Pocket iOS App
• SaveToPocket Share Extension
• PushNotificationServiceExtension
• PushNotificationStoryExtension
• ItemWidgets Widget Extension
• iMessageExtension
B. Internal Frameworks (Containers)
• PocketKit – UI entry points (AppDelegate, ViewControllers, ViewModels, routing)
• Sync – Networking (Apollo GraphQL client), Core Data stack, data mapping, offline sync
• PocketGraph – Generated GraphQL fragments, operations, schema types
• Analytics – Snowplow tracker implementations
• SaveToPocketKit – Share extension logic
• SharedPocketKit – Session management, keychain, app-group utilities, shared models
• PocketStickerKit – iMessage stickers integration
C. External Services & Systems
• Pocket API (GraphQL endpoint)
• Snowplow Micro (analytics collector during tests)
• Apple Push Notification Service (APNs)
• WidgetKit timeline provider
• Core Data local persistent store
Relationships & Data Flow
• UI Layer (UIKit/SwiftUI screens & widgets) invokes ViewModels in PocketKit
• ViewModels call services (protocol-oriented) defined in PocketKit or SaveToPocketKit
• Services delegate to Sync:
– ApolloClient fetches/mutates data against PocketGraph → Pocket API
– Sync maps API responses into Core Data (PersistentContainer)
– Persistent store feeds back to UI via fetched-results or Combine publishers
• Analytics module intercepts user events → sends to Snowplow (HTTP)
• Extensions reuse SharedPocketKit + other frameworks, share Core Data container & configurations
• WidgetKit extension polls Sync (via ItemWidgetsService) to update timelines
Architectural Patterns & Principles
• Modularization: each “kit” is an independent Swift package or framework
• MVVM: ViewControllers/Views ↔ ViewModels ↔ Services ↔ Data layer
• Protocol-oriented: Services (e.g., SlateService, AuthenticationSession) are injected via protocols
• Code Generation: Apollo CLI generates PocketGraph code from schema & .graphql files
• Offline-First: Sync library with Core Data persistence & background refresh coordinators
• Single Responsibility: each framework/extension has a clear domain (UI, Styling, Sync, Analytics, Extension)
Detail & Coverage
• Every essential framework and extension in the codebase
• How codegen (PocketGraph) feeds into Sync and then into UI
• Background refresh coordinators, widget timeline updates
• Don’t overthink – break the system into all major kits, targets, services, and external systems