Centralize API base path and introduce /api/v1 versioning

[tomvothecoder]

Description

Closes #51

This pull request centralizes API path configuration and introduces versioning by adding /api/v1 as the base path for all API endpoints. The change establishes a foundation for future API evolution while maintaining backward compatibility through environment configuration. The PR also upgrades development tooling (mypy 1.19.1, pre-commit hooks) and improves configuration management in both frontend and backend.

Key changes:

• Introduced centralized API versioning with /api/v1 base path via new app/api/version.py module
• Updated all environment files, tests, and CI configuration to use the new versioned API endpoints
• Added explicit environment validation in Vite configuration and upgraded frontend dependency management with dotenv
• Upgraded mypy to 1.19.1 and updated pre-commit configuration for better type checking

Requirements

CI structure

• Split CI to be backend-only
• Renamed workflow to Backend CI
• Kept frontend CI concerns out of this workflow

Python / uv

• Standardized on uv for env + execution
• Installed backend deps via uv venv + uv sync
• Avoided caching .venv (correctness over speed)
• Cached ~/.cache/uv only

pre-commit

• Ensured pre-commit is installed via backend dev deps
• Run pre-commit from repo root
• Scoped pre-commit to backend tools only
• Used SKIP to avoid frontend hooks in backend CI
• Fixed config-path issues (--config-file=backend/pyproject.toml)
• Aligned local and CI pre-commit behavior

pytest / Alembic

• Identified Alembic dependency on working directory
• Run pytest from backend/ (not repo root)
• Added comment explaining why CWD matters
• Verified pytest failures were tooling-related, not code

Caching

• Fixed stale pre-commit cache issues
• Removed unsafe restore-keys usage for tools
• Verified CI cache behavior matches local runs

Still to do (before merge)

• Add final comments to CI steps (pre-commit vs pytest)
• Remove any leftover debug / temporary CI output
• Run full CI once end-to-end to confirm green
• Add --strict-markers to pytest if desired

Explicitly out of scope (future PRs)

• Frontend CI (Node / pnpm / ESLint / Prettier)
• Path-based CI triggers
• Deployment / CD
• Further mypy cleanup

Checklist

• Code follows project style guidelines
• Self-reviewed code
• No new warnings
• Tests added or updated (if needed)
• All tests pass (locally and CI/CD)
• Documentation/comments updated (if needed)
• Breaking change noted (if applicable)

Deployment Notes (if any)

[Copilot]

Pull request overview

This pull request centralizes API path configuration and introduces versioning by adding /api/v1 as the base path for all API endpoints. The change establishes a foundation for future API evolution while maintaining backward compatibility through environment configuration. The PR also upgrades development tooling (mypy 1.19.1, pre-commit hooks) and improves configuration management in both frontend and backend.

Key changes:

• Introduced centralized API versioning with /api/v1 base path via new app/api/version.py module
• Updated all environment files, tests, and CI configuration to use the new versioned API endpoints
• Added explicit environment validation in Vite configuration and upgraded frontend dependency management with dotenv
• Upgraded mypy to 1.19.1 and updated pre-commit configuration for better type checking

Reviewed changes

Copilot reviewed 21 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
backend/app/api/version.py	New module defining centralized API_BASE path constant (/api/v1)
backend/app/api/meta.py	New meta endpoint exposing API version information
backend/app/api/health.py	Extracted health endpoint into dedicated router module
backend/app/main.py	Updated router registration to use centralized API_BASE prefix
backend/tests/**/*.py	Updated all test URLs to use API_BASE constant
backend/pyproject.toml	Upgraded mypy to 1.19.1, refined per-file-ignores patterns, added isort configuration
backend/uv.lock	Lock file updates for mypy 1.19.1 and new librt dependency
frontend/vite.config.ts	Replaced Vite's loadEnv with explicit dotenv loading and added environment file validation
frontend/src/api/api.ts	Removed fallback default for VITE_API_BASE_URL to enforce explicit configuration
frontend/package.json & frontend/pnpm-lock.yaml	Added dotenv dependency for environment file loading
.envs/**/*.env.example	Updated all example environment files with /api/v1 paths
.pre-commit-config.yaml	Upgraded pre-commit hooks to v6.0.0 and mypy to v1.19.1, added explicit config file arguments
.github/workflows/backend-ci.yml	Renamed workflow, added path filters, updated cache strategy, clarified pre-commit execution context
README.md	Enhanced pre-commit documentation with explicit guidance on running from repo root

Files not reviewed (1)

• frontend/pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

.github/workflows/backend-ci.yml:144

• The cache key for pre-commit has been changed from 'pre-commit-${{ runner.os }}-' to remove the restore-keys. While this may be intentional for stricter cache control, it means that partial cache matches will no longer be used when the config file changes, potentially slowing down CI runs. Consider adding back 'restore-keys: pre-commit-${{ runner.os }}-' to allow partial cache hits.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.