System view

How Ranobe Gemini Works

A modular browser-extension architecture: content scripts for in-page UX, background orchestration for AI/backup flows, and storage-first state.

Runtime

Reader-to-Result Flow

flowchart TB A[Open supported chapter] --> B[Content script detects handler] B --> C[Inject Enhance and Summarize controls] C --> D{API key configured?} D -->|No| E[Show setup prompt] D -->|Yes| F[Send request to background] F --> G[Chunking and model pipeline] G --> H[Render enhanced text] H --> I[Optional summary and content boxes]

Open chapter -> Detect handler -> Inject controls -> Check API key -> Process with background pipeline -> Render enhanced content + summary boxes

A: User starts from any supported site chapter page.
B: Site-specific handler is selected dynamically.
G: Large chapters are chunked to avoid model timeout risk.
I: Collapsible sections and style boxes are applied after model output.

Modular Design

Extension Component Map

flowchart TB UI[Popup and Library UI] --> STATE[Storage and Settings] SITES[Website Handlers] --> CONTENT[Content Script Runtime] CONTENT --> BG[Background Orchestrator] BG --> AI[AI Provider Registry] AI --> GEM[Gemini] AI --> OAI[OpenAI-compatible] AI --> OLL[Ollama local] BG --> DRIVE[Storage Orchestrator] DRIVE --> DEST[Drive / OneDrive / Dropbox / WebDAV / Native sync] STATE --> BG STATE --> CONTENT

UI modules -> Shared settings/storage -> Background orchestrator -> AI provider registry (Gemini, OpenAI-compatible, Ollama) + storage orchestrator (Drive, OneDrive, Dropbox, WebDAV, native sync), with content scripts and website handlers as isolated modules

Website Handlers: One module per website keeps extraction logic isolated.
Background Orchestrator: Centralizes API calls, alarms, and backup sync.
Storage and Settings: Shared contract for popup, library, and content layers.
AI Provider Registry: One adapter per provider behind a shared interface, so switching from Gemini to a local Ollama model changes a setting, not a code path.
Storage Orchestrator: Optional module selecting the sync destination you configured; with it off you still have the full local workflow.

Reliability

Backup and Sync Decision Flow

flowchart TB A1[Library data changed] --> B1{Backup mode} B1 -->|Scheduled| C1[Run alarm-based backup] B1 -->|Both| E1[Continuous plus scheduled] B1 -->|Continuous| D1[Debounced upload] C1 --> F1[Versioned backup file] D1 --> G1[Rolling continuous backup file] E1 --> F1 E1 --> G1 F1 --> H1{Drive connected?} G1 --> H1 H1 -->|No| I1[Keep local backup history] H1 -->|Yes| J1[Upload to user Drive]

Library change -> Mode decision (scheduled/continuous/both) -> Create backup artifact -> If Drive connected upload, else keep local history

Both mode: Combines periodic safety points with near-real-time rolling backup.
Drive connected? Backup always remains local-first; cloud sync is optional.
User ownership: Backup files remain in the user's own Google Drive account.

Inter-Process Communication

Message Flow Between Contexts

sequenceDiagram participant CS as Content Script participant BG as Background participant ST as Storage CS->>BG: addToLibrary action BG->>ST: Read library data ST-->>BG: Current novels BG->>BG: Merge novel metadata BG->>ST: Save updated library ST-->>BG: Success BG-->>CS: {success: true} CS->>CS: Show notification

Content -> Background: addToLibrary -> Storage: read -> Background: merge -> Storage: save -> Background: confirm -> Content: notify user

Async Messaging: All cross-context communication uses browser.tabs.sendMessage with timeouts.
Storage Contract: Background owns library state; content reads are query-only.
Error Recovery: Failed messages trigger UI notifications and retry logic.

Data Model

Library Storage Schema Overview

📚 Novel Entry

Stores shelf ID, site novel ID, title, author, status, reading lists, metadata (characters, relationships, tags), chapter count, and URLs.

⚙️ Settings Object

API key, model selection, reading lists definitions, collapsible section types, backup mode, Drive credentials, and UI layout preferences.

📋 Backup History

Versioned and continuous backup metadata including filename, creation timestamp, Drive file ID, upload status, and reconciliation markers.

🔧 Handler Cache

Per-handler site-specific metadata, extraction patterns, URL templates, and favicon/icon fallback URLs for robust display.

Running State Example

Key	Type	Purpose
`novels`	Object<novelId, Novel>	Central library indexed by generated novel IDs
`readingLists`	Array<{id, label}>	User-defined list definitions (rereading, favourites, custom)
`settings`	Object	User preferences and API/backup configuration
`backupHistory`	Array<BackupEntry>	Last 50 backup records with Drive sync status

Site Integration

Handler Registration and Discovery

flowchart LR HR["Handler Files
(*.handler.js)"] --> BR["Build Process
(build.js)"] BR --> HRG["Handler Registry
(generated)"] BR --> MAN["Manifest Domains
(updated)"] HRG --> CSS["Content Script
Loads Registry"] CSS --> DET["Runtime Detection
on Page Open"] MAN --> EXT["Extension Manifest
content_scripts"] EXT --> INJ["Inject Controls
on Matching Domains"]

Handler files -> build.js processes -> registry generated + manifest updated -> content script loads registry -> runtime detection on page -> inject controls on matching domains

Auto-Registration: Adding a new file `*-handler.js` automatically registers it via build process.
Dynamic Detection: Content script detects handler at runtime based on domain match patterns.
Manifest Coupling: Handler domains automatically sync to manifest `content_scripts` matches.

State Machine

Novel Reading Status Lifecycle

stateDiagram-v2 [*] --> PlanToRead: Add to library PlanToRead --> Reading: Start reading Reading --> OnHold: Pause temporarily Reading --> Completed: Finish series OnHold --> Reading: Resume OnHold --> Abandoned: Give up Abandoned --> [*] Completed --> [*] Reading --> Rereading: Toggle rereading list Rereading --> Reading: End reread note right of Rereading Rereading is a list-based tag overlay, not a primary status end note

PlanToRead -> Reading -> OnHold/Completed, Reading <-> Rereading (list toggle)

Primary Status: Novel has one primary reading status at any time.
Reading Lists: Independent list membership (rereading, favourites, custom) can be toggled via dropdown.
Soft Transitions: Reading state can move between any status without validation.

URL Import Pipeline

Adaptive Batch Import with Deduplication

flowchart TB A["Paste URLs
(raw list)"] --> B["Filter Supported
(by domain)"] B --> C["Extract Novel IDs
(per handler pattern)"] C --> D["Check Library
(existing novels)"] D --> E["Dedupe Batch
(same paste)"] E --> F{Queue
Ready} F -->|No matches| G["Report: Skipped all"] F -->|Has URLs| H["Build Canonical
(handler templates)"] H --> I["Open Background
Tabs"] I --> J["Send Add Messages
(explicit flow)"] J --> K["Close Tabs
(cleanup)"] K --> L["Report Results
(added/skipped/failed)"]

Paste URLs -> Filter domains -> Extract IDs -> Check existing -> Dedupe batch -> Build canonical -> Open tabs -> Send add messages -> Close tabs -> Report

Handler-Driven: Each handler provides canonical URL template and extraction pattern.
Existing Skip: Library is queried first; already-added novels are skipped silently.
Batch Dedupe: Duplicates in the same paste are removed before processing.
Explicit Flow: Import uses explicit addToLibrary messages, not passive tab opens.

Ready to Install

Install once, then verify every module yourself

Use published Firefox and Edge builds, or temporary install on Chromium browsers. Then open Library and inspect handlers, filters, and backups in action.

Get for Firefox Get for Edge Install on Other Browsers