diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d55211d..4472c92 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -132,6 +132,33 @@ make reqs-upgrade
> Remember that if you change the [requirements.txt],
you need to rebuild the docker image (`make docker-build`) in order to use it locally.
+### Using UV for faster local development (Optional)
+
+**This is for local development only.** Docker builds use pip by default.
+
+If you prefer faster dependency resolution and installation during local development,
+you can optionally use [uv](https://docs.astral.sh/uv/) instead of pip.
+
+Install `uv`:
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+Then, use it with the justfile commands:
+
+```
+just install
+```
+
+Or use the Makefile commands while overriding the `PIP` variable:
+
+```shell
+make install PIP="uv pip"
+```
+
+This will use `uv pip` for faster resolution while maintaining the same functionality.
+Docker and CI/CD pipelines will continue to use standard pip.
+
## Git Workflow
@@ -170,7 +197,7 @@ Try to follow these guidelines:
- Maintain a clean commit history in your feature branch.
Use interactive rebase (`git rebase -i`) to squash, reorder, or edit commits.[^1]
-
+
- If you are not using [pre-commit] hooks,
use the provided [Makefile] commands (`format`, `lint`, `codespell`, `typecheck`)
as much as possible to maintain code quality.
@@ -195,8 +222,8 @@ Try to follow these guidelines:
-A Google Cloud build that publishes a Docker image is triggered in the following cases:
-- When a commit is merged into `main` or `develop`.
+A Google Cloud build that publishes a Docker image is triggered in the following cases:
+- When a commit is merged into `main` or `develop`.
- When a new tag is created.
diff --git a/justfile b/justfile
new file mode 100644
index 0000000..705a173
--- /dev/null
+++ b/justfile
@@ -0,0 +1,97 @@
+# Justfile - Thin wrapper for local development
+# Adjusts PYTHON and PIP variables for venv, then calls Make recipes
+# Use: `just install`, `just test`, `just reqs`, etc.
+
+set shell := ["bash", "-c"]
+
+
+VENV_NAME := ".venv"
+PYTHON := VENV_NAME / "bin" / "python"
+PIP := "uv pip"
+
+[private]
+default:
+ just --list
+
+# Create virtual environment
+venv:
+ make venv
+
+# Upgrade pip
+upgrade-pip:
+ make upgrade-pip PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Install only test dependencies
+install-test: upgrade-pip
+ make install-test PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Install the package in editable mode & all dependencies for local development
+install: upgrade-pip
+ make install PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Run all unit tests exporting coverage.xml report
+test:
+ make test PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Install and pre-commit hooks
+hooks:
+ make hooks PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Auto-format python source files according with PEP8
+format:
+ make format PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Lint python source files
+lint:
+ make lint PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Use Codespell to do spell checking
+codespell:
+ make codespell PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Perform type-checking
+typecheck:
+ make typecheck PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Use pip-audit to scan for known vulnerabilities
+audit:
+ make audit PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Run all pre-commit hooks
+pre-commit:
+ make pre-commit PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Run the standard set of checks performed in CI
+all: lint codespell typecheck audit test
+
+# Compile requirements.txt with pip-tools
+reqs:
+ make reqs PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Upgrade requirements.txt with pip-tools
+reqs-upgrade:
+ make reqs-upgrade PYTHON="{{ PYTHON }}" PIP="{{ PIP }}"
+
+# Docker: Build docker images
+docker-build:
+ make docker-build
+
+# Docker: Create the docker volume for GCP
+docker-volume:
+ make docker-volume
+
+# Docker: Authenticate to google cloud and configure the project
+docker-gcp:
+ make docker-gcp
+
+# Docker: Run tests using prod image, exporting coverage.xml report
+docker-ci-test:
+ make docker-ci-test
+
+# Docker: Enter interactive dev container shell
+docker-shell:
+ make docker-shell
+
+# Clean local caches and build artifacts
+clean:
+ make clean