This commit is contained in:
Krishna Kumar
160
openwiki/architecture/app-architecture.md
Normal file
160
openwiki/architecture/app-architecture.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# App Architecture
|
||||
|
||||
This page explains how the major Marks runtime pieces fit together. For product-level flows, see [Product workflows](../workflows/product-workflows.md). For setup and verification, see [Development and testing](../operations/development-and-testing.md).
|
||||
|
||||
## Targets and source layout
|
||||
|
||||
`/project.yml` is the XcodeGen project definition. It defines four targets:
|
||||
|
||||
- `Marks` — the main iOS app. Sources include `/Marks` plus `/MarksWidget/WidgetDataStore.swift` so the app can write widget data.
|
||||
- `ShareExtension` — app extension with `/ShareExtension` plus selected shared model/service files from `/Marks` (`Bookmark`, `ServerConfig`, `LinkdingAPI`, `MarksAuth`, `Log`, `PodcastRequests`).
|
||||
- `MarksWidget` — WidgetKit extension with `/MarksWidget`.
|
||||
- `MarksTests` — unit-test bundle depending on `Marks`.
|
||||
|
||||
The app is Swift 6.0 and targets iOS 26.0. The main app, share extension, and widget extension share the app group `group.com.magicive.marks` through entitlements and runtime code.
|
||||
|
||||
## App entrypoint and navigation shell
|
||||
|
||||
`/Marks/MarksApp.swift` contains the `@main` app and `MainContainer`.
|
||||
|
||||
At startup:
|
||||
|
||||
1. `MarksApp` loads a saved `ServerConfig` or falls back to a built-in default config.
|
||||
2. `MainContainer` constructs `LinkdingAPI(config:)`.
|
||||
3. `MainContainer` stores `BookmarksViewModel(api:cacheKey:)` in `@State`, keeping the model stable across SwiftUI re-renders.
|
||||
4. A top-level `TabView` presents Bookmarks, Tags, Podcasts, and Search.
|
||||
|
||||
`MainContainer` also handles:
|
||||
|
||||
- custom deep links (`marks://bookmark?...`, `marks://podcast?...`),
|
||||
- App Intent handoff through `IntentRouter.shared`,
|
||||
- pending podcast requests queued by the share extension,
|
||||
- foreground refreshes and background podcast progress persistence.
|
||||
|
||||
## Central state: `BookmarksViewModel`
|
||||
|
||||
`/Marks/Views/BookmarksViewModel.swift` is `@Observable @MainActor` and is the core app state object. It owns:
|
||||
|
||||
- loaded bookmarks, errors, loading flags, pagination URL, search query, and unread filter,
|
||||
- generated smart collections and enrichment progress,
|
||||
- a `LinkdingAPI` actor for server sync,
|
||||
- `ClaudeService` for backend AI/podcast calls,
|
||||
- `PodcastPlayerViewModel` and `PodcastGenerationManager`,
|
||||
- the disk bookmark cache URL.
|
||||
|
||||
Key side effects during bookmark loading and mutations:
|
||||
|
||||
- `load()` optionally restores cached bookmarks from Application Support, fetches linkding bookmarks, restores local AI metadata, saves the full unfiltered cache, writes recent bookmarks to `WidgetDataStore`, and indexes bookmarks into Spotlight.
|
||||
- `loadMore()` follows linkding's `next` URL and indexes newly appended bookmarks.
|
||||
- `delete()` and `archive()` mutate linkding, remove local entries, and remove Spotlight entries.
|
||||
- `addBookmark()` saves to linkding, inserts locally, indexes the bookmark, and starts best-effort AI enrichment.
|
||||
- `enrichAll()` and background `startEnrichment()` call AI enrichment, persist AI metadata, and reindex enriched bookmarks.
|
||||
|
||||
Because one `BookmarksViewModel` instance is shared by all tabs, array mutations and filters have cross-tab effects.
|
||||
|
||||
## Linkding integration
|
||||
|
||||
`/Marks/Services/LinkdingAPI.swift` is an actor wrapping linkding's REST API. It builds URLs from `ServerConfig` (`/Marks/Models/ServerConfig.swift`) and sends `Authorization: Token ...` headers.
|
||||
|
||||
Implemented operations include:
|
||||
|
||||
- `fetchBookmarks(search:offset:limit:unread:)` → `GET /api/bookmarks/`,
|
||||
- `fetchBookmarksFromUrl(_:)` for pagination `next` URLs,
|
||||
- `checkBookmark(url:)` → `GET /api/bookmarks/check/`, used by the share extension,
|
||||
- `fetchTags(limit:)` → `GET /api/tags/`,
|
||||
- `createBookmark(_:)` → `POST /api/bookmarks/`,
|
||||
- `updateBookmark(id:update:)` → `PATCH /api/bookmarks/{id}/`,
|
||||
- `deleteBookmark(id:)` → `DELETE /api/bookmarks/{id}/`,
|
||||
- `archiveBookmark(id:)` → `POST /api/bookmarks/{id}/archive/`,
|
||||
- `verifyConnection()` for configuration checks.
|
||||
|
||||
`Bookmark`, `BookmarkResponse`, create/update payloads, `BookmarkCheck`, tag response models, and `SmartCollection` live in `/Marks/Models/Bookmark.swift`.
|
||||
|
||||
## Configuration and app-group sharing
|
||||
|
||||
`ServerConfig` contains linkding host, optional port, path, token, and HTTPS flag. Its extension stores config in two places:
|
||||
|
||||
- `UserDefaults.standard` for the main app,
|
||||
- `UserDefaults(suiteName: "group.com.magicive.marks")` for extensions.
|
||||
|
||||
`ServerConfig.loadShared()` is used by the share extension, which cannot read the main app's standard defaults. Avoid changing config keys or app-group IDs without updating all entitlements, `ServerConfig`, `WidgetDataStore`, and `PodcastRequests` together.
|
||||
|
||||
Security note: `/Marks/MarksApp.swift` currently includes a built-in default config with a token-like value. Treat it as sensitive; do not copy it into documentation or generated output.
|
||||
|
||||
## Backend AI, analytics, and podcasts
|
||||
|
||||
`/Marks/Services/MarksAuth.swift` registers an anonymous device with the Marks backend and caches a JWT in `UserDefaults.standard`. `ClaudeService` uses that token for backend calls:
|
||||
|
||||
- bookmark enrichment: `POST /v1/marks/enrich`,
|
||||
- semantic search: `POST /v1/marks/search`,
|
||||
- smart collections: `POST /v1/marks/collections`,
|
||||
- podcast generation: `POST /v1/podcast/generate`,
|
||||
- podcast polling: `GET /v1/podcast/status/{jobId}`,
|
||||
- podcast audio download: `GET /v1/podcast/audio/{jobId}`.
|
||||
|
||||
`/Marks/Services/AnalyticsService.swift` sends events through the backend path used by `ClaudeService`/`MarksAuth`.
|
||||
|
||||
Podcast audio is downloaded to Application Support under a `podcasts` directory using a stable hash of the article URL. `PodcastIndex` records metadata in `index.json`; `PodcastLibrary` reads that index for the Podcasts tab and widget metadata.
|
||||
|
||||
## On-device Ask and Spotlight
|
||||
|
||||
The app has two AI paths:
|
||||
|
||||
1. **Backend AI** through `ClaudeService` for enrichment, semantic search, smart collections, and podcasts.
|
||||
2. **On-device RAG** through `/Marks/Services/BookmarkAssistant.swift` for the Ask UI.
|
||||
|
||||
`BookmarkAssistant` uses `FoundationModels.LanguageModelSession` with `BookmarkSearchTool`. Its instructions require answers to be grounded in bookmarks. Retrieval flows through Spotlight:
|
||||
|
||||
- `SpotlightIndexer` indexes bookmarks after loads, load-more operations, add, and enrichment.
|
||||
- `SpotlightBookmarkSearch`/`BookmarkSearchTool` search the index for relevant bookmarks.
|
||||
- `BookmarkEntity` also conforms to indexed App Intents concepts for system-level entity discovery.
|
||||
|
||||
If changing bookmark fields, keep `Bookmark`, `BookmarkEntity`, Spotlight indexing, widget payloads, and row UI in sync.
|
||||
|
||||
## Share extension architecture
|
||||
|
||||
The share extension is implemented by `/ShareExtension/ShareViewController.swift` and `/ShareExtension/ShareView.swift`.
|
||||
|
||||
It accepts a shared URL/text payload, creates a SwiftUI save card, loads shared `ServerConfig`, checks linkding for an existing bookmark, and lets the user edit tags, notes, read-later state, and a Create Podcast toggle.
|
||||
|
||||
For suggestions, it combines:
|
||||
|
||||
- linkding `checkBookmark` metadata and `auto_tags`,
|
||||
- the user's existing tag vocabulary from `fetchTags()`,
|
||||
- backend AI tag suggestions through `/ShareExtension/TagSuggester.swift`.
|
||||
|
||||
Existing bookmarks are updated rather than duplicated. New bookmarks are created through `LinkdingAPI`. Podcast generation is not performed inside the extension; it queues a `PodcastRequests` item in the app group for the main app to process later.
|
||||
|
||||
## Widget architecture and deep links
|
||||
|
||||
`/MarksWidget/MarksWidgetBundle.swift` registers three widgets:
|
||||
|
||||
- `RecentBookmarksWidget` (`systemMedium`),
|
||||
- `RandomBookmarkWidget` (`systemSmall`),
|
||||
- `RecentPodcastsWidget` (`systemMedium`).
|
||||
|
||||
Widgets read only app-group JSON through `/MarksWidget/WidgetDataStore.swift`:
|
||||
|
||||
- `widget_bookmarks.json`,
|
||||
- `widget_podcasts.json`.
|
||||
|
||||
They do not call network APIs. Main-app writes trigger `WidgetCenter.shared.reloadAllTimelines()` when WidgetKit is available.
|
||||
|
||||
Widget links use custom URLs built by `URL.marksBookmark(_:)` and `URL.marksPodcast(_:)`. `MainContainer.handleDeepLink(_:)` opens bookmark URLs in `BrowserView` or starts podcast playback and shows the player.
|
||||
|
||||
## App Intents and Shortcuts
|
||||
|
||||
`/Marks/Intents/MarksAppIntents.swift` defines:
|
||||
|
||||
- `OpenBookmarkIntent` — opens a selected `BookmarkEntity` in app.
|
||||
- `SearchMarksIntent` — conforms to the system search schema and routes text to the Search tab.
|
||||
- `AddBookmarkIntent` — saves a URL headlessly through linkding and refreshes widget data.
|
||||
- `ShowUnreadIntent` — fetches up to 10 unread bookmarks.
|
||||
- `SummarizeBookmarkIntent` — calls backend AI enrichment for a selected bookmark.
|
||||
- `MarksShortcuts` — registers Add Bookmark, Search, Unread, and Summarize shortcuts.
|
||||
|
||||
`IntentRouter` bridges intents that need to open UI back into `MainContainer`. `BookmarkEntity` maps between linkding `Bookmark` values and App Intents entities.
|
||||
|
||||
## Recent history context
|
||||
|
||||
Recent git history shows major investment in podcast UX and on-device AI: the latest merge added played/unplayed queues, background podcast generation, share-sheet audio requests, podcast library/index changes, and player improvements. A prior AI commit added on-device RAG, Spotlight indexing, and unified logging. Use those areas cautiously because they span app state, storage, widgets, share extension, and App Intents rather than a single view.
|
||||
Reference in New Issue
Block a user