# pocket/pocket-ios architecture

> Architecture diagram of the GitHub repository pocket/pocket-ios, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pocket/pocket-ios
- Repository: https://github.com/pocket/pocket-ios

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        PocketApp["Pocket iOS App"]:::presentation
        SaveExt["SaveToPocket Share Extension"]:::presentation
        PushServiceExt["PushNotificationServiceExtension"]:::presentation
        PushStoryExt["PushNotificationStoryExtension"]:::presentation
        ItemWidgetsExt["ItemWidgets Widget Extension"]:::presentation
        IMessageExt["iMessage Extension"]:::presentation
    end

    %% UI Frameworks
    subgraph "UI Frameworks"
        direction TB
        PocketKit["PocketKit"]:::framework
        Textile["Textile"]:::framework
        SaveKit["SaveToPocketKit"]:::framework
        StickerKit["PocketStickerKit"]:::framework
        ItemWidgetsKit["ItemWidgetsKit"]:::framework
    end

    %% Business Logic & Services
    subgraph "Business Logic & Services"
        direction TB
        Sync["Sync"]:::data
        PocketGraph["PocketGraph"]:::data
        Analytics["Analytics"]:::framework
        SharedKit["SharedPocketKit"]:::framework
    end

    %% Data Persistence
    subgraph "Data Persistence"
        direction TB
        CoreData["Core Data\n(Persistent Store)"]:::data
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        PocketAPI[(Pocket API)]:::external
        Snowplow[(Snowplow)]:::external
        APNs[(APNs)]:::external
        WidgetKit[(WidgetKit)]:::external
    end

    %% Dependencies: Presentation to Frameworks
    PocketApp -->|links| PocketKit
    PocketApp -->|links| Textile
    PocketApp -->|links| Analytics
    PocketApp -->|links| SharedKit
    PocketApp -->|links| Sync

    SaveExt -->|links| SaveKit
    SaveExt -->|links| SharedKit
    SaveExt -->|links| Sync

    PushServiceExt -->|uses| SharedKit
    PushServiceExt -->|uses| Sync
    PushStoryExt -->|uses| SharedKit
    PushStoryExt -->|uses| Sync

    ItemWidgetsExt -->|uses| ItemWidgetsKit
    ItemWidgetsExt -->|uses| SharedKit
    ItemWidgetsExt -->|uses| Sync

    IMessageExt -->|uses| StickerKit
    IMessageExt -->|uses| SharedKit

    %% Framework inter-dependencies
    PocketKit -->|calls| Sync
    PocketKit -->|uses| Textile
    PocketKit -->|reports| Analytics
    PocketKit -->|uses| SharedKit

    SaveKit -->|uses| SharedKit
    SaveKit -->|uses| Sync

    ItemWidgetsKit -->|uses| SharedKit
    ItemWidgetsKit -->|uses| Sync

    StickerKit -->|uses| SharedKit

    Sync -->|uses| PocketGraph
    Sync -->|persists| CoreData
    CoreData -->|feeds UI| PocketKit

    Analytics -->|sends events| Snowplow

    Sync -->|HTTP| PocketAPI

    APNs -->|pushes| PushServiceExt
    APNs -->|pushes| PushStoryExt

    WidgetKit -->|provides timeline| ItemWidgetsExt

    %% Click Events
    click PocketApp "https://github.com/pocket/pocket-ios/blob/develop/PocketApp.swift"
    click SaveExt "https://github.com/pocket/pocket-ios/blob/develop/SaveToPocket/SaveToPocket.swift"
    click PushServiceExt "https://github.com/pocket/pocket-ios/blob/develop/PushNotificationServiceExtension/NotificationService.swift"
    click PushStoryExt "https://github.com/pocket/pocket-ios/blob/develop/PushNotificationStoryExtension/NotificationViewController.swift"
    click ItemWidgetsExt "https://github.com/pocket/pocket-ios/blob/develop/ItemWidgets/ItemWidgetsBundle.swift"
    click IMessageExt "https://github.com/pocket/pocket-ios/blob/develop/iMessageExtension/MessagesViewController.swift"
    click PocketKit "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/PocketKit"
    click Sync "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/Sync"
    click PocketGraph "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/PocketGraph"
    click Textile "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/Textile"
    click Analytics "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/Analytics"
    click SaveKit "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/SaveToPocketKit"
    click SharedKit "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/SharedPocketKit"
    click StickerKit "https://github.com/pocket/pocket-ios/tree/develop/PocketKit/Sources/PocketStickerKit"

    %% Styles
    classDef presentation fill:#FFDDC1,stroke:#333,stroke-width:1px
    classDef framework fill:#C1DFF,stroke:#333,stroke-width:1px
    classDef data fill:#DFF1C1,stroke:#333,stroke-width:1px
    classDef external fill:#F1C1C1,stroke:#333,stroke-width:1px
```
