35 Architecture

Dimitri Witkowski edited this page 2021-03-13 20:01:50 +01:00

Table of Contents

• Repositories
• KeeWeb repository layout
• Application
• Frameworks
• Building
• Native modules

Repositories

• keeweb
  • the main repository containing the application code, desktop installers, and other support files
  • app.keeweb.info
• kdbxweb
  • core library used to read and write the KDBX file format
• keeweb-plugins
  • plugin repository for KeeWeb
  • contains plugins, themes, and translations
  • plugins.keeweb.info
• keeweb-site
  • our promotional website
  • keeweb.info
• favicon-proxy
  • CORS-enabled proxy used to load favicons from websites
  • favicon.keeweb.info
• keeweb-tools
  • tools for low-level working with kdbx files
  • tools.keeweb.info
• keeweb-native-modules
  • pre-built native modules used in KeeWeb
• ...forks of some repositories that can be found in keeweb organization

KeeWeb repository layout

Let's take a closer look at keeweb repository.
It consists of the following parts:

• app: application source code, both web and desktop
• build: build system tasks and the webpack config
• desktop: source code of the desktop part, entry point of the Electron app
• graphics: icons and images
• img: screenshots for the README on GitHub
• package: support files for packagers, docker images, and installers
• plugins: infrastructure for developing plugins and plugin examples
• test: tests
• util: utility scripts for performing different tasks on the repository
• grunt*.js: build system configuration files and task definitions

Application

Now let's dive deeper into the structure of the application code located in keeweb/app folder.

• icons: website favicons
• lib: 3rd-party code that doesn't exist in npm
• manifest: manifests for different browsers
  • browserconfig.xml: Microsoft Edge favicons definition
  • manifest.json: SPA manifest for other browsers
• resources: resources embedded in the application
  • Demo.kdbx: demo database
  • public-key.pem: public key used to verify plugin and update signatures
  • public-key-new.pem: rotated public key
• scripts: JS source code root
  • app.js: entry point
  • auto-type: auto-type engine used in desktop apps
  • collections: collection models with their methods, such as list of open files
  • comp: complex components with business logic using utilities, views, events, and so on
  • const: constant definitions
  • framework: micro-framework used in the app: models, collections, views, and events
  • hbs-helpers: helpers for Handlebars used in templates
  • locales: translations distributed with the app
  • models: models, such as file, entry, group, and so on
  • plugins: plugin engine
  • presenters: presentation-layer model extensions
  • storage: implementation of storage, such as Dropbox, Google Drive, WebDAV, and others
  • util: utility classes, they are similar co components, but they don't have dependencies and business logic
  • views: view controllers
• styles: SCSS styles root
  • main.scss: entry point
  • areas: styles divided by parts of the app, such as footer or header
  • base: common styles, such as global font stack
  • common: SCSS components used on different areas of the application
  • themes: theme definitions
  • utils: SCSS utilities and mixins
• templates: Handlebars templates root
• favicon.png: favicon for the website
• index.html: HTML page template where all scripts and styles are imported
• manifest.appcache: not used for caching anymore, contains only update information for desktop apps
• service-worker.js: service worker used for caching and update management

Frameworks

The app is built on our own micro-framework that is similar to Backbone. Originally it was on Backbone, but we were not using much of it and the number of limitations became more than problems solved. The current framework consists of these building blocks:

• events (the EventEmitter module from node.js)
• model
• collection
• view

Views are built on Handlebars.js and rendered with morphdom, which gives us a possibility to re-render them without losing input state. New code should be written in reactive style, however there are some direct DOM modifications in different places, ideally they should be replaced.

SCSS styles are using Bourbon as a framework. We have our own theme engine that supports switching themes with CSS custom properties.

Desktop apps are created with Electron.

Building

The app is bundled with WebPack and built with Grunt. While it's so 2010s to use Grunt nowadays, it's still far ahead of using npm scripts and perfectly does the job of running different actions with JS. However it's not used for any of web bundle building tasks, this part is completely moved to WebPack.

Desktop apps are packaged with electron-packager and then built into distributables with Grunt. We're not using electron-builder for major installers (Windows MSI, macOS app, .deb, .zip) because the setup process is heavily customized and patching electron-builder would be way harder than implementing builders on our own. However electron-builder is used for various Linux packages, such as Snap or AppImage.

Native modules

KeeWeb uses native modules (node.js C++ addons) in desktop apps. All modules used in KeeWeb are built in keeweb-native-modules repository. Native modules are created:

• if the functionality is not available in Electron, for example, YubiKey API
• when implementing it in JavaScript would be significantly slower, for example, Argon2

In other cases it's better to implement everything in JavaScript. For example, a native module for reading QR codes would not be an acceptable solution.

List of used native modules:

• node-keyboard-auto-type: auto-type implemented using keyboard-auto-type
• node-argon2: faster Argon2 for desktop apps
• node-keytar: secret management, used for settings encryption
• node-yubikey-chalresp: YubiKey interaction
• node-usb-detection: for watching USB devices and displaying the YubiKey icon
• node-secure-enclave: Touch ID support on macOS

Getting started

FAQ
Supported Platforms
iOS
Auto Type
Browser AutoFill
YubiKey
Contributing
About KeeWeb

Self-hosting and configuration

Configuration
WebDAV Config
Dropbox and GDrive

Developing and extending KeeWeb

Architecture
Engineering
Plugins
Unsupported Features
TODO

The only official web app is https://app.keeweb.info