feat: add backend composed of a Postgres database, Alembic to orchestrate migrations, a PostgREST web server, a message queue built on top of the Postgres database, and async Python jobs implemented by the Dramatiq framework

.gitignore

@@ -5,6 +5,34 @@
 *.mo
 *.pot
 
+# Python byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Python Distribution / packaging
+.coverage
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+include/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
 # macOS stuff
 .DS_Store
 

.pre-commit-config.yaml

@@ -50,3 +50,102 @@ repos:
   # Commenting this out because https://github.com/pappasam/toml-sort/issues/11
   # - id: pretty-format-toml
   #   args: [--autofix]
+
+#
+# Backend.
+#
+
+# Sort imports.
+- repo: https://github.com/pycqa/isort
+  rev: 6.0.1
+  hooks:
+  - id: isort
+    name: Sort import statements
+    files: ^backend/
+    args: [--settings-path, backend/develop.toml]
+    stages: [pre-commit]
+
+# Add Black code formatters.
+- repo: https://github.com/ambv/black
+  rev: 25.1.0
+  hooks:
+  - id: black
+    name: Format code
+    files: ^backend/
+    args: [--config, backend/develop.toml]
+- repo: https://github.com/asottile/blacken-docs
+  rev: 1.19.1
+  hooks:
+  - id: blacken-docs
+    name: Format code in docstrings
+    files: ^backend/
+    types: [text, python]
+    args: [--line-length, '120']
+    additional_dependencies: [black==25.1.0]
+
+# Upgrade and rewrite Python idioms.
+- repo: https://github.com/asottile/pyupgrade
+  rev: v3.20.0
+  hooks:
+  - id: pyupgrade
+    name: Upgrade code idioms
+    files: ^backend/src/template_jobs/|^backend/tests/
+    args: [--py313-plus]
+
+# Similar to pylint, with a few more/different checks. For more available
+# extensions: https://github.com/DmytroLitvinov/awesome-flake8-extensions
+- repo: https://github.com/pycqa/flake8
+  rev: 7.2.0
+  hooks:
+  - id: flake8
+    name: Check flake8 issues
+    files: ^backend/src/template_jobs/|^backend/tests/
+    types: [text, python]
+    additional_dependencies: [flake8-bugbear==24.12.12, flake8-builtins==2.5.0, flake8-comprehensions==3.16.0, flake8-docstrings==1.7.0, flake8-logging==1.7.0, flake8-mutable==1.2.0, flake8-noqa==1.4.0, flake8-print==5.0.0, flake8-pyi==25.5.0, flake8-pytest-style==2.1.0, flake8-rst-docstrings==0.3.1, pep8-naming==0.15.1]
+    args: [--config, backend/.flake8]
+
+# Run Pylint from the local repo to make sure venv packages
+# specified in pyproject.toml are available.
+- repo: local
+  hooks:
+  - id: pylint
+    name: Check pylint issues
+    entry: pylint
+    language: python
+    files: ^backend/src/template_jobs/|^backend/tests/
+    types: [text, python]
+    args: [--rcfile, backend/develop.toml]
+
+# Type-check all Python code.
+- repo: local
+  hooks:
+  - id: mypy
+    name: Check typing annotations
+    entry: mypy
+    language: python
+    files: ^backend/src/template_jobs/|^backend/tests/
+    types: [text, python]
+    args: [--config-file, backend/develop.toml]
+
+# Check for potential security issues.
+- repo: https://github.com/PyCQA/bandit
+  rev: 1.8.3
+  hooks:
+  - id: bandit
+    name: Check for security issues
+    files: ^backend/src/template_jobs/|^backend/tests/
+    types: [text, python]
+    args: [--configfile, backend/develop.toml]
+    additional_dependencies: ['bandit[toml]']
+
+# On push to the remote, run the unit tests.
+- repo: local
+  hooks:
+  - id: pytest
+    name: Run unit tests
+    entry: env COVERAGE_CORE=sysmon pytest -c backend/develop.toml --cov-config backend/develop.toml backend/src/template_jobs/ backend/tests/ backend/docs/
+    language: python
+    verbose: true
+    always_run: true
+    pass_filenames: false
+    stages: [pre-push]

Makefile

@@ -0,0 +1,101 @@
+
+# Use bash as the shell when executing a rule's recipe. For more details:
+# https://www.gnu.org/software/make/manual/html_node/Choosing-the-Shell.html
+SHELL := bash
+
+
+.PHONY: all all-frontend all-backend
+all: all-frontend all-backend
+all-frontend:
+	$(MAKE) --directory frontend all
+all-backend:
+	$(MAKE) --directory backend all
+
+
+.PHONY: init init-frontend init-backend
+init: init-frontend init-backend
+init-frontend:
+	$(MAKE) --directory frontend init
+init-backend:
+	$(MAKE) --directory backend init
+
+
+.PHONY: setup setup-frontend setup-backend
+setup: setup-frontend setup-backend
+	pre-commit install
+setup-frontend:
+	$(MAKE) --directory frontend setup
+setup-backend:
+	$(MAKE) --directory backend setup
+
+
+.PHONY: check check-frontend check-backend
+check: check-frontend check-backend
+check-frontend:
+	$(MAKE) --directory frontend check
+check-backend:
+	$(MAKE) --directory backend check
+
+
+.PHONY: test test-frontend test-backend
+test: test-frontend test-backend
+test-frontend:
+	$(MAKE) --directory frontend test
+test-backend:
+	$(MAKE) --directory backend test
+
+
+.PHONY: build build-frontend build-backend build-docker build-docker-frontend build-docker-backend
+build: build-frontend build-backend build-docker
+build-docker: build-docker-frontend build-docker-backend
+build-frontend:
+	$(MAKE) --directory frontend build
+build-docker-frontend:
+	$(MAKE) --directory frontend build-docker
+build-backend:
+	$(MAKE) --directory backend build
+build-docker-backend:
+	$(MAKE) --directory backend build-docker
+
+
+.PHONY: docs docs-frontend docs-backend
+docs: docs-frontend docs-backend
+docs-frontend:
+	$(MAKE) --directory frontend docs
+docs-backend:
+	$(MAKE) --directory frontend docs
+
+
+.PHONY: compose-up compose-down compose-up-develop compose-down-develop
+compose-up:
+	docker compose --file infra/docker-compose.yaml up
+compose-down:
+	docker compose --file infra/docker-compose.yaml down
+compose-up-develop:
+	docker compose --file infra/docker-compose-develop.yaml up
+compose-down-develop:
+	docker compose --file infra/docker-compose-develop.yaml down
+
+
+.PHONY: clean clean-frontend clean-backend
+clean: clean-frontend clean-backend
+	rm -fr .coverage .mypy_cache/  # These backend/ files are created at the base of the repo.
+clean-frontend:
+	$(MAKE) --directory frontend clean
+clean-backend:
+	$(MAKE) --directory backend clean
+
+
+.PHONY: nuke nuke-git-hooks nuke-frontend nuke-backend nuke-caches nuke-caches-frontend nuke-caches-backend
+nuke: clean nuke-git-hooks nuke-caches nuke-frontend nuke-backend
+nuke-caches: nuke-caches-frontend nuke-caches-backend
+nuke-git-hooks:
+	find .git/hooks/ -type f ! -name '*.sample' -delete
+nuke-caches-frontend:
+	$(MAKE) --directory frontend nuke-caches
+nuke-frontend:
+	$(MAKE) --directory frontend nuke
+nuke-caches-backend:
+	$(MAKE) --directory backend nuke-caches
+nuke-backend:
+	$(MAKE) --directory backend nuke

README.md

@@ -3,3 +3,51 @@
 # 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](https://www.gnu.org/software/make/) and related GNU tools to run the Makefiles which, in turn, orchestrate checking, building, testing, and deploying the entire software stack.
+- [pre-commit](https://pre-commit.com/) to manage various [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to enforce coding standards.
+- [commitizen](https://commitizen-tools.github.io/commitizen/) manages automatic version bumps for _semantic versioning_ based on the _conventional commit messages_ in this repository.
+- [Docker](https://www.docker.com/) 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](http://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](frontend/README.md).
+- **Backend**: the backend is composed of a [PostgREST](https://github.com/PostgREST/postgrest) web server, a message queue based on Postgres, and asynchronous workers implemented in Python using the [Dramatiq](https://github.com/Bogdanp/dramatiq) framework. For more details see [here](backend/README.md).
+- **Infrastructure**: both frontend and backend build Docker images which are then orchestrated using [Docker Compose](https://docs.docker.com/compose/). For more details see [here](infra/README.md).
+
+## 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.

backend/.flake8

@@ -0,0 +1,52 @@
+# Unfortunately, Flake8 does not support pyproject.toml configuration.
+# https://github.com/PyCQA/flake8/issues/234
+#
+# More details regarding Flake8 and Black interplay:
+# https://github.com/psf/black/blob/main/docs/guides/using_black_with_other_tools.md#flake8
+[flake8]
+
+# Enable a few additional checks.
+#
+# https://github.com/PyCQA/flake8-bugbear#how-to-enable-opinionated-warnings
+# B9: Bugbear's extended opinionated checks
+#
+# https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
+# W504: line break after binary operator (Black compliant)
+extend-select = B9, W504
+
+# Disable several warnings that don't play nice with PEP8 or Black,
+# or that are a bit of a nuisance in general.
+#
+# http://www.pydocstyle.org/en/latest/error_codes.html
+# D105: Missing docstring in magic method
+#
+# https://pycodestyle.pycqa.org/en/latest/intro.html#error-codes
+# E203: whitespace before ‘,’, ‘;’, or ‘:’ (not Black compliant)
+# E501: line too long (managed better by Bugbear's B950)
+# W503: line break before binary operator (not Black compliant)
+#
+# https://github.com/peterjc/flake8-rst-docstrings#configuration
+# RST307: Error in "XXX" directive
+ignore = D105, E203, E501, RST307, W503
+per-file-ignores =
+
+# More assorted goodness.
+max-line-length = 120
+show-source = true
+
+# Ensure that Flake8 warnings are silenced correctly:
+# https://github.com/plinss/flake8-noqa#options
+noqa-require-code = true
+
+# Ensure that Sphinx extensions of .rst are recognized:
+# https://github.com/peterjc/flake8-rst-docstrings#configuration
+rst-roles = class, func, ref
+rst-directives = envvar, exception
+rst-substitutions = version
+
+# Ensure that Sphinx docstrings use Numpy format for docstrings:
+# https://github.com/PyCQA/flake8-docstrings
+#
+# For details on the Numpy format:
+# https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html
+docstring-convention = numpy

backend/LICENSE.md

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 1999–2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.