Architecture

Architecture

Current implementation

Granthalay is currently a fully client-side SvelteKit application:

flowchart LR
  EPUB[EPUB file] --> Engine[EpubEngine]
  Engine --> Safe[Sanitized chapters]
  Engine --> Assets[Blob asset URLs]
  EPUB --> DB[(IndexedDB)]
  Safe --> Reader[Reader and pagination]
  Reader --> DB
  Worker[Service worker] --> Cache[(Cache Storage)]

Loading

• src/lib/epub/engine.ts owns ZIP, OPF, navigation, CSS, resources, and sanitization.
• src/lib/db.ts owns native IndexedDB access.
• Versioned annotation records use chapter hrefs, normalized progressions, and text-quote selectors so bookmarks and highlights do not depend on rendered page numbers.
• Library, details, and reader routes own their corresponding UI workflows.
• src/service-worker.ts owns application caching and navigation fallback.

Planned evolution

One repository will produce two independently deployed artifacts:

flowchart LR
  PWA[Static PWA on GitHub Pages] -->|HTTPS API| API[Modular backend]
  PWA --> Local[(IndexedDB)]
  API --> DB[(Database)]
  API --> Books[(Book object storage)]
  API --> Providers[Payment and email providers]

Loading

The PWA owns Reader and local Library behavior. The backend owns Accounts, Catalog, Content, Commerce, Entitlements, Notification, Publisher, Administration, and Audit modules.

The backend starts as one deployable and database. Modules own their data and expose explicit internal APIs; providers stay behind adapters. The PWA uses a versioned HTTPS API with an explicit GitHub Pages CORS origin. Accounts use email/password authentication, short-lived JWT access tokens, and revocable refresh sessions. Purchased files require an entitlement check and are never bundled into the static site.

Zod validates shared runtime contracts. Pino provides redacted structured backend logs. Sentry is an optional diagnostics adapter, disabled unless configured and supplied only scrubbed errors. Installing these packages does not enable logging or telemetry by itself.

Anonymous local importing and reading remain permanent capabilities. The server transition is future work represented by milestones v0.4.0 through v1.0.0.