Centralize API base path and introduce /api/v1 versioning (#78)

Author: tomvothecoder

.envs/dev/backend.env.example

@@ -51,7 +51,7 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:

.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/v1

.envs/dev_docker/backend.env.example

@@ -51,7 +51,7 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:

.envs/dev_docker/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/v1

.envs/prod/backend.env.example

@@ -51,9 +51,9 @@ GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret
 
 # Must match the callback URL in your GitHub App configuration
 # This is the backend OAuth callback endpoint that GitHub calls with the authorization code.
-GITHUB_REDIRECT_URL=https://127.0.0.1/auth/github/callback
+GITHUB_REDIRECT_URL=https://127.0.0.1/api/v1/auth/github/callback
 # For production, this must also point to the backend's OAuth callback endpoint
-# GITHUB_REDIRECT_URL=https://app.${DOMAIN}/auth/callback
+# GITHUB_REDIRECT_URL=https://app.${DOMAIN}/api/v1/auth/callback
 
 # Secret used to sign OAuth "state" parameter (prevents CSRF)
 # Generate securely with:

.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/v1

.github/workflows/build.yml .github/workflows/backend-ci.yml.github/workflows/build.yml renamed to .github/workflows/backend-ci.yml

@@ -1,16 +1,25 @@
-name: CI
+name: Backend CI
 
 on:
   pull_request:
     branches: [main]
+    paths:
+      - backend/**
+      - .pre-commit-config.yaml
+      - .github/workflows/backend-ci.yml
   push:
     branches: [main]
+    paths:
+      - backend/**
+      - .pre-commit-config.yaml
+      - .github/workflows/backend-ci.yml
   workflow_dispatch: {}
 
 jobs:
   backend:
     name: Backend checks
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     services:
       postgres:
@@ -60,7 +69,7 @@ jobs:
       # --------------------------------------------------
       GITHUB_CLIENT_ID: dummy
       GITHUB_CLIENT_SECRET: dummy
-      GITHUB_REDIRECT_URL: http://localhost/api/auth/github/callback
+      GITHUB_REDIRECT_URL: http://localhost/api/v1/auth/github/callback
       GITHUB_STATE_SECRET_KEY: dummy
 
       # --------------------------------------------------
@@ -108,15 +117,13 @@ jobs:
       # -------------------------
       # Cache uv + dependencies
       # -------------------------
-      - name: Cache uv
+      - name: Cache uv cache
         uses: actions/cache@v4
         with:
-          path: |
-            ~/.cache/uv
-            backend/.venv
-          key: uv-${{ runner.os }}-${{ hashFiles('backend/uv.lock') }}
+          path: ~/.cache/uv
+          key: uv-cache-${{ runner.os }}-${{ hashFiles('backend/uv.lock') }}
           restore-keys: |
-            uv-${{ runner.os }}-
+            uv-cache-${{ runner.os }}-
 
       # -------------------------
       # Install backend deps
@@ -135,21 +142,24 @@ jobs:
         with:
           path: ~/.cache/pre-commit
           key: pre-commit-${{ runner.os }}-${{ hashFiles('.pre-commit-config.yaml') }}
-          restore-keys: |
-            pre-commit-${{ runner.os }}-
 
       # -------------------------
       # Run pre-commit
       # -------------------------
-      - name: Run pre-commit
-        working-directory: backend
+      - name: Run pre-commit (backend only)
+        env:
+          SKIP: frontend-eslint,frontend-prettier
         run: |
-          uv run pre-commit run --all-files
+          uv run --project backend pre-commit run --all-files
 
       # -------------------------
       # Run pytest
       # -------------------------
       - name: Run pytest
+        # NOTE:
+        # Pytest (and Alembic) must run from the backend directory so relative paths
+        # like alembic.ini and script_location resolve correctly. `--project` only
+        # selects the virtualenv; it does not change the working directory.
         working-directory: backend
         run: |
-          uv run pytest
+          uv run pytest --strict-markers

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
   # General sanity checks
   # ------------------------
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -17,16 +17,26 @@ repos:
     rev: v0.14.10
     hooks:
       - id: ruff-check
-        args: [--fix]
-        files: ^backend/
+        name: ruff (lint)
+        args:
+          - --config=backend/pyproject.toml
+          - --fix
+        files: ^backend/.*\.py$
+
       - id: ruff-format
-        files: ^backend/
+        name: ruff (format)
+        args:
+          - --config=backend/pyproject.toml
+        files: ^backend/.*\.py$
+
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+    rev: v1.19.1
     hooks:
       - id: mypy
         name: mypy (type checking)
+        args:
+          - --config-file=backend/pyproject.toml
         files: ^backend/.*\.py$
         additional_dependencies:
           - fastapi

README.md

@@ -251,19 +251,49 @@ Pre-commit runs automatically on `git commit` and will block commits if checks f
 
 ---
 
+### ⚠️ Important: Where to run pre-commit
+
+**Pre-commit must always be run from the repository root.**
+
+Some hooks (notably `mypy`) reference configuration files using paths relative to the repo root (for example, `backend/pyproject.toml`). Running pre-commit from a subdirectory such as `backend/` can cause those configurations to be missed, leading to inconsistent or misleading results.
+
+✅ Correct:
+
+```bash
+pre-commit run --all-files
+```
+
+❌ Incorrect:
+
+```bash
+cd backend
+pre-commit run --all-files
+```
+
+In CI, pre-commit is also executed from the repository root for this reason.
+
+> **Note:** When using `uv`, CI runs pre-commit via
+> `uv run --project backend pre-commit run --all-files`.
+> The `--project` flag selects the backend virtual environment, but **does not change the working directory**. Pre-commit itself must still be invoked from the repo root so configuration paths resolve correctly.
+
+---
+
 ### What pre-commit checks
 
 - **Backend**
+
   - Ruff linting and formatting
-  - Python style and correctness checks
+  - Python style and correctness checks (mypy)
+
 - **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.
+> **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 frontend hooks can execute successfully.
 
 ---
 
@@ -293,7 +323,7 @@ make pre-commit-install
 
 ### Running pre-commit manually
 
-To run all hooks against all files:
+To run all hooks against all files (from the repo root):
 
 ```bash
 make pre-commit-run
@@ -302,12 +332,9 @@ 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

backend/app/api/health.py

@@ -0,0 +1,8 @@
+from fastapi import APIRouter
+
+router = APIRouter(tags=["health"])
+
+
+@router.get("/health")
+async def health():
+    return {"status": "ok"}