General refactor and code cleanup (#75)

Author: tomvothecoder

.envs/dev/frontend.env.example

@@ -4,4 +4,4 @@
 
 # Backend configuration
 # -------------------------------------------------------------------
-VITE_API_BASE_URL=https://127.0.0.1:8000/api
+VITE_API_BASE_URL=https://127.0.0.1:8000/api

.envs/prod/frontend.env.example

@@ -4,4 +4,4 @@
 
 # Backend configuration
 # -------------------------------------------------------------------
-VITE_API_BASE_URL=https://127.0.0.1:8000/api
+VITE_API_BASE_URL=https://127.0.0.1:8000/api

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -60,4 +60,4 @@ body:
       description: |
         Any other information?
     validations:
-      required: false
+      required: false

.github/ISSUE_TEMPLATE/devops.yml

@@ -1,6 +1,6 @@
 name: DevOps Task
 description: Template for tracking DevOps-related tasks and improvements.
-title: "[DevOps] "
+title: "[DevOps]: "
 labels: ["type: devops"]
 assignees: []
 
@@ -33,20 +33,11 @@ body:
     validations:
       required: false
 
-  - type: input
-    id: deadline
-    attributes:
-      label: Deadline
-      description: When should this task be completed by? (optional)
-      placeholder: YYYY-MM-DD
-    validations:
-      required: false
-
   - type: textarea
     id: additional
     attributes:
       label: Additional Notes
       description: Any other information or resources.
       placeholder: Links, references, or related issues.
     validations:
-      required: false
+      required: false

.github/ISSUE_TEMPLATE/planning_task.yml

@@ -55,4 +55,4 @@ body:
       description: When should this task be completed?
       placeholder: YYYY-MM-DD
     validations:
-      required: false
+      required: false

.github/pull_request_template.md

@@ -18,4 +18,4 @@
 ## Deployment Notes (if any)
 <!--
   Add any special deployment or migration steps here.
--->
+-->

.pre-commit-config.yaml

@@ -0,0 +1,53 @@
+repos:
+  # ------------------------
+  # General sanity checks
+  # ------------------------
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+
+  # ------------------------
+  # Backend (Python / FastAPI)
+  # ------------------------
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+        files: ^backend/
+      - id: ruff-format
+        files: ^backend/
+
+  # ------------------------
+  # Frontend (Node / TS)
+  # NOTE: Git hooks run in a non-interactive shell. Node tooling (pnpm) must be available on PATH.
+  # ------------------------
+  - repo: local
+    hooks:
+    - id: frontend-eslint
+      name: Frontend ESLint (staged files)
+      entry: >
+        bash -c '
+          command -v pnpm >/dev/null 2>&1 ||
+            { echo "❌ pnpm not found on PATH (git hooks run non-interactively)"; exit 1; };
+          export PATH="$HOME/.local/bin:$HOME/.pnpm:$PATH";
+          pnpm --dir frontend run lint:fix:staged
+        '
+      language: system
+      files: ^frontend/.*\.(ts|tsx|js|jsx)$
+
+    - id: frontend-prettier
+      name: Frontend Prettier (staged files)
+      entry: >
+        bash -c '
+          command -v pnpm >/dev/null 2>&1 ||
+            { echo "❌ pnpm not found on PATH (git hooks run non-interactively)"; exit 1; };
+          export PATH="$HOME/.local/bin:$HOME/.pnpm:$PATH";
+          pnpm --dir frontend run format:staged
+        '
+      language: system
+      files: ^frontend/.*\.(ts|tsx|js|jsx|css|json|md)$

.vite/deps/_metadata.json

@@ -5,4 +5,4 @@
   "browserHash": "deca6459",
   "optimized": {},
   "chunks": {}
-}
+}

Makefile

@@ -40,43 +40,75 @@ help:
 	@echo ""
 	@echo "$(BLUE)Environment:$(NC) APP_ENV=$(env)"
 	@echo ""
+
 	@echo "  $(YELLOW)Project Setup$(NC)"
-	@echo "    make setup-dev env=dev                     # Bare-metal dev setup"
-	@echo "    make setup-dev-docker env=dev_docker       # Docker dev setup"
-	@echo "    make setup-dev-assets env=<env>            # Ensure .env + certs exist"
-	@echo "    make copy-env env=<env>                    # Copy .env.example → .env"
-	@echo "    make gen-certs                             # Generate dev SSL certs"
+	@echo "    make install                             # Install backend + frontend deps + pre-commit"
+	@echo "    make setup-dev env=dev                   # Bare-metal dev setup"
+	@echo "    make setup-dev-docker env=dev_docker     # Docker dev setup"
+	@echo "    make setup-dev-assets env=<env>          # Ensure .env files + certs exist"
+	@echo "    make copy-env env=<env>                  # Copy .env.example → .env"
+	@echo "    make gen-certs                           # Generate dev SSL certs"
+	@echo ""
+
+	@echo "  $(YELLOW)Pre-commit$(NC)"
+	@echo "    make pre-commit-install                  # Install git pre-commit hooks"
+	@echo "    make pre-commit-run                      # Run all pre-commit hooks"
 	@echo ""
+
 	@echo "  $(YELLOW)Backend Commands$(NC)"
-	@echo "    make backend-install                       # Create venv + install deps"
-	@echo "    make backend-clean                         # Clean caches"
-	@echo "    make backend-run                           # Start FastAPI"
-	@echo "    make backend-reload                        # Start with auto-reload"
-	@echo "    make backend-migrate m='msg'               # Create Alembic migration"
-	@echo "    make backend-upgrade                       # Apply migrations"
-	@echo "    make backend-downgrade rev=<rev>           # Downgrade DB"
-	@echo "    make backend-test                          # Run pytest"
+	@echo "    make backend-install                     # Create venv (if missing) + install deps"
+	@echo "    make backend-reset                       # Recreate venv + reinstall deps"
+	@echo "    make backend-clean                       # Clean Python caches"
+	@echo "    make backend-run                         # Start FastAPI server"
+	@echo "    make backend-reload                      # Start FastAPI with auto-reload"
+	@echo "    make backend-migrate m='msg'             # Create Alembic migration"
+	@echo "    make backend-upgrade                     # Apply DB migrations"
+	@echo "    make backend-downgrade rev=<rev>         # Downgrade DB"
+	@echo "    make backend-test                        # Run pytest"
 	@echo ""
+
 	@echo "  $(YELLOW)Frontend Commands$(NC)"
-	@echo "    make frontend-install                      # Install dependencies"
-	@echo "    make frontend-dev                          # Start Vite dev server"
-	@echo "    make frontend-build                        # Build site"
-	@echo "    make frontend-preview                      # Preview built site"
-	@echo "    make frontend-lint                         # ESLint"
+	@echo "    make frontend-install                    # Install frontend dependencies"
+	@echo "    make frontend-clean                      # Remove node_modules + build artifacts"
+	@echo "    make frontend-dev                        # Start Vite dev server"
+	@echo "    make frontend-build                      # Build frontend"
+	@echo "    make frontend-preview                    # Preview production build"
+	@echo "    make frontend-lint                       # Run ESLint"
+	@echo "    make frontend-fix                        # Run ESLint with --fix"
 	@echo ""
-	@echo "  $(YELLOW)Docker$(NC)"
-	@echo "    make docker-up env=<env> svc=<svc>         # Start service(s)"
-	@echo "    make docker-build env=<env> svc=<svc>      # Build service images"
+
+	@echo "  $(YELLOW)Docker Commands$(NC)"
+	@echo "    make docker-build env=<env> svc=<svc>    # Build Docker image(s)"
+	@echo "    make docker-rebuild env=<env> svc=<svc>  # Build Docker image(s) without cache"
+	@echo "    make docker-up env=<env> svc=<svc>       # Start service(s)"
+	@echo "    make docker-up-detached env=<env> svc=<svc> # Start service(s) in background"
+	@echo "    make docker-down env=<env>               # Stop all services"
+	@echo "    make docker-restart env=<env> svc=<svc>  # Restart service(s)"
+	@echo "    make docker-logs env=<env> svc=<svc>     # Follow service logs"
+	@echo "    make docker-shell env=<env> svc=<svc>    # Shell into running container"
+	@echo "    make docker-ps env=<env>                 # List running containers"
+	@echo "    make docker-config env=<env>             # Show resolved docker-compose config"
 	@echo ""
+
 	@echo "  $(YELLOW)Database (via Docker)$(NC)"
-	@echo "    make db-init env=<env>                     # Migrate + seed dev DB"
+	@echo "    make db-migrate m='msg' env=<env>        # Create migration"
+	@echo "    make db-upgrade env=<env>                # Apply migrations"
+	@echo "    make db-rollback env=<env>               # Roll back last migration"
+	@echo "    make db-seed env=<env>                   # Seed database (non-prod only)"
+	@echo "    make db-init env=<env>                   # Migrate + seed database"
+	@echo ""
+
+	@echo "  $(YELLOW)Build & Cleanup$(NC)"
+	@echo "    make build                               # Build frontend"
+	@echo "    make preview                             # Preview frontend build"
+	@echo "    make clean                               # Clean backend + frontend artifacts"
 
 
 # ============================================================
 # ⚙️ CORE SETUP
 # ============================================================
 
-.PHONY: setup-dev setup-dev-docker setup-dev-assets copy-env gen-certs
+.PHONY: setup-dev setup-dev-docker setup-dev-assets copy-env gen-certs install
 
 # ------------------------------------------------------------
 # Bare-metal dev
@@ -153,14 +185,29 @@ gen-certs:
 	cd certs && ./generate-dev-certs.sh
 
 
+# ------------------------------------------------------------
+# Pre-commit
+# ------------------------------------------------------------
+
+.PHONY: pre-commit-install pre-commit-run
+
+pre-commit-install:
+	cd $(BACKEND_DIR) && uv run pre-commit install --install-hooks
+
+pre-commit-run:
+	cd $(BACKEND_DIR) && uv run pre-commit run --all-files
+
 # ============================================================
 # 🧑‍💻 BACKEND COMMANDS
 # ============================================================
 
 .PHONY: backend-install backend-clean backend-run backend-reload backend-migrate backend-upgrade backend-downgrade backend-test
 
 backend-install:
-	cd $(BACKEND_DIR) && uv venv .venv && uv sync --all-groups
+	cd $(BACKEND_DIR) && if [ ! -d .venv ]; then uv venv .venv; fi && uv sync --all-groups
+
+backend-reset:
+	cd $(BACKEND_DIR) && rm -rf .venv && uv venv .venv && uv sync --all-groups
 
 backend-clean:
 	cd $(BACKEND_DIR) && find . -type d -name "__pycache__" -exec rm -rf {} + && rm -rf .pytest_cache .ruff_cache build dist .mypy_cache
@@ -288,9 +335,7 @@ db-init:
 
 .PHONY: clean install
 
-install:
-	make backend-install
-	make frontend-install
+install: backend-install frontend-install pre-commit-install
 
 clean:
 	make backend-clean

README.md

@@ -243,16 +243,94 @@ Pull requests should include tests + documentation updates.
 
 ---
 
-## Makefile Overview
+## 🪝 Pre-commit Hooks
 
-The Makefile provides **unified commands** for backend, frontend, Docker, DB, and environment management.
+This repository uses **[pre-commit](https://pre-commit.com/)** to enforce consistent code quality checks for both the **backend (Python)** and **frontend (TypeScript)**.
 
-View all available commands:
+Pre-commit runs automatically on `git commit` and will block commits if checks fail.
+
+---
+
+### What pre-commit checks
+
+- **Backend**
+  - Ruff linting and formatting
+  - Python style and correctness checks
+- **Frontend**
+  - ESLint (auto-fix on staged files)
+  - Prettier formatting (staged files only)
+
+All hooks are configured in the root `.pre-commit-config.yaml`.
+
+> **Note:** Git hooks run in a non-interactive shell
+> Make sure that Node.js tools (such as `pnpm`) are available in your system `PATH` so pre-commit hooks can execute successfully.
+
+---
+
+### Installing pre-commit (recommended)
+
+Pre-commit is installed **inside the backend uv environment** and wired up via the Makefile.
+
+After cloning the repo, run:
 
 ```bash
-make help
+make install
 ```
 
+This will:
+
+- Create the backend `uv` virtual environment (if missing)
+- Install Python and frontend dependencies
+- Install the git pre-commit hooks
+
+If you only want to (re)install the hooks:
+
+```bash
+make pre-commit-install
+```
+
+---
+
+### Running pre-commit manually
+
+To run all hooks against all files:
+
+```bash
+make pre-commit-run
+```
+
+Or directly:
+
+```bash
+cd backend
+uv run pre-commit run --all-files
+```
+
+You can also run pre-commit from **any directory inside the repo**; it always resolves the repo root configuration.
+
+---
+
+### Notes & expectations
+
+- Pre-commit uses the **existing project environments**:
+  - Python hooks run via `uv`
+  - Frontend hooks run via `pnpm`
+- The tools themselves (`uv`, `pnpm`, `node`) are expected to already be installed on your system
+- Hooks are **fast** and only run on staged files by default
+- Formatting issues are usually auto-fixed; re-stage files and retry the commit if needed
+
+---
+
+### Skipping hooks (not recommended)
+
+If you must bypass pre-commit temporarily:
+
+```bash
+git commit --no-verify
+```
+
+Please only do this when absolutely necessary.
+
 ---
 
 ## Local HTTPS