Architecture — FeedReader Documentation

Project Structure

FeedReader is split into two layers: a platform-independent Swift Package and an iOS app that uses it.

FeedReader/ │ ├── Sources/FeedReaderCore/ ← Swift Package (no UIKit) │ ├── RSSParser.swift RSS parsing with concurrent loading │ ├── RSSStory.swift Story model with URL/HTML safety │ ├── FeedItem.swift Feed source model + presets │ └── NetworkReachability.swift SCNetworkReachability wrapper │ ├── FeedReader/ ← iOS App (UIKit) │ ├── AppDelegate.swift App lifecycle │ ├── Story.swift NSCoding-based story model │ ├── Feed.swift Feed model (app layer) │ ├── FeedManager.swift Feed source CRUD singleton │ ├── BookmarkManager.swift Bookmark persistence singleton │ ├── RSSFeedParser.swift App-layer XML parser │ ├── ImageCache.swift Async image loader + NSCache │ ├── Reachability.swift Network detection │ ├── StoryTableViewController Main feed list │ ├── StoryViewController Story detail │ ├── BookmarksViewController Saved stories │ ├── FeedListViewController Feed manager UI │ └── NoInternetFound... Offline fallback │ ├── FeedReaderTests/ ← App tests ├── Tests/FeedReaderCoreTests/ ← Package tests └── Package.swift SPM manifest

Data Flow

Here's how data flows through the app from network to screen:

┌──────────────┐ HTTP GET ┌──────────────┐ │ RSS Feed │ ◄──────────────── │ URLSession │ │ (XML) │ ──────────────► │ (async) │ └──────┬───────┘ └──────┬────────┘ │ XML data │ ▼ │ ┌──────────────┐ │ │ XMLParser │ ◄────────────────────────┘ │ (per-feed │ │ collector) │ └──────┬───────┘ │ [RSSStory] ▼ ┌──────────────┐ deduplicate ┌──────────────┐ │ RSSParser │ ─────────────────►│ Main Thread │ │ (merge + │ via serial │ Delegate │ │ dedup) │ queue │ Callback │ └──────────────┘ └──────┬────────┘ │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ ┌────────────┐ ┌──────────┐ ┌────────────┐ │ UITableView│ │ NSCoding │ │ ImageCache │ │ (display) │ │ (persist) │ │ (thumbnails│ └────────────┘ └──────────┘ └────────────┘

Threading Model

FeedReader's threading is designed for correctness without complexity:

Component	Thread	Why
`URLSession` tasks	Background (system)	Network I/O should never block the main thread
`RSSParseCollector`	URLSession callback thread	Each feed parsed in isolation — no shared state
`RSSParser` merge	Serial `DispatchQueue`	Protects shared `stories` and `seenLinks` from data races
Delegate callbacks	Main thread	UI updates must happen on main thread
`ImageCache` downloads	Background (URLSession)	Image fetching doesn't block scrolling
`NSCoding` persistence	Main thread	Simple archiving — fast enough for typical story counts

Concurrency Safety

The key concurrency challenge is multi-feed parsing. When loadFeeds is called with multiple URLs:

Each URL spawns its own URLSession data task
Each task's completion handler creates an isolated RSSParseCollector — no shared parsing state
Parsed stories are merged onto a serial DispatchQueue, which protects the shared stories array and seenLinks set
When the last feed completes, the delegate is called on the main thread
If a new loadFeeds call arrives while a previous one is in-flight, the previous session is cancelled via invalidateAndCancel()

Caching Strategy

Story Persistence (NSCoding)

Stories are persisted to disk using NSKeyedArchiver/NSKeyedUnarchiver. This provides:

Offline reading — Previously fetched stories are available without network
Fast launch — Cached stories display immediately while fresh data loads
Graceful degradation — If a feed fails to load, the user still sees cached content

Image Caching (NSCache)

The ImageCache class provides a two-tier caching strategy:

In-memory (NSCache) — Images are cached in memory for instant access during scrolling. NSCache automatically evicts under memory pressure.
Async loading — Images are fetched on background threads. The cell checks if the image is already cached before making a network request.
Cell reuse safety — The cache key is checked against the current cell's story to prevent displaying stale images from reused cells.

MVC Pattern

The iOS app follows Apple's recommended MVC architecture:

Layer	Components	Responsibility
Model	`Story`, `Feed`	Data representation, NSCoding conformance, equality
View	Storyboards, `StoryTableViewCell`	Visual layout, cell rendering, image display
Controller	`StoryTableViewController`, `StoryViewController`, etc.	User interaction, data binding, navigation, XML parsing orchestration

Singletons

Two singletons manage persistent state:

FeedManager.shared — Manages the list of RSS feed sources. Handles adding, removing, toggling, and reordering feeds. Persists to UserDefaults via NSCoding.
BookmarkManager.shared — Manages bookmarked stories. Persists to the app's documents directory via NSCoding.

The Swift Package Split

The FeedReaderCore Swift Package extracts platform-independent functionality:

In Package (FeedReaderCore)	In App (FeedReader)
`RSSParser` — concurrent multi-feed parsing	StoryTableViewController — UI + XML orchestration
`RSSStory` — model with URL/HTML safety	`Story` — NSCoding model for persistence
`FeedItem` — feed source model + presets	`Feed` — app-layer feed model
`NetworkReachability` — SCNetworkReachability	`Reachability` — app-layer connectivity

The package has no UIKit dependency, making it suitable for any iOS, macOS, or server-side Swift project that needs RSS parsing.

Security Considerations

URL Validation

All URLs (story links and image paths) are validated by RSSStory.isSafeURL():

Only http and https schemes are allowed
javascript:, file:, data:, and other schemes are rejected
Stories with invalid link URLs are dropped entirely (init? returns nil)
Invalid image URLs are silently discarded (imagePath set to nil)

HTML Sanitization

RSS descriptions often contain HTML. RSSStory.stripHTML() removes all HTML tags via regex and decodes common entities, preventing XSS-style injection in the UI.

Network Security

All feed fetching uses URLSession with default security settings (ATS enforced on iOS 9+). HTTPS is preferred for all preset feeds.