jarvis/CLAUDE.md

Jarvis iOS — Claude Code

What this is

Jarvis is an iOS app (SwiftUI, SwiftData, iOS 17+) that displays ranked news stories served from a self-hosted backend. The backend ingests RSS, clusters articles into stories, ranks them by signal score, and serves cached results via REST + WebSocket.

The app is a cached news intelligence client. It is not an RSS reader.

---

Architecture rule

RSS feeds → backend ingestion → cache/database → API → frontend

The frontend must never fetch RSS feeds directly. The frontend must never parse, deduplicate, or rank articles. The frontend consumes cached backend data only.

---

Backend responsibilities (not the app's job)

• RSS fetching, validation, timeout handling
• Feed health checks and dead-feed detection
• Article normalization and deduplication
• Story clustering and ranking
• Freshness, interestingness, and signal scoring
• API response caching and last-known-good fallback

The app trusts these to be done. It does not replicate them.

---

Frontend responsibilities

• Load cached stories immediately on open (SwiftData)
• Display stories with freshness indicators and source attribution
• Show connection/refresh state without blocking the UI
• Show stale-cache label when backend data is old
• Paginate via cursor (nextCursor)
• Never show an empty state when the cache has data

Performance targets:

• App opens with cached news: instant
• Home feed API response: < 1 second
• Refresh response: < 2 seconds
• Story open: < 500ms
• Background refresh does not block UI

If any of these fail, treat it as a bug.

---

Frontend validation checklist

Before marking any feed/story feature complete, verify:

• Cached news loads immediately without waiting for RSS
• Refresh does not freeze the UI
• Empty state does not appear when cache has data
• Stale cache is labeled (age visible)
• Fresh stories rise above old ones
• Categories are balanced across the feed
• Source attribution is correct and links work
• Offline state shows last-known-good content

---

Project structure

Jarvis/
  Models/Models.swift          — Codable structs + SwiftData models
  Networking/APIClient.swift   — REST layer (actor-based)
  Networking/WebSocketManager.swift — WS + reconnect backoff
  Store/StoryStore.swift       — central ObservableObject, drives all views
  Store/StoryStore+Supplement.swift — background section supplement fetches
  Store/ServerSettings.swift   — persists host to UserDefaults
  Store/CacheMaintenance.swift — SwiftData eviction
  Views/
    Home/SignalFeedView.swift  — main feed (All digest, pill pills, sub-sections)
    Home/StoryRowView.swift    — story card
    Reader/ArticleReaderView.swift — full article, cached badge
    Story/StoryDetailView.swift   — cluster detail + timeline
    Feeds/FeedManagerView.swift   — feed list + health states
    Feeds/AddFeedSheet.swift
    Settings/SettingsView.swift
    Settings/NotificationsView.swift
    Shared/Theme.swift         — StoryPill enum, NewsSection, design tokens
    Shared/SignalStripe.swift
    Shared/SourceChips.swift
    Shared/CachedBadge.swift
    Shared/ConnectionBanner.swift
    Onboarding/OnboardingView.swift
  JarvisApp.swift
API/contract.md               — REST + WebSocket API spec

---

Design tokens

• Accent: KisaniOrange = #FF5C00
• Background: #000000 (pure black)
• Surface: #111111 / #1A1A1A
• All views: .preferredColorScheme(.dark) unless user overrides in settings

---

Key decisions

• Story is the user-facing object. Never expose Cluster to UI.
• Pipeline: Article → Cluster → Story
• Signal score is server-computed; scoreBreakdown is exposed for display.
• WebSocket pushes {storyId, score} only; app re-fetches the full object via REST.
• WS reconnect: exponential backoff 1s → 2s → 4s → max 60s.
• Pagination: cursor-based via nextCursor.
• StoryStore.setPill() resets lastSyncedAt to bypass the 30s rate-limit on filter switch.
• sectionSupplement fetches populate sparse regional sections in the All digest independently.

---

Pill → tag mapping

Pill	Backend tags queried
All	— (no filter, full ranked feed)
F1	formula-1
Sport	sports, esports
Tech	technology, artificial-intelligence, machine-learning, cloud-computing, homelab, cybersecurity, security, programming-and-software-development, privacy-and-data-protection, web-design-and-ui-ux, wordpress-and-web-development, robotics
East Africa	east-africa, uganda (Uganda sub-section pinned first)
Southern Africa	south-africa, namibia, botswana, zimbabwe, zambia, mozambique, southern-africa
Canada	canada
US	united-states

---

Reporting requirement

At the end of any significant work session, generate a report covering:

1. Executive summary — is the app usable, fast, serving cached news?
2. Issues found — backend, frontend, cache, feed, ranking, data quality
3. Fixes made — file, function, reason, result
4. Measurements — before/after for response times, article counts, dead feeds
5. Remaining risks — nothing hidden
6. Next actions — highest-value improvements
7. Status — one of: NOT READY / PARTIALLY READY / READY FOR TESTING / READY FOR RELEASE

Never claim READY FOR RELEASE without evidence from logs, API responses, or timing measurements.