A Full-Stack Web Application Template

This repository is an opinionated implementation of a full-stack web application template.

Prerequisites

The following tools should be available on your machine to get started:

• GNU make and related GNU tools to run the Makefiles which, in turn, orchestrate checking, building, testing, and deploying the entire software stack.
• pre-commit to manage various git hooks to enforce coding standards.
• commitizen manages automatic version bumps for semantic versioning based on the conventional commit messages in this repository.
• Docker to build and deploy application containers.

Quick start

After checking out this repository the following steps should stand up the entire stack locally on your machine:

make init
. backend/.venv/bin/activate
make setup
make build
make compose-up

Now navigate to localhost:3001 to read the interactive Swagger documentation for the API…

Architecture

There are three main componenst in this repository, structured into three directories:

• Frontend: TBD. For more details see here.
• Backend: the backend is composed of a PostgREST web server, a message queue based on Postgres, and asynchronous workers implemented in Python using the Dramatiq framework. For more details see here.
• Infrastructure: both frontend and backend build Docker images which are then orchestrated using Docker Compose. For more details see here.

Development

All of the development — checking and compiling code, running tests, and building Docker images — is managed by make and each component has its own Makefile.

To set up this project for development, follow these steps:

1. make init: initialize both frontend and backend.
2. make setup: set up and install all tools and packages to build and test and run.
3. make check: run code checks for both frontend and backend.
4. make test: run all tests.
5. make build: build both frontend and backend packages, then build the Docker images.
6. make docs: generate documentation.
7. make compose-up and make compose-down stand up and tear down the application locally.
8. make clean and make nuke reset the build environment and remove all generated artifacts.

More details can be found in the documentation for each of the components.