Design Philosophy

The goal of this project is to provide a ready-to-use boilerplate that is both robust and flexible enough to accomodate the diverse projects Lonestone is working on, and yet easy to use and maintain.

Finding balance between features

As the boilerplate is meant to be a starting point for new projects, we needed to find a balance between features that are useful for most projects, and features that are only useful for specific projects.

In a perfect world, we would have a CLI tool allowing the user to create a project with a specific set of features. Sadly, the devil is in the details: a lot of features are tighly coupled, or modify the same files, making it hard to combine them in a CLI.

Instead, we chose to propose a all-in-one, ready-to-use solution. The promise is that you can clone the repo and start coding right away.

For this strategy to pay off, we need to keep the boilerplate as simple as possible.

Hence why adding a new feature to the boilerplate codebase must be done with care. A simple rule of thumb is to check if the feature is used in 80% of Lonestone’s projects. If not, it’s probably not worth adding it to the boilerplate. Instead, it should be added as a guide in this documentation.

Evolution of an existing project is another important factor. Without a CLI, removal or addition of features must be done manually. To help this process, we will provide a “How to remove” section in each “core features” page. For addition, we will provide guides.

Key principles

• Velocity is key for us, as we bootstrap new projects regularly. It’s fine to have ~20% of the codebase unused, as long as it’s easy to remove
• Technical choices need to be battle-tested, as we use this boilerplate on clients’ projects. This is not the place for experimentations
• Simplicity of maintenance and upgradability. We don’t have the staff to maintain a lot of packages, sync their versions, etc. The process of maintaining this repository must be as simple as possible, even if it comes at the cost of features/upgrade path/etc. Beware of over engineering, and trust the developers to read and understand the codebase and docs.
• Upgradability of existing projects is not a top priority. Once a project is launched, we will not upgrade the dependencies that much (doing it manually is OK)
• Only the 80%. If a feature is not used in 80% of Lonestone’s projects, it should be added as a guide in this documentation, and not shipped with the boilerplate.
• Robustness is not all about code. The documentation should feature numerous guides to add “almost necessary” features to the project, such as logging, tracing, analytics, etc.
• Learning place. Finally, this boilerplate is not only a starting point for new projects, but also a learning place for new developers. The documentation should be clear and easy to understand, and feature numerous explanations as to why we chose some tools.