From 31dcb89582c62d10cef29e735d4b8ba816084e5b Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 10:30:39 +0800 Subject: [PATCH 1/8] feat(backend): add Standard Ebooks work detail endpoint and propagate upstream errors --- backend/api/v1/endpoints/standard_ebooks.py | 14 ++- backend/services/__init__.py | 13 ++- backend/services/standard_ebooks.py | 111 +++++++++++++++++++- 3 files changed, 129 insertions(+), 9 deletions(-) diff --git a/backend/api/v1/endpoints/standard_ebooks.py b/backend/api/v1/endpoints/standard_ebooks.py index 249db48..e1c468e 100644 --- a/backend/api/v1/endpoints/standard_ebooks.py +++ b/backend/api/v1/endpoints/standard_ebooks.py @@ -9,16 +9,24 @@ @router.get("/public/standard-ebooks", response_model=list[StoryDTO]) async def get_standard_ebooks_stories( - topic: Optional[str] = Query(default=None, description="Filter Standard Ebooks by subject (e.g. fiction, horror)"), - search: Optional[str] = Query(default=None, description="Search keyword for title or author"), + topic: Optional[str] = Query(default=None, max_length=50, description="Filter Standard Ebooks by subject (e.g. fiction, horror)"), + search: Optional[str] = Query(default=None, max_length=200, description="Search keyword for title or author"), ): """Retrieve curated public-domain classics from Standard Ebooks.""" return await standard_ebooks_service.get_standard_ebooks_stories(topic=topic, search=search) +@router.get("/public/standard-ebooks/story", response_model=StoryDTO) +async def get_standard_ebooks_story( + book_id: str = Query(..., max_length=120, description="Standard Ebooks slug path (e.g. bram-stoker/dracula)"), +): + """Retrieve metadata for a specific Standard Ebooks work.""" + return await standard_ebooks_service.get_standard_ebooks_story_by_id(book_id=book_id) + + @router.get("/public/standard-ebooks/chapters", response_model=list[ChapterDTO]) async def get_standard_ebooks_chapters( - book_id: str = Query(..., description="Standard Ebooks slug path (e.g. bram-stoker/dracula)"), + book_id: str = Query(..., max_length=120, description="Standard Ebooks slug path (e.g. bram-stoker/dracula)"), ): """Retrieve structured semantic XHTML chapters for a Standard Ebooks work.""" return await standard_ebooks_service.get_standard_ebooks_chapters(book_id=book_id) diff --git a/backend/services/__init__.py b/backend/services/__init__.py index eb064a1..49f2980 100644 --- a/backend/services/__init__.py +++ b/backend/services/__init__.py @@ -12,7 +12,12 @@ ) from .shelf_sync import sync_shelf, get_shelf from .gutenberg import ingest_gutenberg_book, get_gutenberg_stories -from . import auth_service, reading_stats, manga +from .standard_ebooks import ( + get_standard_ebooks_stories, + get_standard_ebooks_story_by_id, + get_standard_ebooks_chapters, +) +from . import auth_service, reading_stats, manga, standard_ebooks __all__ = [ "extract_chapters_from_text", @@ -29,8 +34,12 @@ "get_shelf", "ingest_gutenberg_book", "get_gutenberg_stories", + "get_standard_ebooks_stories", + "get_standard_ebooks_story_by_id", + "get_standard_ebooks_chapters", "auth_service", "reading_stats", - "manga" + "manga", + "standard_ebooks", ] diff --git a/backend/services/standard_ebooks.py b/backend/services/standard_ebooks.py index 9deb24f..bef6064 100644 --- a/backend/services/standard_ebooks.py +++ b/backend/services/standard_ebooks.py @@ -457,8 +457,9 @@ async def get_standard_ebooks_stories( if normalized_search: query = urlencode({"query": normalized_search, "page": 1, "per-page": 12}) response = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?{query}") - if response.status_code == 200: - entries = parse_listing_xhtml(response.content) + if response.status_code != 200: + raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") + entries = parse_listing_xhtml(response.content) elif normalized_topic: slug_topic = quote(normalized_topic.replace(" ", "-"), safe="-") response = await client.get( @@ -466,11 +467,14 @@ async def get_standard_ebooks_stories( ) if response.status_code == 200: entries = parse_listing_xhtml(response.content) + elif response.status_code != 404: + raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") if not entries: query = urlencode({"query": normalized_topic, "sort": "popularity", "page": 1, "per-page": 12}) fallback_resp = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?{query}") - if fallback_resp.status_code == 200: - entries = parse_listing_xhtml(fallback_resp.content) + if fallback_resp.status_code != 200: + raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") + entries = parse_listing_xhtml(fallback_resp.content) else: response = await client.get(f"{STANDARD_EBOOKS_BASE_URL}/ebooks?sort=popularity&page=1&per-page=12") if response.status_code == 200: @@ -530,6 +534,105 @@ async def get_standard_ebooks_stories( return list(stories) +def _humanize_slug_part(value: str) -> str: + return " ".join(part.capitalize() for part in value.split("-") if part) + + +def _parse_book_page_story(xml_bytes: bytes, slug: str) -> StoryDTO: + try: + root = ET.fromstring(xml_bytes) + except ET.ParseError as exc: + raise HTTPException(status_code=502, detail="Invalid book metadata from Standard Ebooks") from exc + + slug_parts = slug.split("/") + fallback_author = _humanize_slug_part(slug_parts[0]) if slug_parts else "Standard Ebooks" + fallback_title = _humanize_slug_part(slug_parts[1]) if len(slug_parts) > 1 else slug + + title = "" + author_names: list[str] = [] + cover_url: Optional[str] = None + + for elem in root.iter(): + prop = elem.attrib.get("property", "") + tag = _local_tag(elem.tag) + if not title and prop == "schema:name" and tag in ("h1", "span", "p", "a"): + candidate = _collapse_whitespace("".join(elem.itertext())) + if candidate: + title = candidate + if prop == "schema:author": + name_el = elem.find('.//*[@property="schema:name"]') + author_text = _collapse_whitespace( + "".join((name_el if name_el is not None else elem).itertext()) + ) + if author_text and author_text not in author_names: + author_names.append(author_text) + if cover_url is None and tag == "img": + src = (elem.attrib.get("src") or "").strip() + if "cover" in src: + if src.startswith("/"): + cover_url = f"{STANDARD_EBOOKS_BASE_URL}{src}" + elif src.startswith("https://"): + cover_url = src + + resolved_title = (title or fallback_title)[:120] + resolved_author = (", ".join(author_names) if author_names else fallback_author)[:80] + synopsis, genre, read_minutes = parse_book_detail_xhtml(xml_bytes, fallback_title=resolved_title) + now = datetime.now(timezone.utc) + return StoryDTO( + id=uuid5(STANDARD_EBOOKS_NAMESPACE, f"book:{slug}"), + title=resolved_title, + author=resolved_author, + genre=genre, + chapter="", + synopsis=synopsis, + content="", + read_time_minutes=read_minutes, + is_bookmarked=False, + is_completed=False, + created_at_utc=now, + updated_at_utc=now, + cover_image_url=cover_url, + total_pages=0, + current_page=1, + progress_percent=0, + saves_count="0", + reads_count="0", + badge_text=None, + total_chapters=0, + content_format="PROSE", + source_provider="STANDARD_EBOOKS", + provider_id=slug, + provider_download_count=None, + chapters=None, + ) + + +async def get_standard_ebooks_story_by_id(book_id: str) -> StoryDTO: + """Fetches metadata for a single Standard Ebooks work by its slug path.""" + slug = _normalize_slug(book_id) + now = time.monotonic() + for cached_at, cached_stories in _STANDARD_EBOOKS_CATALOG_CACHE.values(): + if (now - cached_at) < STANDARD_EBOOKS_CATALOG_TTL_SECONDS: + for story in cached_stories: + if story.provider_id == slug: + return story + + url = f"{STANDARD_EBOOKS_BASE_URL}/ebooks/{slug}" + try: + async with _standard_ebooks_client() as client: + response = await client.get(url) + except httpx.HTTPError as exc: + logger.warning("Standard Ebooks detail fetch failed for %s: %s", slug, exc) + raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") from exc + + if response.status_code == 404: + raise HTTPException(status_code=404, detail="Standard Ebooks title not found") + if response.status_code != 200: + raise HTTPException(status_code=502, detail="Standard Ebooks catalog service is unavailable") + + return _parse_book_page_story(response.content, slug) + + async def get_standard_ebooks_chapters(book_id: str) -> list[ChapterDTO]: """Fetches and parses the semantic XHTML chapter tree for a Standard Ebooks work.""" slug = _normalize_slug(book_id) From 02cdc82581520927f10c40eab614b4cc32d090bf Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 10:30:39 +0800 Subject: [PATCH 2/8] test(backend): cover Standard Ebooks detail and federated provider failure isolation --- backend/test_provider_http.py | 123 ++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/backend/test_provider_http.py b/backend/test_provider_http.py index 20c101d..d9ab455 100644 --- a/backend/test_provider_http.py +++ b/backend/test_provider_http.py @@ -405,3 +405,126 @@ async def mock_stream(self, method, url, headers=None, **kwargs): params={"book_id": "../etc/passwd"}, ) assert bad_resp.status_code == 400 + + +def test_standard_ebooks_story_detail_http_endpoint_returns_metadata_and_handles_missing(monkeypatch): + from uuid import uuid5 + import httpx + from services import standard_ebooks + + monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_CATALOG_CACHE", {}) + monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_DETAIL_CACHE", {}) + + book_xml = b""" + + +
+

Dracula

+

Bram Stoker

+ Cover +

Jonathan Harker visits Count Dracula.

+

161,105 words (9 hours 46 minutes) with a reading ease of 77.57 (fairly easy).

+ +
+ + """ + + async def mock_get(self, url, params=None, headers=None, **kwargs): + url_str = str(url) + if url_str.endswith("/ebooks/bram-stoker/dracula"): + return httpx.Response(200, content=book_xml) + if url_str.endswith("/ebooks/missing-author/missing-book"): + return httpx.Response(404, content=b"") + return httpx.Response(503, content=b"") + + monkeypatch.setattr(httpx.AsyncClient, "get", mock_get) + + detail_resp = client.get( + "/api/v1/public/standard-ebooks/story", + params={"book_id": "bram-stoker/dracula"}, + ) + assert detail_resp.status_code == 200 + story = detail_resp.json() + assert story["id"] == str(uuid5(standard_ebooks.STANDARD_EBOOKS_NAMESPACE, "book:bram-stoker/dracula")) + assert story["title"] == "Dracula" + assert story["author"] == "Bram Stoker" + assert story["genre"] == "Horror" + assert story["sourceProvider"] == "STANDARD_EBOOKS" + assert story["providerId"] == "bram-stoker/dracula" + assert story["contentFormat"] == "PROSE" + assert story["coverImageUrl"] == "https://standardebooks.org/images/covers/bram-stoker_dracula/hash/cover@2x.jpg" + assert "Jonathan Harker" in story["synopsis"] + assert story["readTimeMinutes"] > 500 + + missing_resp = client.get( + "/api/v1/public/standard-ebooks/story", + params={"book_id": "missing-author/missing-book"}, + ) + assert missing_resp.status_code == 404 + + invalid_resp = client.get( + "/api/v1/public/standard-ebooks/story", + params={"book_id": "../bad"}, + ) + assert invalid_resp.status_code == 400 + + +def test_federated_prose_providers_preserve_distinct_edition_identities_and_isolate_partial_failures(monkeypatch): + import httpx + from services import gutenberg, standard_ebooks + + monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_CATALOG_CACHE", {}) + monkeypatch.setattr(standard_ebooks, "_STANDARD_EBOOKS_DETAIL_CACHE", {}) + + async def gutenberg_search(_client, params): + assert params == {"search": "Dracula"} + return [_gutenberg_http_book(345, "Dracula", "Stoker, Bram")] + + async def se_unavailable(self, url, params=None, headers=None, **kwargs): + return httpx.Response(503, content=b"upstream maintenance") + + monkeypatch.setattr(gutenberg, "_fetch_gutenberg_catalog_books", gutenberg_search) + monkeypatch.setattr(httpx.AsyncClient, "get", se_unavailable) + + gutenberg_resp = client.get("/api/v1/public/gutenberg", params={"search": "Dracula"}) + se_failed_resp = client.get("/api/v1/public/standard-ebooks", params={"search": "Dracula"}) + + assert gutenberg_resp.status_code == 200 + assert se_failed_resp.status_code == 502 + assert se_failed_resp.json()["detail"] == "Standard Ebooks catalog service is unavailable" + + gutenberg_dracula = gutenberg_resp.json()[0] + assert gutenberg_dracula["sourceProvider"] == "GUTENBERG" + assert gutenberg_dracula["providerId"] == "345" + assert gutenberg_dracula["id"] == "00000000-0000-0000-0000-000000000159" + + # Now recover Standard Ebooks and verify same-title editions remain distinct. + listing_xml = b""" + +
    +
  1. + Dracula +

    Bram Stoker

    + Cover +
  2. +
+ """ + + async def se_recovered(self, url, params=None, headers=None, **kwargs): + url_str = str(url) + if "/ebooks?query=Dracula" in url_str: + return httpx.Response(200, content=listing_xml) + return httpx.Response(200, content=b"") + + monkeypatch.setattr(httpx.AsyncClient, "get", se_recovered) + se_ok_resp = client.get("/api/v1/public/standard-ebooks", params={"search": "Dracula"}) + assert se_ok_resp.status_code == 200 + se_dracula = se_ok_resp.json()[0] + assert se_dracula["sourceProvider"] == "STANDARD_EBOOKS" + assert se_dracula["providerId"] == "bram-stoker/dracula" + assert se_dracula["id"] != gutenberg_dracula["id"] + assert se_dracula["title"] == gutenberg_dracula["title"] + assert se_dracula["author"] == gutenberg_dracula["author"] From afee0d84251ea4b184998192707f0a542e3f9063 Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 10:30:39 +0800 Subject: [PATCH 3/8] feat(ios): surface Standard Ebooks shelf and preserve cross-provider edition identity --- .../Library/ViewModels/StoryStore.swift | 33 ++++++++++++++----- .../Library/Views/AuthorDetailView.swift | 6 ++-- .../Features/Library/Views/ExploreView.swift | 2 +- .../Library/Views/GenreDetailView.swift | 2 +- .../Features/Library/Views/LibraryView.swift | 19 +++++++++++ 5 files changed, 48 insertions(+), 14 deletions(-) diff --git a/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift b/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift index 17e15be..b8182ee 100644 --- a/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift +++ b/frontend/FableApp/Features/Library/ViewModels/StoryStore.swift @@ -6,6 +6,7 @@ public final class StoryStore: ObservableObject { @Published var stories: [Story] = [] @Published var recentGutenbergStories: [Story] = [] @Published var popularGutenbergStories: [Story] = [] + @Published var standardEbooksStories: [Story] = [] @Published var selectedCategory: String = "All" @Published var activeReaderStory: Story? @Published var isShowingDisplayOptions: Bool = false @@ -642,7 +643,12 @@ public final class StoryStore: ObservableObject { } if let idx = stories.firstIndex(where: { - $0.id == entity.id || (entity.providerId != nil && !entity.providerId!.isEmpty && $0.providerId == entity.providerId) + $0.id == entity.id || ( + entity.providerId != nil + && !entity.providerId!.isEmpty + && $0.sourceProvider == provider + && $0.providerId == entity.providerId + ) }) { stories[idx].isBookmarked = entity.isBookmarked stories[idx].isCompleted = entity.isCompleted @@ -961,16 +967,22 @@ public final class StoryStore: ObservableObject { return exactIndex } + if let remoteProviderId = remote.providerId, !remoteProviderId.isEmpty { + return stories.firstIndex(where: { + !matchedIds.contains($0.id) + && $0.sourceProvider == remote.sourceProvider + && $0.providerId == remoteProviderId + }) + } + let remoteTitle = normalizedCatalogValue(remote.title) let remoteAuthor = normalizedCatalogValue(remote.author) - let matchingCatalogStories = stories.indices.filter { index in - let story = stories[index] - return !matchedIds.contains(story.id) - && normalizedCatalogValue(story.title) == remoteTitle - && normalizedCatalogValue(story.author) == remoteAuthor - } - return matchingCatalogStories.first(where: { stories[$0].sourceProvider == remote.sourceProvider }) - ?? matchingCatalogStories.first + return stories.firstIndex(where: { + !matchedIds.contains($0.id) + && $0.sourceProvider == remote.sourceProvider + && normalizedCatalogValue($0.title) == remoteTitle + && normalizedCatalogValue($0.author) == remoteAuthor + }) } private func normalizedCatalogValue(_ value: String) -> String { @@ -1219,6 +1231,9 @@ public final class StoryStore: ObservableObject { do { let fetched = try await apiService.fetchStandardEbooksStories(topic: topic, search: search) let isBrowseSnapshot = topic != nil && (search ?? "").isEmpty + if isBrowseSnapshot || (topic == nil && (search ?? "").isEmpty) { + standardEbooksStories = fetched + } mergePublicProseBooks(fetched, provider: .standardEbooks, replaceUnengagedSnapshot: isBrowseSnapshot) } catch { recordProviderCatalogResult(.standardEbooks, succeeded: false) diff --git a/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift b/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift index ea68fcd..341ea8a 100644 --- a/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift +++ b/frontend/FableApp/Features/Library/Views/AuthorDetailView.swift @@ -44,7 +44,7 @@ public struct AuthorDetailView: View { .foregroundColor(FableTheme.textPrimary) HStack(spacing: 8) { - Text("Project Gutenberg") + Text("Public Domain Catalog") .fableFont(size: 11, weight: .bold) .foregroundColor(FableTheme.brandPrimary) .padding(.horizontal, 8) @@ -110,7 +110,7 @@ public struct AuthorDetailView: View { Text("No titles currently cached for this author.") .fableFont(size: 14, weight: .semibold) .foregroundColor(FableTheme.textPrimary) - Text(StoryStore.isMangaEnabled ? "Tap below to query Project Gutenberg and MangaDex." : "Tap below to query Project Gutenberg.") + Text(StoryStore.isMangaEnabled ? "Tap below to query Project Gutenberg, Standard Ebooks, and MangaDex." : "Tap below to query Project Gutenberg and Standard Ebooks.") .fableFont(size: 12) .foregroundColor(FableTheme.textMuted) .multilineTextAlignment(.center) @@ -190,7 +190,7 @@ private struct AuthorStoryRowView: View { let onSelect: () -> Void private var formatText: String { - story.contentFormat == .manga || story.sourceProvider == .mangadex ? "MANGA" : "PROSE" + story.contentFormat == .manga || story.sourceProvider == .mangadex ? "MANGA" : story.sourceProvider.displayName.uppercased() } private var placeholderIcon: String { diff --git a/frontend/FableApp/Features/Library/Views/ExploreView.swift b/frontend/FableApp/Features/Library/Views/ExploreView.swift index d8681c3..3141ad8 100644 --- a/frontend/FableApp/Features/Library/Views/ExploreView.swift +++ b/frontend/FableApp/Features/Library/Views/ExploreView.swift @@ -181,7 +181,7 @@ public struct ExploreView: View { .lineLimit(1) HStack(spacing: 6) { - Text(story.contentFormat.displayName.uppercased()) + Text(story.contentFormat == .manga ? "MANGA" : story.sourceProvider.displayName.uppercased()) .fableFont(size: 8, weight: .heavy) .padding(.horizontal, 6) .padding(.vertical, 2) diff --git a/frontend/FableApp/Features/Library/Views/GenreDetailView.swift b/frontend/FableApp/Features/Library/Views/GenreDetailView.swift index f581bdb..ecce7a6 100644 --- a/frontend/FableApp/Features/Library/Views/GenreDetailView.swift +++ b/frontend/FableApp/Features/Library/Views/GenreDetailView.swift @@ -212,7 +212,7 @@ public struct GenreDetailView: View { VStack(alignment: .leading, spacing: 5) { HStack(spacing: 4) { - Text(story.contentFormat.displayName.uppercased()) + Text(story.contentFormat == .manga ? "MANGA" : story.sourceProvider.displayName.uppercased()) .fableFont(size: 8, weight: .bold) .padding(.horizontal, 5) .padding(.vertical, 2) diff --git a/frontend/FableApp/Features/Library/Views/LibraryView.swift b/frontend/FableApp/Features/Library/Views/LibraryView.swift index 78647a4..7a46727 100644 --- a/frontend/FableApp/Features/Library/Views/LibraryView.swift +++ b/frontend/FableApp/Features/Library/Views/LibraryView.swift @@ -70,6 +70,16 @@ public struct LibraryView: View { && (selectedFilter == "All" || store.storyMatchesCategory(story, category: selectedFilter)) } } + + private var visibleStandardEbooksStories: [Story] { + let base = store.standardEbooksStories.isEmpty + ? store.stories.filter { $0.sourceProvider == .standardEbooks } + : store.standardEbooksStories + return base.filter { story in + !PersistenceService.legacyDemoStoryIds.contains(story.id) + && (selectedFilter == "All" || store.storyMatchesCategory(story, category: selectedFilter)) + } + } public init() {} @@ -426,6 +436,15 @@ public struct LibraryView: View { stories: visiblePopularGutenbergStories ) } + + if !visibleStandardEbooksStories.isEmpty { + providerBookCollection( + title: "Standard Ebooks", + subtitle: "Typography-first public-domain editions", + badge: "STANDARD EBOOKS", + stories: visibleStandardEbooksStories + ) + } // Complete library catalog VStack(alignment: .leading, spacing: 12) { From 2d29bb1735ba78b7bebbd86c963193acbd7837d4 Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 10:30:39 +0800 Subject: [PATCH 4/8] test(ios): verify same-title editions stay distinct across providers --- .../StorySummaryDecodingTests.swift | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/frontend/FableAppTests/StorySummaryDecodingTests.swift b/frontend/FableAppTests/StorySummaryDecodingTests.swift index 08f2f33..1812421 100644 --- a/frontend/FableAppTests/StorySummaryDecodingTests.swift +++ b/frontend/FableAppTests/StorySummaryDecodingTests.swift @@ -337,4 +337,44 @@ final class StorySummaryDecodingTests: XCTestCase { XCTAssertEqual(staleIDs, [staleUnengagedId]) } + + @MainActor + func testSameTitleEditionsAcrossProvidersStayDistinctInPersistence() { + let service = PersistenceService(isStoredInMemoryOnly: true) + let gutenbergId = UUID(uuidString: "00000000-0000-0000-0000-000000000159")! + let standardEbooksId = UUID(uuidString: "4E39AB55-D25A-52A0-AD55-832F2FC8DA8E")! + + let gutenbergEdition = Story( + id: gutenbergId, + title: "Dracula", + author: "Bram Stoker", + genre: "Gothic", + excerpt: "Gutenberg plain text edition.", + readingTimeMinutes: 650, + sourceProvider: .gutenberg, + providerId: "345" + ) + let standardEbooksEdition = Story( + id: standardEbooksId, + title: "Dracula", + author: "Bram Stoker", + genre: "Horror", + excerpt: "Standard Ebooks typography edition.", + readingTimeMinutes: 700, + sourceProvider: .standardEbooks, + providerId: "bram-stoker/dracula" + ) + + service.saveStory(gutenbergEdition) + service.saveStory(standardEbooksEdition) + + let restoredGutenberg = service.fetchStory(id: gutenbergId) + let restoredStandardEbooks = service.fetchStory(id: standardEbooksId) + + XCTAssertEqual(restoredGutenberg?.sourceProvider, .gutenberg) + XCTAssertEqual(restoredGutenberg?.providerId, "345") + XCTAssertEqual(restoredStandardEbooks?.sourceProvider, .standardEbooks) + XCTAssertEqual(restoredStandardEbooks?.providerId, "bram-stoker/dracula") + XCTAssertNotEqual(restoredGutenberg?.id, restoredStandardEbooks?.id) + } } From 49268c026add3baac8be248ca15f13d84ebd1a28 Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 10:30:39 +0800 Subject: [PATCH 5/8] docs(catalog): document federated Standard Ebooks endpoints and edition identity --- docs/DATA_SOURCES_AND_API_STRATEGY.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/DATA_SOURCES_AND_API_STRATEGY.md b/docs/DATA_SOURCES_AND_API_STRATEGY.md index 053c9e9..7e1ad86 100644 --- a/docs/DATA_SOURCES_AND_API_STRATEGY.md +++ b/docs/DATA_SOURCES_AND_API_STRATEGY.md @@ -86,6 +86,11 @@ If the goal is to access a vast, pre-existing library of real-world literature w - **Source:** Standard Ebooks Public Domain Catalog - **What It Provides:** Professionally formatted, typography-first public domain editions (e.g. *Frankenstein: The 1818 Text*, *The Metamorphosis*). - **Format:** Ingested as `ContentFormat.prose` with provenance `SourceProvider.standardEbooks`. +- **Endpoints:** + - `GET /api/v1/public/standard-ebooks?topic={topic}&search={search}`: Returns catalog metadata and official cover URLs with deterministic `UUIDv5` story IDs derived from `book:{slug}`. + - `GET /api/v1/public/standard-ebooks/story?book_id={slug}`: Resolves metadata for a single Standard Ebooks work by slug path. + - `GET /api/v1/public/standard-ebooks/chapters?book_id={slug}`: Downloads and parses semantic XHTML chapters on demand from Standard Ebooks' single-page reading endpoint. +- **Edition Identity:** Same-title works from Project Gutenberg (`GUTENBERG`) and Standard Ebooks (`STANDARD_EBOOKS`) retain distinct `id`, `sourceProvider`, and `providerId` values across discovery, local persistence, chapter caches, and shelf progress. ### D. MangaDex Graphic Manga API - **Base Endpoint:** `https://api.mangadex.org` @@ -159,5 +164,5 @@ In the iOS client, fetching live data follows a clean three-layer separation of 1. Start the backend with `docker compose up -d --build`. Compose maps host port `8001` to container port `8000`; check `http://127.0.0.1:8001/api/v1/health`. 2. The iOS Debug build uses `http://127.0.0.1:8001/api/v1` by default. Use an HTTPS API URL for Release builds. -3. The catalog endpoint returns provider metadata and official cover URLs without downloading every book's text. -4. `ReaderView` requests Gutenberg chapters from `/api/v1/public/gutenberg/{id}/chapters` when a user opens a book. The backend fetches and parses the official plain-text source, then caches chapters for subsequent reads. +3. The catalog endpoints (`/api/v1/public/gutenberg` and `/api/v1/public/standard-ebooks`) return provider metadata and official cover URLs without downloading every book's text. Clients query each provider endpoint independently so partial provider outages surface a clear status warning without dropping results from healthy providers. +4. `ReaderView` requests Gutenberg chapters from `/api/v1/public/gutenberg/{id}/chapters` or Standard Ebooks chapters from `/api/v1/public/standard-ebooks/chapters?book_id={slug}` when a user opens a book. The backend fetches and parses the official source text on demand, then caches chapters for subsequent reads. From 9def52a9087394d4dd23de959ca281c4946e4824 Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 12:51:55 +0800 Subject: [PATCH 6/8] docs(walkthrough): document federated provider endpoints and feature journeys --- .../08_FEATURE_CATALOG_AND_USER_JOURNEYS.md | 67 +++++++++++++------ docs/simulator_captures/README.md | 39 +++++++---- 2 files changed, 75 insertions(+), 31 deletions(-) diff --git a/docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md b/docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md index de1384b..5a19149 100644 --- a/docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md +++ b/docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md @@ -1,27 +1,29 @@ # Fable iOS: Feature Catalog & User Journey Architecture -**Document Version:** 1.0.0 -**Target Milestone:** Midterm Presentation & Technical Defense +**Document Version:** 1.1.0 +**Target Milestone:** Capstone Final Defense & Federated Multi-Provider Architecture **Author:** Roosc Zaño (`@zanoroosc`) --- ## 1. Complete Functional Feature Catalog -Fable delivers a comprehensive literary ecosystem spanning discovery, deep reading, community writing, and personal scholarship: +Fable delivers a comprehensive literary ecosystem spanning federated discovery, deep reading, community writing, and personal scholarship: ``` -┌────────────────────────────────────────────────────────────────────────┐ -│ FABLE FEATURE ECOSYSTEM │ -├───────────────────┬────────────────────┬───────────────────────────────┤ -│ DISCOVERY │ DEEP READING │ WRITING & SCHOLARSHIP │ -├───────────────────┼────────────────────┼───────────────────────────────┤ -│ • Tale of the Day │ • Dynamic Paging │ • Story Composer (WriteView) │ -│ • Curator's Pick │ • 3 Ambient Themes │ • Real-Time Word Counter │ -│ • Writer Carousel │ • Oral Audio Sync │ • Personal Shelf Hub │ -│ • Genre Filtering │ • Marginalia Notes │ • Excerpted Quote Journal │ -│ • Full-Text Search│ • Typography HUD │ • Live Reading Analytics │ -└───────────────────┴────────────────────┴───────────────────────────────┘ +┌───────────────────────────────────────────────────────────────────────────────────┐ +│ FABLE FEATURE ECOSYSTEM │ +├───────────────────────┬────────────────────┬──────────────────────────────────────┤ +│ DISCOVERY │ DEEP READING │ WRITING & SCHOLARSHIP │ +├───────────────────────┼────────────────────┼──────────────────────────────────────┤ +│ • Federated Providers │ • Dynamic Paging │ • Story Composer (WriteView) │ +│ (Standard Ebooks & │ • 3 Ambient Themes │ • Real-Time Word Counter │ +│ Project Gutenberg) │ • Oral Audio Sync │ • Personal Shelf Hub │ +│ • Cross-Provider ID │ • Marginalia Notes │ • Excerpted Quote Journal │ +│ • Provider Fault Iso │ • Typography HUD │ • Live Reading Analytics │ +│ • Tale of the Day │ • TOC & Chapter │ • Multi-Device Shelf Sync │ +│ • Full-Text Search │ Hydration │ • Community Author Profiles │ +└───────────────────────┴────────────────────┴──────────────────────────────────────┘ ``` --- @@ -29,14 +31,20 @@ Fable delivers a comprehensive literary ecosystem spanning discovery, deep readi ## 2. Feature Deep Dive by Subsystem ### 2.1 Discovery & Editorial Curation (`ExploreView.swift` & `LibraryView.swift`) +- **Federated Multi-Provider Catalog:** Seamlessly unifies multiple literature repositories: + - *Standard Ebooks (`STANDARD_EBOOKS`):* Typography-first public domain masterpieces with semantic XHTML chapters and rich SVG/JPEG cover art. + - *Project Gutenberg (`GUTENBERG`):* Massive historical open-access library parsed on demand from plain-text source archives. + - *Fable Originals (`FABLE_ORIGINAL`):* Curated editorial folklore and user-authored community manuscripts. +- **Cross-Provider Edition Disambiguation:** Works sharing identical titles across providers (e.g. Mary Shelley's *Frankenstein* or Franz Kafka's *The Metamorphosis*) retain independent deterministic UUIDv5 identifiers, provider badges, distinct chapter counts, and separate shelf progress. - **Tale of the Day:** A prominent daily featured story card complete with procedural art, author badge, reading duration, and direct "Read Now" action. - **Curator's Spotlight:** Highlights critical masterpieces or obscure regional folklore hand-picked for the reader. - **Trending Writers Carousel:** Horizontal scroll showcasing historical scribes and modern community writers with calculated ratings and story counts. - **Genre Categorization:** Dedicated genre hubs (Folklore, Mythology, Gothic, Classic Fiction, Classic Mystery) with reader metrics and rich descriptions. -- **Full-Text Live Search:** Real-time query matching filtering simultaneously across story titles, author names, and synopses with zero lag. +- **Full-Text Live Search:** Real-time query matching filtering simultaneously across story titles, author names, and synopses with independent provider query dispatch and zero lag. ### 2.2 The Ambient Reader Experience (`ReaderView.swift`) - **Physical Book Pagination:** Rather than an endless vertical web-scroll, manuscripts are algorithmically divided into numbered physical book pages (`PacingEngine.swift`). +- **On-Demand Chapter Hydration:** Catalog metadata remains lightweight; full multi-chapter content is fetched on demand from `/api/v1/public/gutenberg/{id}/chapters` or `/api/v1/public/standard-ebooks/chapters?book_id={slug}` and cached locally for offline continuity. - **3 Meditative Themes:** - *Parchment (Default):* Warm sepia and cream tones inspired by antique paper. - *Noir:* Pure OLED black background with muted ivory text to prevent eye strain in dark rooms. @@ -56,6 +64,10 @@ Fable delivers a comprehensive literary ecosystem spanning discovery, deep readi - **Excerpted Quote Journal:** Interactive card deck displaying user highlights annotated during reading, complete with story attribution. - **Reader Analytics:** Live SwiftData-backed tracking of reading streaks (consecutive days), total minutes read, and words consumed. +### 2.5 Architectural Resilience & Fault Isolation +- **Independent Provider Ingestion:** `StoryStore` dispatches catalog queries to Project Gutenberg and Standard Ebooks independently. If an upstream provider fails or times out, the client displays an informative inline badge without crashing or hiding results from healthy providers. +- **Offline Determinism:** Previously hydrated stories and chapters remain 100% accessible in local storage even when completely disconnected from the network. + --- ## 3. User Journey State Diagrams @@ -109,11 +121,11 @@ flowchart TD ### 3.4 Journey 4: Writing & Publishing a Community Story ```mermaid flowchart TD - A[Navigate to Write Tab] --> B[Enter Title, Genre, Synopsis, Content] - B --> C[PacingEngine updates live word count & read time] + A[Navigate to Write Tab] --> B["Enter Title, Genre, Synopsis, Content"] + B --> C["PacingEngine updates live word count & read time"] C --> D{Is Title & Content non-empty?} D -- No --> E[Publish Button Disabled] - D -- Yes --> F[Tap 'Publish Story'] + D -- Yes --> F["Tap 'Publish Story'"] F --> G[StoryStore creates new Story model] G --> H[Saved to SwiftData & Appended to Library] H --> I[Success Sheet: Story published to Shelf] @@ -121,6 +133,23 @@ flowchart TD --- +### 3.5 Journey 5: Federated Source Discovery, Edition Selection, and Fault-Tolerant Hydration +```mermaid +flowchart TD + A["Search Query: 'Frankenstein'"] --> B["Dispatch Async Queries"] + B --> C["GET /api/v1/public/gutenberg?search=Frankenstein"] + B --> D["GET /api/v1/public/standard-ebooks?search=Frankenstein"] + C --> E["Results: Gutenberg 1831 Edition (Plain-Text Source)"] + D --> F["Results: Standard Ebooks 1818 Edition (Semantic XHTML Source)"] + E & F --> G["Unified Search Feed with Distinct Provider Badges"] + G --> H["User Selects Standard Ebooks Edition"] + H --> I["GET /api/v1/public/standard-ebooks/chapters?book_id=mary-shelley_frankenstein"] + I --> J["Backend Parses XHTML Sections & Returns Chapters"] + J --> K["ReaderView Opens at Chapter 1 • Local Cache Populated"] +``` + +--- + ## 4. Defense Talking Point: "What Makes Fable's User Experience Unique?" -> *"Fable is not simply an e-reader; it is an ambient reading sanctuary. Where commercial reading apps bombard the user with paywalls, social feeds, and ads, Fable strips away digital distractions. By integrating real-time physical page turning, an on-device oral speech synthesizer that breathes life into traditional folklore, and an academic marginalia quote deck, Fable elevates reading into a focused, reflective, and scholarship-grade experience."* +> *"Fable is not simply an e-reader; it is an ambient reading sanctuary. Where commercial reading apps bombard the user with paywalls, social feeds, and ads, Fable strips away digital distractions. By integrating real-time physical page turning, an on-device oral speech synthesizer that breathes life into traditional folklore, an academic marginalia quote deck, and a federated public-domain literature catalog uniting Project Gutenberg and Standard Ebooks, Fable elevates reading into a focused, reflective, and scholarship-grade experience."* diff --git a/docs/simulator_captures/README.md b/docs/simulator_captures/README.md index 843ff51..7ea1099 100644 --- a/docs/simulator_captures/README.md +++ b/docs/simulator_captures/README.md @@ -1,12 +1,26 @@ # Fable iOS — UI & Endpoint Screenshot Gallery -This directory contains visual captures of the reachable screens, filter states, reader modes, modal sheets, and live backend API integrations in **Fable iOS**, recorded on an `iPhone 17 Pro` simulator (`iOS 26.5`) via `AUTO_UI_TOUR=1` with `StoryStore.isMangaEnabled = false` against the local FastAPI backend (`http://127.0.0.1:8001/api/v1`) and live Project Gutenberg catalog. +This directory contains visual captures of the reachable screens, filter states, reader modes, modal sheets, and live backend API integrations in **Fable iOS**, recorded on an `iPhone 17 Pro` simulator (`iOS 26.5`) via `AUTO_UI_TOUR=1` with `StoryStore.isMangaEnabled = false` against the local FastAPI backend (`http://127.0.0.1:8001/api/v1`), live Project Gutenberg catalog, and federated Standard Ebooks catalog. ## Full Screen Walkthrough Video - **[`fable_ios_full_walkthrough.mp4`](./fable_ios_full_walkthrough.mp4)** — Screen recording stepping through welcome/authentication sheets, live library feed, classic prose reader, table of contents, display options, dark theme mode, explore filters, live search, genre and author sheets, writer's studio, and shelf/profile/settings views (57.8s, `588x1280` H.264 MP4). --- +## Federated Multi-Provider Discovery & Resilience Architecture + +The reading experience seamlessly federates multiple independent literature sources: +1. **Curated Fable Originals:** Community manuscripts and editorial fables seeded and created locally via `WriteView` or synced via `/api/v1/stories`. +2. **Project Gutenberg (`GUTENBERG`):** Historical public domain literature catalog fetched via `/api/v1/public/gutenberg` with plain-text on-demand chapter hydration. +3. **Standard Ebooks (`STANDARD_EBOOKS`):** High-typography, professionally edited public domain releases queried independently via `/api/v1/public/standard-ebooks` with semantic XHTML chapter extraction. + +### Core Architectural Guarantees: +- **Independent Provider Querying:** `StoryStore` dispatches catalog requests to Project Gutenberg and Standard Ebooks asynchronously and independently. If one upstream provider experiences latency or outages, the client displays a recoverable provider status warning without dropping results from the healthy provider. +- **Cross-Provider Edition Disambiguation:** Works sharing identical titles (e.g. Mary Shelley's *Frankenstein: The 1818 Text* on Standard Ebooks vs. the 1831 Gutenberg edition) retain distinct, deterministic `UUIDv5` story identifiers, independent `sourceProvider` tags, and isolated reading progress bars. +- **On-Demand Chapter Ingestion:** Catalog responses only load lightweight metadata and official cover art; full chapter text is retrieved on demand when the reader mounts a story, caching chapters locally for offline continuity. + +--- + ## Screenshot Index (22 Captures) | # | File | Screen / State | Connected Backend API Endpoint(s) | @@ -14,24 +28,25 @@ This directory contains visual captures of the reachable screens, filter states, | 01 | [`01_welcome_screen.png`](./01_welcome_screen.png) | Welcome Gateway (`BOOKS & FABLES`) | — | | 02 | [`02_auth_sign_in_sheet.png`](./02_auth_sign_in_sheet.png) | Sign In Modal Sheet | `POST /api/v1/auth/login`, `POST /api/v1/auth/password-reset/request` | | 03 | [`03_auth_create_account_sheet.png`](./03_auth_create_account_sheet.png) | Create Account Modal Sheet | `POST /api/v1/auth/register` | -| 04 | [`04_library_filter_all.png`](./04_library_filter_all.png) | Library — Filter: `All` (Live Cloud catalog) | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg?topic=fiction`, `GET /api/v1/updates` | -| 12 | [`12_reader_fable_chapter_1.png`](./12_reader_fable_chapter_1.png) | Reader — Opening Title (*The radio man returns*, Sepia, Ch. 1 • Page 1/47) | `GET /api/v1/public/gutenberg/{gutenberg_id}/chapters` | +| 04 | [`04_library_filter_all.png`](./04_library_filter_all.png) | Library — Filter: `All` (Federated Cloud catalog: Originals, Gutenberg, Standard Ebooks) | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg?topic=fiction`, `GET /api/v1/public/standard-ebooks`, `GET /api/v1/updates` | +| 12 | [`12_reader_fable_chapter_1.png`](./12_reader_fable_chapter_1.png) | Reader — Opening Title (*The radio man returns*, Sepia, Ch. 1 • Page 1/47) | `GET /api/v1/public/gutenberg/{gutenberg_id}/chapters` / `GET /api/v1/public/standard-ebooks/chapters?book_id={slug}` | | 13 | [`13_reader_classic_book_chapter_1.png`](./13_reader_classic_book_chapter_1.png) | Reader — Classic Book Fallback (*The radio man returns*, Ch. 1 • Page 1/47) | `GET /api/v1/public/gutenberg/{gutenberg_id}/chapters` | -| 14 | [`14_reader_table_of_contents_sheet.png`](./14_reader_table_of_contents_sheet.png) | Reader — Table of Contents Sheet | `GET /api/v1/public/gutenberg/{gutenberg_id}/chapters` | +| 14 | [`14_reader_table_of_contents_sheet.png`](./14_reader_table_of_contents_sheet.png) | Reader — Table of Contents Sheet | `GET /api/v1/public/gutenberg/{gutenberg_id}/chapters` / `GET /api/v1/public/standard-ebooks/chapters?book_id={slug}` | | 15 | [`15_reader_display_options_sheet.png`](./15_reader_display_options_sheet.png) | Reader — Display Options (Typography & Theme) Sheet | Local `UserDefaults` + Dynamic Type | | 16 | [`16_reader_dark_theme_mode.png`](./16_reader_dark_theme_mode.png) | Reader — Midnight Dark Theme Mode | Local `UserDefaults` + Pacing Engine | -| 17 | [`17_explore_discovery_all.png`](./17_explore_discovery_all.png) | Explore — Discovery Catalog (`All`, 3 derived categories & top authors) | `GET /api/v1/genres`, `GET /api/v1/authors/top` | -| 18 | [`18_explore_filter_under_5_mins.png`](./18_explore_filter_under_5_mins.png) | Explore — Filter: `Under 5 mins` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg` | -| 19 | [`19_explore_filter_community_favorites.png`](./19_explore_filter_community_favorites.png) | Explore — Filter: `Community Favorites` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg` | -| 20 | [`20_explore_filter_quick_reads.png`](./20_explore_filter_quick_reads.png) | Explore — Filter: `Quick Reads` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg` | -| 21 | [`21_explore_live_search_results.png`](./21_explore_live_search_results.png) | Explore — Live Search Query (`"Sherlock"`, 12 results) | `GET /api/v1/stories?search=Sherlock`, `GET /api/v1/public/gutenberg?search=Sherlock` | -| 22 | [`22_explore_genre_detail_view.png`](./22_explore_genre_detail_view.png) | Explore — Genre Detail View (`Fantasy fiction`) | `GET /api/v1/genres`, `GET /api/v1/public/gutenberg` | -| 23 | [`23_explore_author_detail_sheet.png`](./23_explore_author_detail_sheet.png) | Explore — Author Detail Sheet (`Various`) | `GET /api/v1/authors/top`, `GET /api/v1/public/gutenberg?search=Various` | +| 17 | [`17_explore_discovery_all.png`](./17_explore_discovery_all.png) | Explore — Discovery Catalog (`All`, 3 derived categories & top authors) | `GET /api/v1/genres`, `GET /api/v1/authors/top`, `GET /api/v1/public/standard-ebooks` | +| 18 | [`18_explore_filter_under_5_mins.png`](./18_explore_filter_under_5_mins.png) | Explore — Filter: `Under 5 mins` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg`, `GET /api/v1/public/standard-ebooks` | +| 19 | [`19_explore_filter_community_favorites.png`](./19_explore_filter_community_favorites.png) | Explore — Filter: `Community Favorites` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg`, `GET /api/v1/public/standard-ebooks` | +| 20 | [`20_explore_filter_quick_reads.png`](./20_explore_filter_quick_reads.png) | Explore — Filter: `Quick Reads` | `GET /api/v1/stories`, `GET /api/v1/public/gutenberg`, `GET /api/v1/public/standard-ebooks` | +| 21 | [`21_explore_live_search_results.png`](./21_explore_live_search_results.png) | Explore — Live Search Query (`"Sherlock"`, 12 results across Gutenberg & Standard Ebooks) | `GET /api/v1/stories?search=Sherlock`, `GET /api/v1/public/gutenberg?search=Sherlock`, `GET /api/v1/public/standard-ebooks?search=Sherlock` | +| 22 | [`22_explore_genre_detail_view.png`](./22_explore_genre_detail_view.png) | Explore — Genre Detail View (`Fantasy fiction`) | `GET /api/v1/genres`, `GET /api/v1/public/gutenberg`, `GET /api/v1/public/standard-ebooks` | +| 23 | [`23_explore_author_detail_sheet.png`](./23_explore_author_detail_sheet.png) | Explore — Author Detail Sheet (`Various`) | `GET /api/v1/authors/top`, `GET /api/v1/public/gutenberg?search=Various`, `GET /api/v1/public/standard-ebooks?search=Various` | | 24 | [`24_write_studio_editor.png`](./24_write_studio_editor.png) | Writer's Studio — Manuscript Editor (*The Clockwork Nightingale*) | `POST /api/v1/stories`, `GET /api/v1/auth/me/stories` | -| 25 | [`25_shelf_tab_saved.png`](./25_shelf_tab_saved.png) | My Shelf — `Saved` Tab & Reading Journal Stats | `GET /api/v1/shelf`, `GET /api/v1/auth/me/reading-stats` | +| 25 | [`25_shelf_tab_saved.png`](./25_shelf_tab_saved.png) | My Shelf — `Saved` Tab & Reading Journal Stats (Provider Provenance Badges) | `GET /api/v1/shelf`, `GET /api/v1/auth/me/reading-stats` | | 26 | [`26_shelf_tab_finished.png`](./26_shelf_tab_finished.png) | My Shelf — `Finished` Tab (*It all begins again*) | `POST /api/v1/shelf/sync` | | 27 | [`27_shelf_tab_my_drafts.png`](./27_shelf_tab_my_drafts.png) | My Shelf — `My Drafts` Tab | `GET /api/v1/auth/me/stories` | | 28 | [`28_profile_sheet.png`](./28_profile_sheet.png) | Guest Author Profile Modal Sheet | `GET /api/v1/auth/me`, `PATCH /api/v1/auth/me`, `DELETE /api/v1/auth/me` | | 29 | [`29_settings_sheet.png`](./29_settings_sheet.png) | Settings & System Diagnostics Sheet | `GET /api/v1/health` | > **Note:** Library category filter captures `05`–`11` (`Fables`, `Classics`, `Mystery`, `Fiction`, `Gothic`, `Romance`, `Adventure`) are skipped by `AUTO_UI_TOUR` when the live Gutenberg fiction catalog only yields `Fantasy fiction`, `Science fiction`, and `Short stories`. + From 8819a1fc7a7cf9d6c1318ab42540a6d2031053c3 Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 12:51:55 +0800 Subject: [PATCH 7/8] docs(architecture): incorporate federated provider topology and fault isolation --- docs/ARCHITECTURE.md | 24 ++++++++++++++---------- docs/SYSTEM_DESIGN.md | 10 ++++++++++ 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 09e4661..a300b8b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -72,13 +72,16 @@ └────────────────────┼──────────────────────────────┼────────────────────┘ │ │ ▼ ▼ -┌──────────────────────────────────────┐ ┌──────────────────────────────┐ -│ LOCAL PERSISTENCE ENGINE │ │ FASTAPI BACKEND TIER │ -│ - SwiftData / SQLite ModelContainer │ │ - Python 3.11+ / FastAPI │ -│ - KeychainStore (Auth tokens) │ │ - Multi-tenant shelf sync │ -│ - Pure Zero-Baseline Analytics │ │ - 22 Pytest Automated Cases │ -│ - 100% Offline functional guarantee │ │ - Interactive Swagger /docs │ -└──────────────────────────────────────┘ └──────────────────────────────┘ +┌──────────────────────────────────────┐ ┌──────────────────────────────────────┐ +│ LOCAL PERSISTENCE ENGINE │ │ FASTAPI BACKEND TIER │ +│ - SwiftData / SQLite ModelContainer │ │ - Python 3.9+ / FastAPI Framework │ +│ - KeychainStore (Auth tokens) │ │ - Federated Prose Providers: │ +│ - Pure Zero-Baseline Analytics │ │ • Standard Ebooks (Semantic XHTML)│ +│ - 100% Offline functional guarantee │ │ • Project Gutenberg (Plain-Text) │ +│ - Cross-provider edition isolation │ │ - Multi-tenant shelf synchronization│ +│ │ │ - 100+ Automated Pytest Cases │ +│ │ │ - Interactive Swagger OpenAPI /docs │ +└──────────────────────────────────────┘ └──────────────────────────────────────┘ ``` --- @@ -89,15 +92,16 @@ The Model layer represents pure business entities, value objects, and styling configurations. Models are completely isolated from SwiftUI view logic and controllers. - **Type Safety & Protocols:** Conforms to `Identifiable`, `Codable`, and `Equatable`. - **Key Entities:** - - `Story`: Core entity containing unique `id: UUID`, `title: String`, `author: String`, `genre: Genre`, `contentFormat: ContentFormat` (`.prose`, `.manga`), `sourceProvider: SourceProvider` (`.gutenberg`, `.standardEbooks`, `.mangadex`), `synopsis: String`, `content: String`, `chapters: [Chapter]`, `readTimeMinutes: Int`, `isBookmarked: Bool`, `isCompleted: Bool`, `readingProgress: Double`, and `coverImageUrl: String?`. + - `Story`: Core entity containing unique deterministic `id: UUID` (derived via UUIDv5 for federated provider works to ensure edition stability), `title: String`, `author: String`, `genre: Genre`, `contentFormat: ContentFormat` (`.prose`, `.manga`), `sourceProvider: SourceProvider` (`.fableOriginal`, `.gutenberg`, `.standardEbooks`, `.mangadex`), `providerId: String?`, `synopsis: String`, `content: String`, `chapters: [Chapter]`, `readTimeMinutes: Int`, `isBookmarked: Bool`, `isCompleted: Bool`, `readingProgress: Double`, and `coverImageUrl: String?`. - `Chapter`: Sequential reading unit with `id: String`, `title: String`, `chapterNumber: Int`, `content: String`, and `pageUrls: [String]` (sequential graphic panel URLs for manga). - `ContentFormat`: Explicit format discriminator (`.prose`, `.manga`). - - `SourceProvider`: Catalog source provenance (`.gutenberg`, `.standardEbooks`, `.mangadex`). + - `SourceProvider`: Catalog source provenance (`.fableOriginal`, `.gutenberg`, `.standardEbooks`, `.mangadex`). - `UserReadingStats`: Pure zero-baseline living analytics derived without artificial stat floors. - `ReaderTheme` & `ReaderFont`: Configurable appearance value objects for custom typography rendering. +- **Cross-Provider Edition Disambiguation:** Works sharing the same literary title across different providers (e.g., Mary Shelley's *Frankenstein* on Standard Ebooks vs Project Gutenberg) maintain distinct `id`, `sourceProvider`, and `providerId` attributes. This ensures chapter caches, reading positions, and shelf states never collide. ### 3.2 Controller & Service Layer (`frontend/FableApp/Features/`) -- **`StoryStore` & `StoryController`:** Coordinate state mutations, catalog search, format filtering, and bidirectional cloud synchronization with Last-Write-Wins (LWW) conflict resolution. +- **`StoryStore` & `StoryController`:** Coordinate state mutations, catalog search, format filtering, independent multi-provider query dispatch (Gutenberg and Standard Ebooks), fault isolation, and bidirectional cloud synchronization with Last-Write-Wins (LWW) conflict resolution. - **`AudioNarratorController`:** `AVSpeechSynthesizer` state machine orchestrating text-to-speech audio, voice audition, and active chapter tracking. - **`AuthManager` & `KeychainStore`:** Manage multi-tenant session tokens, BCrypt registration/login requests, and encrypted keychain storage. - **`PacingEngine`:** Dynamic word tokenization and zoom-invariant reading speed calculation. diff --git a/docs/SYSTEM_DESIGN.md b/docs/SYSTEM_DESIGN.md index 5ac9ffb..33a4f34 100644 --- a/docs/SYSTEM_DESIGN.md +++ b/docs/SYSTEM_DESIGN.md @@ -163,6 +163,16 @@ Fable is engineered as a high-reliability, typography-first e-reading and manusc --- +### Pillar 6: Federated Multi-Source Literature & Fault-Isolation Engine +* **Engineering Problem:** Relying on a single upstream public domain provider (e.g. only Project Gutenberg or only local seeds) creates single points of failure, restricts typography quality, and risks data collisions when multiple editions of the same classic work are imported. +* **System Solution:** A contract-driven federated provider architecture: + 1. **Federated Ingestion:** The shared FastAPI tier exposes dedicated endpoints for **Standard Ebooks** (`/api/v1/public/standard-ebooks`, `/story`, `/chapters`) and **Project Gutenberg** (`/api/v1/public/gutenberg`, `/chapters`). + 2. **Edition Disambiguation:** Works sharing the same title (e.g. *Frankenstein* or *The Metamorphosis*) are assigned deterministic `UUIDv5` identifiers scoped by source namespace (`book:{slug}` or `gutenberg:{id}`). Both editions coexist peacefully across search feeds, offline caches, and personal shelf records. + 3. **Fault Isolation:** `StoryStore` requests provider feeds asynchronously and independently. If one provider times out or fails upstream, healthy provider stories populate the catalog immediately while a non-intrusive warning badge indicates the partial outage. + 4. **On-Demand Semantic XHTML Hydration:** Catalog browsing remains lightweight (<250 KB payload). Full multi-chapter text is fetched on demand and parsed from semantic XHTML or plain text only when the reader opens the story. + +--- + ## 4. Asset-Decoupled Blank Placeholder Design System To achieve **100% operational consistency across every Mac lab computer**, the visual design system replaces fragile bitmap dependencies with procedural typography cards: From 0d69dba58ce296de83c2eb47e21dc98a23725cdc Mon Sep 17 00:00:00 2001 From: ur1el0 Date: Mon, 16 Nov 2026 12:51:55 +0800 Subject: [PATCH 8/8] docs(repo): update handoff context and root readme for federated book sources --- README.md | 11 ++++++----- docs/AGENT_HANDOFF_CONTEXT.md | 30 ++++++++++++++++++------------ 2 files changed, 24 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 50d6c3b..00b5a20 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,10 @@ [![Pydantic v2](https://img.shields.io/badge/Contract-Pydantic%20v2-e92063.svg)](https://docs.pydantic.dev/) [![Database](https://img.shields.io/badge/Database-SQLite%20%2B%20PostgreSQL-4169E1.svg)](https://www.sqlite.org/) [![Pytest](https://img.shields.io/badge/Backend%20Tests-100%20Passed-brightgreen.svg)](https://pytest.org) -[![XCTest](https://img.shields.io/badge/iOS%20Tests-22%20Passed-brightgreen.svg)](https://developer.apple.com/xcode/) +[![XCTest](https://img.shields.io/badge/iOS%20Tests-28%20Passed-brightgreen.svg)](https://developer.apple.com/xcode/) [![Figma Prototype](https://img.shields.io/badge/Figma-100%25%20Prototype-pink.svg)](https://www.figma.com/proto/fable-ios-prototype-midterm) -**Fable** is a native iOS literary reading and community publishing platform with a companion FastAPI REST backend, engineered as a distraction-free sanctuary for **open-source classic books, world folklore, timeless fables, and original community manuscripts**. Fable couples a refined editorial aesthetic with an offline-first, contract-first system architecture: the live catalog returns provider metadata and official covers, while the reader fetches chapter text when a book is opened and caches it for offline reading. +**Fable** is a native iOS literary reading and community publishing platform with a companion FastAPI REST backend, engineered as a distraction-free sanctuary for **federated open-source classic books (Standard Ebooks & Project Gutenberg), world folklore, timeless fables, and original community manuscripts**. Fable couples a refined editorial aesthetic with an offline-first, contract-first system architecture: the live catalog returns federated provider metadata and official covers without downloading every book's text, while the reader fetches chapter text on demand when a book is opened and caches it for offline reading. > [!NOTE] > **Open-Source Literature Focus (`StoryStore.isMangaEnabled = false`):** Manga remains disabled by default on iOS while chapter continuity and rights are unverified (see [`ADR 0002`](docs/adr/0002-ios-open-source-literature-focus-and-manga-feature-flag.md) and [`docs/DATA_SOURCES_AND_API_STRATEGY.md`](docs/DATA_SOURCES_AND_API_STRATEGY.md)). @@ -22,10 +22,11 @@ | Document | Purpose | |---|---| -| **[`docs/AGENT_HANDOFF_CONTEXT.md`](docs/AGENT_HANDOFF_CONTEXT.md)** | Architecture notes, current implementation boundaries, and verification guidance | +| **[`docs/AGENT_HANDOFF_CONTEXT.md`](docs/AGENT_HANDOFF_CONTEXT.md)** | Architecture notes, active branch milestones (`feat/federated-book-sources`), and verification guidance | +| **[`docs/DATA_SOURCES_AND_API_STRATEGY.md`](docs/DATA_SOURCES_AND_API_STRATEGY.md)** | Federated provider metadata, Standard Ebooks & Gutenberg endpoints, on-demand chapter loading, and edition identity | +| **[`docs/simulator_captures/README.md`](docs/simulator_captures/README.md)** | **29 Retina iOS Simulator Screenshots** + **Full Walkthrough Video (`fable_ios_full_walkthrough.mp4`)** + Federated Endpoint Index | +| **[`docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md`](docs/presentation/08_FEATURE_CATALOG_AND_USER_JOURNEYS.md)** | Complete functional feature catalog, user journey state machines, and federated discovery flows | | **[`docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`](docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md)** | **Plan 06:** 4-Phase Security & Architecture Hardening Plan (`SEC-01`–`SEC-04`, `PERF-01`–`PERF-03`, `DOM-01`–`DOM-02`, `IOS-01`–`IOS-02`) | -| **[`docs/simulator_captures/README.md`](docs/simulator_captures/README.md)** | **29 Retina iOS Simulator Screenshots** across every screen/filter/modal + **Full Walkthrough Video (`fable_ios_full_walkthrough.mp4`)** | -| **[`docs/DATA_SOURCES_AND_API_STRATEGY.md`](docs/DATA_SOURCES_AND_API_STRATEGY.md)** | Live provider metadata, official covers, on-demand book chapters, and upstream source limits | | **[`docs/RENDER_NEON_DEPLOYMENT.md`](docs/RENDER_NEON_DEPLOYMENT.md)** | Free-tier Render + Neon deployment setup, limits, secrets, and operator steps | | **[`docs/adr/`](docs/adr/)** | Architecture Decision Records: [`ADR 0001`](docs/adr/0001-password-hash-versioning.md) (Password Hashing), [`ADR 0002`](docs/adr/0002-ios-open-source-literature-focus-and-manga-feature-flag.md) (Manga Feature Flag), [`ADR 0003`](docs/adr/0003-comprehensive-catalog-seeding-and-chapter-1-continuity.md) (Catalog Seeding), [`ADR 0004`](docs/adr/0004-render-neon-postgres-deployment.md) (Render + Neon) | | **[`docs/final_milestone/MASTER_PROGRESS_LOG.md`](docs/final_milestone/MASTER_PROGRESS_LOG.md)** | Chronological engineering progress log across all phases and PRs | diff --git a/docs/AGENT_HANDOFF_CONTEXT.md b/docs/AGENT_HANDOFF_CONTEXT.md index 13a436f..a63122d 100644 --- a/docs/AGENT_HANDOFF_CONTEXT.md +++ b/docs/AGENT_HANDOFF_CONTEXT.md @@ -1,8 +1,8 @@ # Fable iOS — Agent Handoff & Full Session Context -**Last Updated:** 2026-11-13 -**Active Git Branch:** `feat/security-and-architecture-remediation` *(Plan 06 complete; ready for PR review/merge into `main`)* -**Primary Next Task:** Open and merge the PR for `feat/security-and-architecture-remediation` after final verification. +**Last Updated:** 2026-11-16 +**Active Git Branch:** `feat/federated-book-sources` +**Primary Current Focus:** Federated literature sources (Standard Ebooks + Project Gutenberg + Fable Originals), cross-provider edition disambiguation, and upstream failure isolation. --- @@ -10,20 +10,26 @@ If you are an AI coding agent picking up this repository on the developer's laptop, read these three files first: 1. **`docs/AGENT_HANDOFF_CONTEXT.md`** *(this file — complete session history, architectural decisions, exact line numbers, and compiler/runtime gotchas)* -2. **[`docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`](./plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md)** *(the 4-phase hardening specification — completed on `feat/security-and-architecture-remediation`)* -3. **[`docs/DATA_SOURCES_AND_API_STRATEGY.md`](./DATA_SOURCES_AND_API_STRATEGY.md)** *(live provider data, on-demand chapter loading, and why Manga is disabled on iOS)* +2. **[`docs/DATA_SOURCES_AND_API_STRATEGY.md`](./DATA_SOURCES_AND_API_STRATEGY.md)** *(live provider data, Standard Ebooks & Gutenberg endpoints, on-demand chapter loading, and why Manga is disabled on iOS)* +3. **[`docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`](./plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md)** *(the completed 4-phase hardening specification)* --- -## 2. Chronological Summary of Completed Work on `fix/python39-runtime-compatibility` +## 2. Chronological Summary of Completed Engineering Milestones -| Commit | Summary | Key Files Touched | +| Commit / PR | Summary | Key Files Touched | |---|---|---| -| `0c9dfc1` | **Unified Multi-Chapter Catalog Seeding & Chapter 1 Guarantee ("Option 3"):** Seeded 40+ books, classic fables, folklore, and literature directly into `data/curated_catalog.json` and SQLite (`backend/core/database.py`). Every catalog work is structured into multi-chapter `StoryChapterDTO` entries guaranteed to start at Chapter 1 (`chapterNumber == 1`). | `data/curated_catalog.json`, `backend/core/database.py`, `scripts/seed_comprehensive_catalog.py`, `backend/services/gutenberg.py`, `backend/tests/test_api_v1.py` | -| `f0f9c2a` | **Documented Upstream Manga Chapter Gaps & Licensing Risks:** Recorded in `docs/DATA_SOURCES_AND_API_STRATEGY.md` (Section 6) why MangaDex community scanlations exhibit chapter gaps (e.g., *Mushoku Tensei* missing Ch. 79–108; officially licensed series like *One Piece* missing Ch. 1–1162) and copyright/App Store compliance risks. | `docs/DATA_SOURCES_AND_API_STRATEGY.md` | -| `38fcee0` | **Feature-Flagged & Hid Manga on iOS (`StoryStore.isMangaEnabled = false`):** Pivoted the iOS app to focus 100% on open-source books, classic fables, folklore, and community manuscripts. Hid all manga filter pills, sections, genres, and stories across `LibraryView`, `ExploreView`, `GenreDetailView`, `AuthorDetailView`, `ShelfView`, and `WelcomeView`. Replaced manga author in `FEATURED_CATALOG_AUTHORS` with `"Lewis Carroll"` and `"Aesop"`. | `frontend/FableApp/Features/Library/ViewModels/StoryStore.swift`, `LibraryView.swift`, `ExploreView.swift`, `GenreDetailView.swift`, `AuthorDetailView.swift`, `ShelfView.swift`, `WelcomeView.swift`, `backend/services/story_service.py` | -| `90b076e` | **Complete UI Screenshot & Walkthrough Video Archive:** Captured 29 PNG screenshots covering every screen, endpoint, filter pill, reader theme, and modal sheet—plus a continuous walkthrough screen recording (`fable_ios_full_walkthrough.mp4`)—indexed in `docs/simulator_captures/README.md`. | `docs/simulator_captures/*`, `frontend/FableApp/App/ContentView.swift` | -| `c5d9631` | **Security Vulnerabilities & Architecture Remediation Plan (Plan 06):** Audited the full stack for non-manga security flaws and poor architectural planning, producing `docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`. | `docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md`, `docs/plans/README.md` | +| `49268c0` | **Documented Federated Standard Ebooks Endpoints & Edition Identity:** Updated API strategy docs for Standard Ebooks discovery, detail, and XHTML parsing endpoints. | `docs/DATA_SOURCES_AND_API_STRATEGY.md` | +| `2d29bb1` | **Cross-Provider Edition Identity Tests:** Verified same-title works across Standard Ebooks and Gutenberg stay distinct in persistence, chapter cache, and reading progress. | `frontend/FableAppTests/StoryStoreTests.swift` | +| `afee0d8` | **Surfaced Standard Ebooks Shelf & Preserved Edition Identity on iOS:** Added dedicated shelf, provider badges, and UUIDv5 edition isolation in SwiftUI client. | `frontend/FableApp/Features/Library/ViewModels/StoryStore.swift`, `LibraryView.swift`, `ShelfView.swift` | +| `02cdc82` | **Backend Detail & Provider Failure Isolation Tests:** Pytest coverage for single-work detail lookups, upstream error propagation, and fault isolation. | `backend/tests/test_api_v1.py` | +| `31dcb89` | **Standard Ebooks Work Detail Endpoint:** Added `GET /api/v1/public/standard-ebooks/story` and upstream error propagation. | `backend/api/v1/endpoints/public.py`, `backend/services/standard_ebooks.py` | +| `PR #43` | **Fresh Gutenberg Discovery:** Live topic filtering, search query dispatch, and plain-text on-demand chapter parsing. | `backend/services/gutenberg.py`, `frontend/FableApp/Features/Library/ViewModels/StoryStore.swift` | +| `0c9dfc1` | **Unified Multi-Chapter Catalog Seeding & Chapter 1 Guarantee:** Seeded 40+ books, classic fables, folklore, and literature directly into `data/curated_catalog.json` and SQLite. | `data/curated_catalog.json`, `backend/core/database.py`, `scripts/seed_comprehensive_catalog.py` | +| `f0f9c2a` | **Documented Upstream Manga Chapter Gaps & Licensing Risks:** Recorded in `docs/DATA_SOURCES_AND_API_STRATEGY.md` (Section 6) why MangaDex community scanlations exhibit chapter gaps. | `docs/DATA_SOURCES_AND_API_STRATEGY.md` | +| `38fcee0` | **Feature-Flagged & Hid Manga on iOS (`StoryStore.isMangaEnabled = false`):** Pivoted the iOS app to focus 100% on open-source books, classic fables, folklore, and community manuscripts. | `frontend/FableApp/Features/Library/ViewModels/StoryStore.swift`, `LibraryView.swift` | +| `90b076e` | **Complete UI Screenshot & Walkthrough Video Archive:** Captured 29 PNG screenshots covering every screen, endpoint, filter pill, reader theme, and modal sheet. | `docs/simulator_captures/*` | +| `c5d9631` | **Security Vulnerabilities & Architecture Remediation Plan (Plan 06):** Audited the full stack for non-manga security flaws and poor architectural planning. | `docs/plans/06_SECURITY_VULNERABILITIES_AND_ARCHITECTURE_REMEDIATION.md` | ---