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).
| 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 |
- 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
MangaReaderViewwith 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, regionalAVSpeechSynthesisVoiceaudition sheet) - Security & Credential Vault: Apple
Securityframework (KeychainStorefor encrypted token and session storage) - Diagnostics Suite: Built-in
AppHealthTestsand on-deviceSystemDiagnosticsSheetverifying layout clipping and live ingestion contracts. - Networking & HTTP: Native
URLSessionwith ATS enabled; development API base URL is configurable
- 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.
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) │
└───────────────────────────────────────────────────────────────────────────┘
- Contract-First API Design: Python schemas define camelCase Pydantic serialization aliases that match Swift
Codablecontracts; backend tests cover the serialized response shapes. - 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.
- Decoupled Service Boundary: SwiftUI views never execute raw network requests. All data fetching, caching, and mutations flow through protocol-abstracted services.
- 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+
-
Navigate to the Repository Root:
cd Fable-IOS -
Create and Activate a Python Virtual Environment:
python3 -m venv .venv source .venv/bin/activate -
Install Dependencies:
pip install --upgrade pip pip install -r backend/requirements-test.txt
-
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).
-
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:8001indevelopmentmode, prints your Home Wi-Fi / Hotspot URLhttp://<LAN_IP>:8001/api/v1, and opens a live HTTPS Cloudflare tunnelhttps://<id>.trycloudflare.com/api/v1for campus/mobile networks. Use./scripts/start_wireless_server.sh --no-tunnelfor 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
- Local API Base URL:
-
Open the Project in Xcode:
open frontend/FableApp.xcodeproj
(Or launch Xcode ➔ File ➔ Open... ➔ Select
frontend/FableApp.xcodeproj). -
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).
-
Configure the API URL:
- The
FABLE_API_BASE_URLXcode build setting is exposed throughfrontend/FableApp-Info.plist. It defaults tohttp://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") andSettingsView("Backend Server URL") let you change the active backend URL at runtime (StoryAPIService.setCustomBaseURL), automatically appending/api/v1if 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 generatedhttps://<id>.app.lhr.life/api/v1URL in the in-app Backend Server URL switcher—or tap Use Render Cloud. - ATS (
NSAppTransportSecurityinfrontend/FableApp-Info.plist) allows local networking for development while keeping arbitrary HTTP loads disabled.StoryAPIService.iso8601DateDecodingStrategysupports both fractional-microsecond ISO-8601 timestamps from FastAPI and standard ISO-8601 timestamps.
- The
-
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.
- Press
- Backend operations, backups, and restore procedures
- OCI production deployment, HTTPS, Object Storage backups, and monitoring
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
| 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). |
- Figma Interactive Prototype: https://www.figma.com/proto/fable-ios-prototype-midterm
- GitHub Repository URL: Fable-IOS
- Author / Developer: Roosc Zaño (ITWM101 | M090)