Skip to content
ur1el0Public

About

A native iOS reader for literature, folklore, and manga

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Repository files navigation

Fable iOS: Curated Open-Source Books, Classic Fables & Community Literature Platform

Swift 5.10 iOS 17.0+ SwiftUI Architecture FastAPI Pydantic v2 Database Pytest XCTest Figma Prototype

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 and docs/DATA_SOURCES_AND_API_STRATEGY.md).


Quick Documentation & Handoff Index

Document Purpose
docs/AGENT_HANDOFF_CONTEXT.md Architecture notes, active branch milestones (feat/federated-book-sources), and verification guidance
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 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 Complete functional feature catalog, user journey state machines, and federated discovery flows
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/RENDER_NEON_DEPLOYMENT.md Free-tier Render + Neon deployment setup, limits, secrets, and operator steps
docs/adr/ Architecture Decision Records: ADR 0001 (Password Hashing), ADR 0002 (Manga Feature Flag), ADR 0003 (Catalog Seeding), ADR 0004 (Render + Neon)
docs/final_milestone/MASTER_PROGRESS_LOG.md Chronological engineering progress log across all phases and PRs
docs/MAC_LAB_RUNBOOK.md Step-by-step computer lab setup, grading demo runbook, and troubleshooting
docs/WIRELESS_IPHONE_AND_LINUX_SETUP.md One-command wireless backend launcher (start_wireless_server.sh), Fedora Linux setup, and in-app server switcher

1. Tech Stack Overview

Client-Side (iOS)

  • Language & Runtime: Swift 5.10 / Swift 6 Concurrency (@MainActor, Sendable, async/await)
  • Target Operating System: iOS 17.0+ (iPhone & iPad responsive layouts)
  • User Interface: SwiftUI (Declarative state-driven UI, custom geometry readers, safe-area insets, dynamic typography)
  • Reading Engines:
    • Prose Engine: Typographical customizer (font family, theme, line spacing), Table of Contents modal, pacing velocity estimator.
    • Graphic Manga Engine: Cinema-black MangaReaderView with continuous vertical Webtoon scrolling and horizontal swipe pagination.
  • Reactive State Management: Combine framework (@Published, ObservableObject, PassthroughSubject)
  • Local Persistence & Caching: SwiftData & CoreData SQLite engine (ModelContainer, ModelContext, FetchDescriptor)
  • Audio Speech Engine: AVFoundation (AVSpeechSynthesizer, AVSpeechUtterance, regional AVSpeechSynthesisVoice audition sheet)
  • Security & Credential Vault: Apple Security framework (KeychainStore for encrypted token and session storage)
  • Diagnostics Suite: Built-in AppHealthTests and on-device SystemDiagnosticsSheet verifying layout clipping and live ingestion contracts.
  • Networking & HTTP: Native URLSession with ATS enabled; development API base URL is configurable

Server-Side (Backend API)

  • Runtime & Framework: Python 3.9+ / FastAPI (High-performance asynchronous REST API)
  • Data Validation & Contracts: Pydantic v2 with serialization_alias (Strict camelCase client / snake_case server parity)
  • Database & Persistence: SQLite 3 by default for local development; PostgreSQL via Neon for hosted persistence, with additive schema initialization and account-scoped shelf, reading-session, and user records.
  • HTTP Client: HTTPX for live Gutendex/Project Gutenberg and Open Library requests.
  • Security: Salted PBKDF2-HMAC-SHA256 password hashes, SHA-256 digests of random bearer tokens, 30-day session expiry, server-side logout revocation, and operator-key protected provider ingestion.
  • ASGI Web Server: Uvicorn.
  • Automated Testing: Pytest with FastAPI TestClient, plus native iOS XCTest verification in CI.

2. System Architecture

Fable is architected around Feature-Driven Vertical Slices combined with MVVM+S (Model-View-ViewModel + Store/Service) to achieve high cohesion, low coupling, and offline-first resilience:

┌───────────────────────────────────────────────────────────────────────────┐
│                           SwiftUI View Layer                              │
│   (LibraryView, ReaderView, MangaReaderView, ExploreView, ShelfView)      │
└─────────────────────────────────────┬─────────────────────────────────────┘
                                      │ User Gestures & Property Bindings
                                      ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                    @MainActor Central ViewModel Tier                      │
│                    (StoryStore.swift / AuthManager.swift)                 │
└──────────────────┬─────────────────────────────────────┬──────────────────┘
                   │ Reactive @Published Mutations       │ Asynchronous I/O
                   ▼                                     ▼
┌──────────────────────────────────────┐ ┌──────────────────────────────────┐
│        Local Persistence Layer       │ │      Service Abstraction         │
│   (SwiftData / PersistenceService)   │ │    (StoryAPIServiceProtocol)     │
│   - In-memory cache fallback         │ │   - StoryAPIService Client       │
│   - Pure zero-baseline analytics     │ │   - KeychainStore (Auth Tokens)  │
│   - Pinned annotations & journal     │ │   - AudioNarratorController      │
└──────────────────────────────────────┘ └──────────────────┬───────────────┘
                                                            │ REST JSON Calls
                                                            ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                      FastAPI Backend Engine (v1)                          │
│   - /api/v1/auth       (Registration, login, profile, logout, stats)     │
│   - /api/v1/auth/me/stats (Account reading totals and active streak)     │
│   - /api/v1/stories    (Multi-format catalog, prose & manga chapters)     │
│   - /api/v1/genres     (Live taxonomy & reader metrics)                   │
│   - /api/v1/authors/top(Verified top creators & avatar URLs)              │
│   - /api/v1/updates    (Live chapter updates & editorial highlights)      │
│   - /api/v1/shelf      (Bearer-protected account shelf read and sync)    │
│   - /api/v1/auth/me/reading-sessions (Idempotent reading events)          │
│   - /api/v1/health     (System diagnostics & DB status)                   │
└─────────────────────────────────────┬─────────────────────────────────────┘
                                      │ Relational Queries
                                      ▼
┌───────────────────────────────────────────────────────────────────────────┐
│                       SQLite Storage Tier                                 │
│ (stories, chapters, account_shelf_items, reading_sessions, user_sessions) │
└───────────────────────────────────────────────────────────────────────────┘

Architectural Principles

  1. Contract-First API Design: Python schemas define camelCase Pydantic serialization aliases that match Swift Codable contracts; backend tests cover the serialized response shapes.
  2. Offline-First Resilience: When the backend is unreachable, the client uses previously cached SwiftData stories, chapters, discovery metadata, images, shelf state, and queued reading sessions. The disk image cache evicts its oldest files above 256 MiB. A fresh install has no bundled story catalog.
  3. Decoupled Service Boundary: SwiftUI views never execute raw network requests. All data fetching, caching, and mutations flow through protocol-abstracted services.

3. How to Set Up and Run

Prerequisites

  • macOS: macOS Sonoma (14.0+) or Sequoia (15.0+)
  • Xcode: Xcode 15.4 or Xcode 16.0+
  • Python: Python 3.9 or higher
  • Git: Git 2.39+

Step A: Setting Up & Starting the Backend API

  1. Navigate to the Repository Root:

    cd Fable-IOS
  2. Create and Activate a Python Virtual Environment:

    python3 -m venv .venv
    source .venv/bin/activate
  3. Install Dependencies:

    pip install --upgrade pip
    pip install -r backend/requirements-test.txt
  4. Execute Backend Verification Tests (100 Automated Tests):

    FABLE_ENV=test ./.venv/bin/pytest backend/test_main.py -v

    (All 100 tests must pass, verifying health checks, serialization contracts, Chapter 1 continuity, rate limits, auth hashing, and shelf sync logic).

  5. Start the FastAPI Development Server (Single-Command Wireless Mode for Mac & Fedora Linux):

    ./scripts/start_wireless_server.sh

    (This one command starts Uvicorn on 0.0.0.0:8001 in development mode, prints your Home Wi-Fi / Hotspot URL http://<LAN_IP>:8001/api/v1, and opens a live HTTPS Cloudflare tunnel https://<id>.trycloudflare.com/api/v1 for campus/mobile networks. Use ./scripts/start_wireless_server.sh --no-tunnel for LAN/Simulator-only runs.)

    • Local API Base URL: http://127.0.0.1:8001/api/v1
    • Interactive Swagger UI: Open your browser and navigate to http://127.0.0.1:8001/docs
    • Health Check: curl http://127.0.0.1:8001/api/v1/health

Step B: Setting Up & Running the iOS Client (SwiftUI)

  1. Open the Project in Xcode:

    open frontend/FableApp.xcodeproj

    (Or launch Xcode ➔ File ➔ Open... ➔ Select frontend/FableApp.xcodeproj).

  2. Select Target Scheme & Run Destination:

    • In the top Xcode toolbar, confirm the active scheme is set to FableApp.
    • Select an iOS Simulator running iOS 17.0+ (e.g., iPhone 16 Pro or iPhone 15 Pro).
  3. Configure the API URL:

    • The FABLE_API_BASE_URL Xcode build setting is exposed through frontend/FableApp-Info.plist. It defaults to http://127.0.0.1:8001/api/v1, matching the local Uvicorn and Docker Compose host port.
    • In-App Backend Server URL Switcher (No Rebuild Needed): Both WelcomeView ("Server: … • Change") and SettingsView ("Backend Server URL") let you change the active backend URL at runtime (StoryAPIService.setCustomBaseURL), automatically appending /api/v1 if omitted, or switch with one tap to Render Cloud (https://fable-api-cbo8.onrender.com/api/v1).
    • Physical iPhone on Home Wi-Fi / Personal Hotspot (Mac or Fedora Linux): Bind FastAPI to 0.0.0.0 (uvicorn main:app --reload --host 0.0.0.0 --port 8001) and enter your computer's LAN address (e.g., http://192.168.1.20:8001/api/v1) in the in-app Backend Server URL switcher.
    • Physical iPhone on Campus / Isolated Wi-Fi (Wireless Local Backend): When campus Wi-Fi AP Client Isolation blocks peer-to-peer LAN traffic, expose your local FastAPI server over an instant SSH HTTPS tunnel (ssh -T -R 80:127.0.0.1:8001 nokey@localhost.run) and enter the generated https://<id>.app.lhr.life/api/v1 URL in the in-app Backend Server URL switcher—or tap Use Render Cloud.
    • ATS (NSAppTransportSecurity in frontend/FableApp-Info.plist) allows local networking for development while keeping arbitrary HTTP loads disabled. StoryAPIService.iso8601DateDecodingStrategy supports both fractional-microsecond ISO-8601 timestamps from FastAPI and standard ISO-8601 timestamps.
  4. Build & Launch:

    • Press Cmd + R (or click the Play button).
    • With the backend reachable, Fable discovers provider catalog entries and user-published stories. When offline, it uses previously cached provider metadata, images, chapters, and account-specific drafts; a fresh install has no bundled story catalog.

Deployment and Operations

4. Project Directory Topology

Fable-IOS/
├── README.md                               # Repository guide & setup documentation (this file)
├── Package.swift                           # Swift Package Manager manifest
├── scripts/
│   └── sqlite_backup.py                    # Encrypted SQLite backup/restore utility
├── backend/                                # Asynchronous Python 3.9+ / FastAPI Backend
│   ├── main.py                             # Application entrypoint & middleware configuration
│   ├── requirements.txt                    # Runtime dependencies (FastAPI, Uvicorn, Pydantic, HTTPX)
│   ├── requirements-test.txt               # Runtime plus pytest for local and CI verification
│   ├── test_main.py                        # Pytest runner entrypoint (executes 100-test suite)
│   ├── tests/
│   │   └── test_api_v1.py                  # Comprehensive 100-case API, auth, backup, and catalog test suite
│   ├── api/v1/
│   │   ├── api.py                          # Unified API router mounting
│   │   └── endpoints/                      # Route controllers (auth, stories, shelf, gutenberg, health)
│   ├── core/
│   │   ├── config.py                       # Environment & security settings
│   │   ├── database.py                     # SQLite connection, schema bootstrap & curated catalog upsert
│   │   ├── operator_auth.py                # Operator key guard for ingestion routes
│   │   └── rate_limit.py                   # Sliding-window and SQLite token-bucket rate limiters
│   ├── models/                             # Pydantic v2 DTOs with camelCase serialization aliases
│   └── services/                           # Business logic (auth_service, story_service, shelf_service, gutenberg)
├── frontend/                               # Native iOS Application (22 XCTests)
│   ├── FableApp.xcodeproj/                 # Xcode 16 project file
│   └── FableApp/
│       ├── App/                            # Lifecycle bootstrap (FableApp.swift, ContentView.swift)
│       ├── Core/                           # Foundation tokens, FableTheme, FableImageView, KeychainStore
│       ├── Features/                       # Domain-Driven Vertical Slices
│       │   ├── Auth/                       # Welcome, SignIn, SignUp, AuthManager, AuthTests
│       │   ├── Library/                    # LibraryView, ExploreView, GenreDetail, StoryStore, APIService, AppHealthTests
│       │   ├── Reader/                     # ReaderView, MangaReaderView (dormant), DisplayOptionsSheet, VoiceSelectionSheet
│       │   ├── Shelf/                      # ShelfView, ProfileView, SettingsView, SystemDiagnosticsSheet, ShelfTests
│       │   └── Write/                      # WriteView, StoryComposer, StoryPublishedSheet, WriteTests
│       └── Assets.xcassets/                # App icon and accent color
├── docs/                                   # Architectural specifications & engineering documentation
│   ├── AGENT_HANDOFF_CONTEXT.md            # Complete session handoff context for laptop agents
│   ├── adr/                                # Architecture Decision Records (ADR 0001, 0002, 0003)
│   ├── plans/                              # Feature & Security Remediation Plans (Plans 01 through 06)
│   ├── simulator_captures/                 # 29 Retina UI screenshots + full walkthrough MP4 video
│   ├── final_milestone/                    # Capstone specs & MASTER_PROGRESS_LOG.md
│   ├── FINAL_MILESTONE_PROGRESS.md         # Comprehensive milestone progression audit
│   ├── DATA_SOURCES_AND_API_STRATEGY.md    # Catalog seeding architecture & upstream manga gap analysis
│   ├── ARCHITECTURE.md                     # System architecture & vertical slice design
│   ├── SYSTEM_DESIGN.md                    # Critical system design & 5 pillars specification
│   ├── OPERATIONS.md                       # Encrypted backup, verification, and restore runbook
│   ├── OCI_DEPLOYMENT.md                   # Oracle Cloud production deployment guide
│   └── MAC_LAB_RUNBOOK.md                  # Step-by-step computer lab verification runbook
└── prototype_reference/                    # High-resolution screenshots of all 10 prototype screens

5. Lab Troubleshooting & Consistency Guarantees

Issue Encountered Root Cause Resolution
Xcode defaults to "My Mac" destination Xcode auto-selected Mac Catalyst or macOS destination Click the target dropdown at the top of Xcode ➔ Choose iOS Simulators ➔ iPhone 16 Pro.
Simulator fails to connect to 127.0.0.1:8001 The API container is stopped or the app URL uses a different host port Start it with docker compose up -d --build and verify curl http://127.0.0.1:8001/api/v1/health. Keep the Xcode Debug URL on port 8001.
Old cached build artifacts fail Previous user left stale build cache Press Shift + Cmd + K (Product ➔ Clean Build Folder), then press Cmd + B to rebuild.
Offline Lab Network (No Internet) Campus Wi-Fi blocked or offline computer Fable reads previously cached stories, chapters, images, and per-account shelf data. A first launch without network has no catalog to display.
Physical iPhone "Untrusted Developer" / "Internet connection required" Free Apple ID Personal Team certificate requires one-time verification with ppq.apple.com On the iPhone, temporarily enable Mobile Data (if campus Wi-Fi blocks Apple verification), go to Settings ➔ General ➔ VPN & Device Management, tap your Developer App profile, and tap Trust.
Physical iPhone cannot reach Mac's local IP (172.x.x.x:8001) on campus Wi-Fi Campus Wi-Fi AP Client Isolation blocks peer-to-peer traffic between wireless clients Run ssh -T -R 80:127.0.0.1:8001 nokey@localhost.run on the Mac and pass FABLE_API_BASE_URL="https://<id>.app.lhr.life/api/v1" (or use the deployed Render URL https://fable-api-cbo8.onrender.com/api/v1).

6. Official Submission References

About

A native iOS reader for literature, folklore, and manga

Topics

Resources

Stars

12 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages