Concept

As beavy is modeled under the key assumption that you are building an app for yourself (not one to necessarily be distributed to other), configuration considered part of the build process – and doesn’t dynamically change during run time. Meaning that whenver you change the config.yaml in the main directory you have to restart the backend app and rebuild the assets.

When you start beavy it will look up which modules to include in the app by looking at the configuration file. If the module isn’t listed it won’t even be loaded, in order to to prevent bloath your runtime and cluttering it with things that aren’t needed ever. This is one of the features that keeps your frontend webpack build nice, neat and clean to exactly those things you need. The same applies to the database migrations – they will only be run/applied if the module is included in your configuration.

This allows beavy to ship a ton of code while still having a really small footprint customized to the special setup you want. Heck, some modules even further slim their own code base, dependant on configuration options supplied.

Similar to the idea that configuration is code, styles are considered code, too. Beavy will not load styles or html snippets from the database or any other external configuration as they will be included at compile time.

The core of beavy and jsbeavy is a rather small set of basic components all other modules can rely upon. It brings a lot of handy functions and common and unified behaviours (like JSON-API-Wrappers for paging), which all modules can depend on and should use. If two modules end up implementing the same function, that code should be found in the base setup.

The core also contains the basic framework and mechanismn to load modules, plug their backends together and provide basic functionality (like routing, configuration loading, blueprint management). It also ships the HTML-file, pre-load-json-loading and the jsbeavy frontend modules.

But all other code, among all languages and frameworks is separated in the beavy_modules they belong to. This includes the python flask and worker code, the javascript and react frontend code, SCSS and CSS styles as well as database models and migration needed for this module to work. If something is specific to one module – no matter the language it is written in – it belongs into that module. That includes the documentation.

In order to allow the modules to ship their UI features without having to rely on what the UI exactly looks like, everything in the frontend is shipped as React-Modules in a redux-style infrastructure. While an App might directly import a specific UI component and includes somewhere explicitly, modules by themselves plug into the UI only via hooks. Hooks are essentially managed lists or directories they add themselves info (with a key-name), which either provide a function to be aplied or a component to be rendered. Any part of the UI as well as components of other modules can then query all hooks of a specific name and include the UI components. A component might still provide features to configure those further.

As an example, this is how the MainMenu is constructred. As a general rule a hook may only be included by one component and use the same parameters for all components included, to have a predictable behaviour of the surroundings. A module can rely on the behaviour of the hook to not change. Should that be the case a new name for the hook should be used instead.

As a result one or many modules may provide feature for more hooks than an UI needs or ever will be used. But the overhead of that is incredibly slim.

While the frontend is implemented using React in a Redux-Style, the backend provides all it’s data in a JSON-API.org compliant structured API. All URLs a user can surf to with their browser, provides both an HTML-representation (with preloading) and an JSON-Style when asked for it (you can try that by just adding '?json=1', it detects Ajax-Request and serves JSON if the Content-Header is detected).

Beavy, as so many other web apps, is built in a continuous integration fashion and app implementations based on beavy are expected to have a similar development flow to integrate latest changes. This means that beavy itself doesn’t rely on versioning or release cycles but the master branch on the upstream repo is considered to always be clean – learn more about what that means in the Contributing docs.

In order to allow quick and easy integration of latest upstream beavy changes into your implementation, unlike in classic frameworks or libraries, to develop with beavy, you are expected to maintain your own git fork and commit to that when developing your app. Thus allowing you to facilitate git in all its awesomeness when integrating upstream changes.

Beavy encourages that you fork this project, branch from master and start developing your app in that branch. If you then switch the github default branch of that fork to your new branch, beavy will even send you PRs automatically when master changes (and builds successfully) allowing you to integrate all upstream changes with just a click. Learn more about that in the Development docs.