# ultimatejimmy/storefront.koplugin architecture

> Architecture diagram of the GitHub repository ultimatejimmy/storefront.koplugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ultimatejimmy/storefront.koplugin
- Repository: https://github.com/ultimatejimmy/storefront.koplugin

## Overview

Storefront is a KOReader plugin for browsing and managing community plugins, patches, fonts, and screensavers. The user workflow runs from the in-device browser through catalog and detail views to installation, with caching and update tracking supporting ongoing use. Separate branches cover screensaver customization, shared blueprints, and ratings. The README documents the major user capabilities; sampled backend excerpts support the blueprint and ratings service links, while many plugin modules were not sampled, so uncertain internal call wiring is omitted.

Main entry points: [`storefront.koplugin/main.lua`](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/main.lua) (Plugin entry), [`storefront.koplugin/storefront_browser_ui.lua`](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_browser_ui.lua) (Unified browser), [`storefront.koplugin/storefront_installer.lua`](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_installer.lua) (Installer), [`storefront.koplugin/storefront_screensavers_ui.lua`](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_screensavers_ui.lua) (Screensaver browser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Device experience"]
  node_plugin["Plugin entry<br/>[main.lua]"]
  node_browser["Unified browser"]
  node_details["Item details"]
  node_filters["Filters and search"]
  node_localization["Localization"]
end

subgraph group_manage["Content management"]
  node_installer["Installer"]
  node_fontmanager["Font manager"]
  node_patchmanager["Patch manager"]
  node_updates["Update tracking"]
  node_screensavers["Screensaver browser"]
  node_screensaverconfig["Screensaver settings"]
end

subgraph group_services["Sharing and ratings"]
  node_blueprintui["Blueprint sharing"]
  node_blueprintcloud["Blueprint client"]
  node_blueprintworker["Blueprint service"]
  node_ratings["Ratings client"]
  node_voteworker["Vote service"]
  node_d1[("Cloudflare D1")]
end

subgraph group_data["Catalog and state"]
  node_catalog["Catalog data<br/>[catalog.json]"]
  node_network["Catalog and GitHub"]
  node_cache["Offline cache"]
end

node_reader(("KOReader user"))
node_github["GitHub"]
node_devicefiles[("KOReader files")]

node_reader -->|"opens"| node_plugin
node_plugin -->|"shows"| node_browser
node_browser -->|"reads"| node_catalog
node_browser -->|"fetches"| node_network
node_network -->|"requests"| node_github
node_browser -->|"reads and writes"| node_cache
node_browser -->|"filters"| node_filters
node_browser -->|"opens"| node_details
node_details -->|"fetches README"| node_github
node_details -->|"installs"| node_installer
node_installer -->|"writes files"| node_devicefiles
node_installer -->|"installs fonts"| node_fontmanager
node_installer -->|"installs patches"| node_patchmanager
node_updates -->|"checks versions"| node_github
node_updates -->|"reads installed items"| node_devicefiles
node_plugin -->|"opens"| node_screensavers
node_screensavers -->|"customizes"| node_screensaverconfig
node_screensavers -->|"downloads"| node_github
node_screensavers -->|"saves images"| node_devicefiles
node_plugin -->|"opens"| node_blueprintui
node_blueprintui -->|"shares"| node_blueprintcloud
node_blueprintcloud -->|"requests"| node_blueprintworker
node_blueprintworker -->|"reads and writes"| node_d1
node_plugin -->|"shows ratings"| node_ratings
node_ratings -.->|"submits votes"| node_voteworker
node_voteworker -->|"stores votes"| node_d1
node_plugin -->|"loads strings"| node_localization

click node_plugin "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/main.lua"
click node_browser "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_browser_ui.lua"
click node_details "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_details_dialog.lua"
click node_filters "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_filter_dialog.lua"
click node_localization "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/localization_storefront.lua"
click node_catalog "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/catalog.json"
click node_network "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_net_catalog.lua"
click node_cache "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_cache.lua"
click node_installer "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_installer.lua"
click node_fontmanager "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_font_mgr.lua"
click node_patchmanager "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_patch_mgr.lua"
click node_updates "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_updates_mgr.lua"
click node_screensavers "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_screensavers_ui.lua"
click node_screensaverconfig "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_screensaver_config.lua"
click node_blueprintui "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_blueprint_ui.lua"
click node_blueprintcloud "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_blueprint_cloud.lua"
click node_blueprintworker "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/tools/blueprint-worker.js"
click node_ratings "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_ratings.lua"
click node_voteworker "https://github.com/ultimatejimmy/storefront.koplugin/blob/main/tools/vote-proxy-worker.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_browser,node_details,node_filters,node_localization,node_reader toneBlue
class node_installer,node_fontmanager,node_patchmanager,node_updates,node_screensavers,node_screensaverconfig,node_devicefiles toneAmber
class node_blueprintui,node_blueprintcloud,node_blueprintworker,node_ratings,node_voteworker,node_d1 toneMint
class node_catalog,node_network,node_cache toneRose
class node_github toneIndigo
```

## Components

### Device experience

- [Plugin entry](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/main.lua): `storefront.koplugin/main.lua`
- [Unified browser](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_browser_ui.lua): `storefront.koplugin/storefront_browser_ui.lua`
- [Item details](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_details_dialog.lua): `storefront.koplugin/storefront_details_dialog.lua`
- [Filters and search](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_filter_dialog.lua): `storefront.koplugin/storefront_filter_dialog.lua`
- [Localization](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/localization_storefront.lua): `storefront.koplugin/localization_storefront.lua`

### Content management

- [Installer](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_installer.lua): `storefront.koplugin/storefront_installer.lua`
- [Font manager](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_font_mgr.lua): `storefront.koplugin/storefront_font_mgr.lua`
- [Patch manager](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_patch_mgr.lua): `storefront.koplugin/storefront_patch_mgr.lua`
- [Update tracking](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_updates_mgr.lua): `storefront.koplugin/storefront_updates_mgr.lua`
- [Screensaver browser](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_screensavers_ui.lua): `storefront.koplugin/storefront_screensavers_ui.lua`
- [Screensaver settings](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_screensaver_config.lua): `storefront.koplugin/storefront_screensaver_config.lua`

### Sharing and ratings

- [Blueprint sharing](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_blueprint_ui.lua): `storefront.koplugin/storefront_blueprint_ui.lua`
- [Blueprint client](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_blueprint_cloud.lua): `storefront.koplugin/storefront_blueprint_cloud.lua`
- [Blueprint service](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/tools/blueprint-worker.js): `tools/blueprint-worker.js`
- [Ratings client](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_ratings.lua): `storefront.koplugin/storefront_ratings.lua`
- [Vote service](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/tools/vote-proxy-worker.js): `tools/vote-proxy-worker.js`
- **Cloudflare D1**

### Catalog and state

- [Catalog data](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/catalog.json): `storefront.koplugin/catalog.json`
- [Catalog and GitHub](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_net_catalog.lua): `storefront.koplugin/storefront_net_catalog.lua`
- [Offline cache](https://github.com/ultimatejimmy/storefront.koplugin/blob/main/storefront.koplugin/storefront_cache.lua): `storefront.koplugin/storefront_cache.lua`

### Other components

- **KOReader user**
- **GitHub**
- **KOReader files**

## Connections

- KOReader user → Plugin entry: opens
- Plugin entry → Unified browser: shows
- Unified browser → Catalog data: reads
- Unified browser → Catalog and GitHub: fetches
- Catalog and GitHub → GitHub: requests
- Unified browser → Offline cache: reads and writes
- Unified browser → Filters and search: filters
- Unified browser → Item details: opens
- Item details → GitHub: fetches README
- Item details → Installer: installs
- Installer → KOReader files: writes files
- Installer → Font manager: installs fonts
- Installer → Patch manager: installs patches
- Update tracking → GitHub: checks versions
- Update tracking → KOReader files: reads installed items
- Plugin entry → Screensaver browser: opens
- Screensaver browser → Screensaver settings: customizes
- Screensaver browser → GitHub: downloads
- Screensaver browser → KOReader files: saves images
- Plugin entry → Blueprint sharing: opens
- Blueprint sharing → Blueprint client: shares
- Blueprint client → Blueprint service: requests
- Blueprint service → Cloudflare D1: reads and writes
- Plugin entry → Ratings client: shows ratings
- Ratings client → Vote service: submits votes
- Vote service → Cloudflare D1: stores votes
- Plugin entry → Localization: loads strings