Architecture
Inkshelf is one Go module. Everything but the two programs in cmd lives under
internal, in folders named after a domain: what you need to know to work there.
This page is the map. Each package's own documentation (go doc ./internal/..., or its
doc.go) explains its domain in more depth. New to all this? The learning
chapters of this site (docs/learn, make docs) explain the same domains from scratch, with
interactive animations.
The domains, bottom to top
| Domain | Packages | What it knows |
|---|---|---|
| device | device/pocketbook | The PocketBook reader without its SDK: framebuffer, e-ink refreshes, firmware messages, input, the event loop, Wi-Fi, and an emulated reader for the host. |
| graphics | graphics/fonts, graphics/pageimage | Pixels: TrueType fonts, shaping and drawing text in gray; page images decoded, fitted, toned, dithered to 16 grays and packed into .pg4 files. |
| web | web/css, web/svgimage, web/mathml, web/webfont, web/webimage, web/uri | The web formats books are written in: the CSS cascade, SVG, MathML, WOFF fonts, a book's images, relative links and data: URIs. |
| typesetting | typesetting/document, typesetting/layout, typesetting/hyphen | Text on pages: the document model (blocks of styled runs), line breaking, bidi, justification, floats, tables, pagination, hyphenation. |
| ebook | ebook/epub/container, ebook/epub, ebook/fixedlayout, ebook/comicarchive | Book files: an EPUB's zip, package and navigation; its XHTML and CSS turned into documents; fixed-layout pages; the pages of a CBZ. |
| (utility) | naturalorder | "Tome 2" before "Tome 10". Imports nothing; used by ebook, servers and shelf. |
| (utility) | timing | Spans for the log and the execution trace, and profile captures. Imports nothing of Inkshelf's; any domain may use it. See profiling.md. |
| servers | servers, servers/komga, servers/mealie, servers/calibreweb, servers/httpclient, servers/registry, their fakes, servers/servertest | What the app needs from a server of books (the Server interface and its neutral model), and one package per kind of server. See servers.md. |
| shelf | shelf | The books downloaded on the reader: downloading them, preparing them for the panel, book.json, covers. See on-disk-formats.md. |
| progress | progress | Keeping the reading progress of the reader and the server in agreement. See progress-sync.md. |
| reading | reading | The engine behind reading an EPUB whose text flows: positions, page turns across chapters, links and notes, the table of contents. |
| app | app and below | The user interface: state, widgets, services, screens. See app-threading.md. |
| cmd | cmd/inkshelf, cmd/emulator | The program for the reader, and the emulator for the host. See emulator.md. |
The layering rule
A package imports only from its own domain or from domains below it in the table. Two more rules keep the app independent of any one server:
appandshelf(and everything they import) never import a specific server (servers/komga,servers/mealie,servers/calibreweb). They talk toservers.Server. Only the programs incmdimportservers/registry, which knows every kind.- The reader side (device, graphics, web, typesetting, ebook) knows nothing of servers.
Check the first rule with:
go list -deps ./internal/app/... ./internal/shelf | grep -E 'servers/(komga|mealie|calibreweb)'
It must print nothing.
The imports between domains, from go list -f '{{.ImportPath}}: {{join .Imports " "}}' ./...:
timing is left out of the graph to keep it readable: device, graphics, ebook, servers, shelf,
reading, app and cmd use it, to time their work for the log and the trace.
Where do I look for…
| Question | Where |
|---|---|
| What happens on a page turn | app/openbook TurnPage, then the reader screen's DrawAndRefreshLocked in app/screens/reader; sequence in app-threading.md |
| A panel refresh, waveforms, ghosting | device/pocketbook (Refresh, FlashRefresh, eink_refresh.go); eink-and-firmware.md |
| Talking to the firmware, input, the event loop | device/pocketbook; eink-and-firmware.md |
| A download | app/downloadqueue (the queue), shelf Store.Download (the work); image-pipeline.md |
| How a page image is prepared | graphics/pageimage; image-pipeline.md |
| A CSS property in a book | ebook/epub (computeStyle and the builder), web/css (parsing, cascade); epub-to-page.md |
| What a chapter becomes | typesetting/document; document-model.md |
| Line breaking, justification, pagination | typesetting/layout; pagination.md |
| Fonts, fallbacks, Arabic shaping | graphics/fonts |
| How much of EPUB 3.3 works | epub-conformance.md |
| A server's API | servers/komga, servers/mealie, servers/calibreweb; servers.md |
| Adding a kind of server | servers.md, the checklist at the end |
| Progress sync | progress, the calls in app/openbook and app/catalog; progress-sync.md |
| A screen | app/screens: one package per screen; app/screens.go for the Screen interface |
| Locks, goroutines, repaints | app/state; app-threading.md |
| Files on the reader | shelf, app/session, cmd/inkshelf; on-disk-formats.md |
| The emulator, scripts and screenshots | cmd/emulator, emulator/scripts; emulator.md |