Skip to content

Latest commit

 

History

History
116 lines (82 loc) · 4.89 KB

Codetour.md

File metadata and controls

116 lines (82 loc) · 4.89 KB
Raw

Code tour

A quick introduction to the folders and files in this repo.

WebExtension anatomy

To comply with the anatomy of a WebExtension, this extension consists of the following parts (found in extension/ after compilation):

  • background.js always runs, in an 'empty invisible tab', listening for messages and events.
  • content_script.js is loaded into every web page that is visited. It is invisible from that web page's own scripts, and can talk to the background script.
  • overview/overview.html, with the resources in that folder, provides the main user interface.
  • options/options.html (plus resources) is a technically separate application that provides the settings page.

The parts communicate in two ways:

  • Messaging through browser.sendMessage, usually done implicitly by using a remote procedure call (util/webextensionRPC.js).
  • Through the in-browser PouchDB database, they get to see the same data, and can react to changes made by other parts.

Besides these parts, browser-polyfill.js provides the promise-based browser API, that simply wraps Chromium/Chrome's callback-based chrome API, in order to make the same code run in different browsers (and to structure the callback mess).

Source organisation

To keep things modular, the source code in src/ is not split in exactly those the three parts of the extension, but is rather grouped by functionality. Some folders may end up being factored out into separate repos later on, or at some point perhaps even into separate but interacting browser extensions.

src/activity-logger/: activity logger

This logs every page visit in PouchDB. Soon it should also watch for user interactions, for example to remember which parts of a page you have read.

Currently, for every visit, a new page object is created in the database, to represent the visited page itself. This object should soon be deduplicated when the same page is visited multiple times. After creating a new page object, the next module is triggered to start analysing the page.

src/page-analysis: (web)page analysis

This extracts and stores information about the page in a given tab, such as:

  • The plain text of the page, mainly for the full-text search index.
  • Metadata, such as its author, publication date, etcetera.
  • A screenshot for visual recognition.

src/page-storage: (web)page storage

Everything around managing the pages stored in the database. Mainly created for grouping the code around comparison and deduplication of stored versions of web pages, which did not really fit well under another folder.

src/page-viewer: display stored pages

Code for displaying the locally stored web pages, making them accessible on their own URL.

src/overview/: overview

The overview is the user interface that opens in a tab of its own. It is built with React and Redux, which create a somewhat complex but nicely organised application structure.

See src/overview/Readme.md for more details.

src/options/: settings panel

The page for modifying the settings is implemented as an individual React app. Currently it does not do much yet.

src/browser-history/: import browser history

Currently unused code for importing information from the browser's own history. Still to be developed and reorganised.

src/search: document search

Functions for finding relevant knowledge in the user's memory. Currently provides a simple full-text keyword search through visited pages using pouchdb-quick-search. This can be improved in many ways, because we are searching through a person's memory, not just some arbitrary document collection. For example, we can use created assocations and browsing paths to better understand what one is looking for.

src/dev/: development tools

Tools to help during development. They are not used in production builds.

src/util/: utilities

Contains small generic things, stuff that is not project-specific. Things that could perhaps be packaged and published as an NPM module some day.

...: other stuff

The build process is a Makefile, that runs some npm commands specified in package.json, which in turn start the corresponding tasks in gulpfile.babel.js (transpiled by settings in .babelrc). All lurking there so you only have to type make to get things running.

And a bunch of other development tool configurations, the usual cruft.

So much for the code tour. 💤 Any questions? ☝️