Merge branch 'master' into fix-backend-reload-during-playwright-tests

[skip ci]

.agents/skills/fastapi

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/fastapi/.agents/skills/fastapi

.agents/skills/library-skills/.library-skills.json

@@ -0,0 +1,4 @@
+{
+  "kind": "tool-skill",
+  "version": "0.0.19"
+}

.agents/skills/library-skills/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: library-skills
+description: Use Library Skills to discover, install, refresh, repair, check, and manage agent skills from installed packages.
+---
+
+# Library Skills
+
+Use this skill when a project might benefit from agent skills bundled by its installed packages, or when existing Library Skills-managed symlinks are stale, broken, orphaned, or need to be checked.
+
+Run commands from the project root.
+
+Agents bundle their own skills by including an `.agents/skills` directory. More details in [Library Skills](https://library-skills.io).
+
+## First-Time Setup
+
+- Make sure project dependencies are installed first, for example with `uv sync` for Python projects or `npm install` / `bun install` for Node.js projects.
+- Run `uvx library-skills` or `npx library-skills` to discover skills bundled by the installed packages and install selected skills interactively.
+- Use `uvx library-skills --all` or `npx library-skills --all` only when all newly discovered skills should be installed without selecting individual skills.
+- Use `uvx library-skills --tool-skill` or `npx library-skills --tool-skill` to copy this Library Skills tool skill into the project so future agents know how to discover, install, update, repair, and check skills.
+
+## Commands
+
+- Run `uvx library-skills` or `npx library-skills` to discover package-provided skills, install selected new skills, and reconcile existing managed symlinks.
+- Run `uvx library-skills list` or `npx library-skills list` to inspect discovered and installed skills.
+- Run `uvx library-skills list --json` or `npx library-skills list --json` for machine-readable installed status.
+- Run `uvx library-skills scan --json` or `npx library-skills scan --json` for discovery-only automation.
+- Run `uvx library-skills --check` or `npx library-skills --check` to validate managed skill symlink state without changing files.
+- Run `uvx library-skills --yes` or `npx library-skills --yes` to repair stale managed symlinks and remove orphaned managed symlinks non-interactively.
+- Add `--claude` when `.claude/skills` should also be managed.
+- Add `--skill NAME` to install a specific discovered skill by name.
+
+## Safety
+
+- Prefer rerunning `library-skills` over editing managed symlinks manually.
+- If installed skill symlinks are broken, dependencies may not be installed yet. Try the project's normal install command first, such as `uv sync`, `npm install`, or `bun install`, then rerun `library-skills`.
+- Do not delete or overwrite hand-authored skill directories.
+- Library Skills only removes managed symlinks. It should not remove copied or hand-authored skill directories.

.agents/skills/sqlmodel

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/sqlmodel/.agents/skills/sqlmodel

.claude/skills/fastapi

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/fastapi/.agents/skills/fastapi

.claude/skills/library-skills/.library-skills.json

@@ -0,0 +1,4 @@
+{
+  "kind": "tool-skill",
+  "version": "0.0.19"
+}

.claude/skills/library-skills/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: library-skills
+description: Use Library Skills to discover, install, refresh, repair, check, and manage agent skills from installed packages.
+---
+
+# Library Skills
+
+Use this skill when a project might benefit from agent skills bundled by its installed packages, or when existing Library Skills-managed symlinks are stale, broken, orphaned, or need to be checked.
+
+Run commands from the project root.
+
+Agents bundle their own skills by including an `.agents/skills` directory. More details in [Library Skills](https://library-skills.io).
+
+## First-Time Setup
+
+- Make sure project dependencies are installed first, for example with `uv sync` for Python projects or `npm install` / `bun install` for Node.js projects.
+- Run `uvx library-skills` or `npx library-skills` to discover skills bundled by the installed packages and install selected skills interactively.
+- Use `uvx library-skills --all` or `npx library-skills --all` only when all newly discovered skills should be installed without selecting individual skills.
+- Use `uvx library-skills --tool-skill` or `npx library-skills --tool-skill` to copy this Library Skills tool skill into the project so future agents know how to discover, install, update, repair, and check skills.
+
+## Commands
+
+- Run `uvx library-skills` or `npx library-skills` to discover package-provided skills, install selected new skills, and reconcile existing managed symlinks.
+- Run `uvx library-skills list` or `npx library-skills list` to inspect discovered and installed skills.
+- Run `uvx library-skills list --json` or `npx library-skills list --json` for machine-readable installed status.
+- Run `uvx library-skills scan --json` or `npx library-skills scan --json` for discovery-only automation.
+- Run `uvx library-skills --check` or `npx library-skills --check` to validate managed skill symlink state without changing files.
+- Run `uvx library-skills --yes` or `npx library-skills --yes` to repair stale managed symlinks and remove orphaned managed symlinks non-interactively.
+- Add `--claude` when `.claude/skills` should also be managed.
+- Add `--skill NAME` to install a specific discovered skill by name.
+
+## Safety
+
+- Prefer rerunning `library-skills` over editing managed symlinks manually.
+- If installed skill symlinks are broken, dependencies may not be installed yet. Try the project's normal install command first, such as `uv sync`, `npm install`, or `bun install`, then rerun `library-skills`.
+- Do not delete or overwrite hand-authored skill directories.
+- Library Skills only removes managed symlinks. It should not remove copied or hand-authored skill directories.

.claude/skills/sqlmodel

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/sqlmodel/.agents/skills/sqlmodel

.dockerignore

@@ -0,0 +1,11 @@
+.git
+**/__pycache__
+**/.venv
+backend/htmlcov
+frontend/blob-report
+frontend/dist
+frontend/node_modules
+frontend/playwright-report
+frontend/playwright/.auth
+frontend/test-results
+node_modules

.env

@@ -0,0 +1,18 @@
+# Enable development behavior for commands that import the app directly
+FASTAPI_ENV=development
+
+PROJECT_NAME="Full Stack FastAPI Project"
+
+SECRET_KEY=changethis
+FIRST_SUPERUSER=admin@example.com
+FIRST_SUPERUSER_PASSWORD=changethis
+
+# Emails
+SMTP_HOST=localhost
+EMAILS_FROM_EMAIL=info@example.com
+SMTP_TLS=False
+SMTP_PORT=1025
+
+# Postgres
+POSTGRES_PASSWORD=changethis
+DATABASE_URL=postgresql://postgres:${POSTGRES_PASSWORD}@localhost:5432/app

.fastapicloudignore

@@ -0,0 +1,2 @@
+.env
+!backend/app/frontend/

.gitattributes

@@ -0,0 +1,2 @@
+* text=auto
+*.sh text eol=lf

.github/dependabot.yml

@@ -0,0 +1,77 @@
+version: 2
+updates:
+  # GitHub Actions
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ⬆
+    labels:
+      - "internal"
+      - "dependencies"
+      - "github_actions"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+  # Python uv
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ⬆
+    labels: [dependencies, internal]
+    groups:
+      python-packages:
+        patterns:
+          - "*"
+  # bun
+  - package-ecosystem: bun
+    directory: /
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ⬆
+    labels: [dependencies, internal]
+    ignore:
+      - dependency-name: "@hey-api/openapi-ts"
+    groups:
+      npm-packages:
+        patterns:
+          - "*"
+  # Docker
+  - package-ecosystem: docker
+    directories:
+      - /backend
+      - /frontend
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ⬆
+    groups:
+      docker:
+        patterns:
+          - "*"
+  # Docker Compose
+  - package-ecosystem: docker-compose
+    directory: /
+    schedule:
+      interval: "monthly"
+    cooldown:
+      default-days: 7
+    commit-message:
+      prefix: ⬆
+    groups:
+      docker-compose:
+        patterns:
+          - "*"

.github/latest-changes.yml

@@ -0,0 +1,12 @@
+auto-labels:
+  docs:
+    - exclude: frontend/**
+    - exclude: backend/**
+    - exclude: .github/**
+    - exclude: scripts/**
+    - '**/*.md'
+  internal:
+    - .github/**
+    - scripts/**
+    - .gitignore
+    - .pre-commit-config.yaml

.github/pr-push.yml

@@ -0,0 +1,2 @@
+workflows:
+  - .github/workflows/pre-commit.yml

.github/pr-submit.yml

@@ -0,0 +1,3 @@
+workflows:
+  - .github/workflows/bump-pre-commit-hooks.yml
+  - .github/workflows/prepare-release.yml

.github/workflows/add-to-project.yml

@@ -0,0 +1,22 @@
+name: Add to Project
+
+on:
+  pull_request_target: # zizmor: ignore[dangerous-triggers]
+  issues:
+    types:
+      - opened
+      - reopened
+
+permissions: {}
+
+jobs:
+  add-to-project:
+    name: Add to project
+    if: github.repository_owner == 'fastapi'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/add-to-project@5afcf98fcd03f1c2f92c3c83f58ae24323cc57fd # v2.0.0
+        with:
+          project-url: https://github.com/orgs/fastapi/projects/2
+          github-token: ${{ secrets.PROJECTS_TOKEN }} # zizmor: ignore[secrets-outside-env]

.github/workflows/bump-pre-commit-hooks.yml

@@ -0,0 +1,71 @@
+name: Bump pre-commit hooks
+
+on:
+  schedule:
+    - cron: "0 12 1 * *"
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  bump-pre-commit-hooks:
+    if: github.repository_owner == 'fastapi'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: ".python-version"
+      - name: Setup uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+      - name: Bump pre-commit hooks
+        run: uv run prek auto-update --freeze --cooldown-days 7
+      - name: Get PR Submit token
+        id: pr-submit
+        uses: tiangolo/pr-submit@d802fdf59bde80bc3eb8bd3259f4cbeec63de4aa # 0.0.1
+      - name: Create pull request
+        env:
+          GH_TOKEN: ${{ steps.pr-submit.outputs.token }}
+          BASE_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          if git diff --quiet; then
+            echo "No pre-commit hook updates available"
+            exit 0
+          fi
+          git config user.name "pr-submit[bot]"
+          git config user.email "pr-submit[bot]@users.noreply.github.com"
+          branch="bump-pre-commit-hooks"
+          git switch -C "$branch"
+          git add .pre-commit-config.yaml
+          git commit -m "⬆ Bump pre-commit hooks"
+          gh auth setup-git
+          git push --force origin "$branch"
+          if [ -z "$(gh pr list --head "$branch" --state open --json number --jq '.[].number')" ]; then
+            gh pr create \
+              --base "$BASE_BRANCH" \
+              --head "$branch" \
+              --title "⬆ Bump pre-commit hooks" \
+              --body "Bump pre-commit hook versions via \`prek auto-update --freeze --cooldown-days 7\`." \
+              --label internal \
+              --label dependencies \
+              --label pre-commit
+          else
+            echo "PR for \"$branch\" already open; branch updated in place."
+          fi

.github/workflows/create-draft-release.yml

@@ -0,0 +1,52 @@
+name: Create Draft Release
+
+on:
+  pull_request:
+    types:
+      - closed
+
+permissions: {}
+
+jobs:
+  create-draft-release:
+    if: github.event.pull_request.merged == true && contains(github.event.pull_request.labels.*.name, 'release')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+      pull-requests: read
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: ".python-version"
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+      - name: Extract release details
+        id: release-details
+        run: |
+          set -euo pipefail
+          version="$(uv run python scripts/prepare_release.py current-version)"
+          uv run python scripts/prepare_release.py release-notes > draft-release-notes.md
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Create draft release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ steps.release-details.outputs.version }}
+        run: |
+          set -euo pipefail
+          gh release create "$VERSION" \
+            --draft \
+            --title "$VERSION" \
+            --notes-file draft-release-notes.md \
+            --target "$(git rev-parse HEAD)"

.github/workflows/deploy-docker-compose.yml

@@ -0,0 +1,41 @@
+name: Deploy with Docker Compose
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: deploy-docker-compose
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    # Do not deploy the template repository, only projects created from it
+    if: github.repository != 'fastapi/full-stack-fastapi-template'
+    runs-on: self-hosted
+    timeout-minutes: 30
+    env:
+      DOMAIN: ${{ vars.DOMAIN }}
+      PROJECT_NAME: ${{ vars.PROJECT_NAME }}
+      SECRET_KEY: ${{ secrets.SECRET_KEY }}
+      FIRST_SUPERUSER: ${{ vars.FIRST_SUPERUSER }}
+      FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
+      SMTP_HOST: ${{ vars.SMTP_HOST }}
+      SMTP_USER: ${{ vars.SMTP_USER }}
+      SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }}
+      EMAILS_FROM_EMAIL: ${{ vars.EMAILS_FROM_EMAIL }}
+      POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
+      SENTRY_DSN: ${{ vars.SENTRY_DSN }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Build
+        run: docker compose -f compose.yml -f compose.deploy.yml build
+      - name: Prepare database
+        run: docker compose -f compose.yml -f compose.deploy.yml run --rm backend bash scripts/prestart.sh
+      - name: Start application
+        run: docker compose -f compose.yml -f compose.deploy.yml up -d

.github/workflows/deploy.yml

@@ -0,0 +1,54 @@
+name: Deploy
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - release-notes.md
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  deploy:
+    # Do not deploy the template repository, only projects created from it
+    if: github.repository != 'fastapi/full-stack-fastapi-template'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Set up Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.12
+      - name: Install frontend dependencies
+        run: bun ci
+      - name: Build frontend
+        run: bun run --filter frontend build
+        env:
+          # Override frontend/.env so the deployed frontend uses the same origin as the API
+          VITE_API_URL: ""
+      - name: Set up uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+      - name: Prepare database
+        run: uv run bash scripts/prestart.sh
+        working-directory: backend
+        env:
+          DATABASE_URL: ${{ secrets.DATABASE_URL }}
+          PROJECT_NAME: ${{ vars.PROJECT_NAME }}
+          SECRET_KEY: ${{ secrets.SECRET_KEY }}
+          FIRST_SUPERUSER: ${{ vars.FIRST_SUPERUSER }}
+          FIRST_SUPERUSER_PASSWORD: ${{ secrets.FIRST_SUPERUSER_PASSWORD }}
+      - name: Deploy to FastAPI Cloud
+        run: uv run fastapi deploy
+        env:
+          FASTAPI_CLOUD_TOKEN: ${{ secrets.FASTAPI_CLOUD_TOKEN }}
+          FASTAPI_CLOUD_APP_ID: ${{ secrets.FASTAPI_CLOUD_APP_ID }}

.github/workflows/detect-conflicts.yml

@@ -0,0 +1,22 @@
+name: "Conflict detector"
+on:
+  push:
+  pull_request_target: # zizmor: ignore[dangerous-triggers]
+    types: [synchronize]
+
+permissions: {}
+
+jobs:
+  main:
+    permissions:
+      contents: read
+      pull-requests: write
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Check if PRs have merge conflicts
+        uses: eps1lon/actions-label-merge-conflict@0273be72a0bbd58fcd71d0d6c02c209b50d1e5e1 # v3.1.0
+        with:
+          dirtyLabel: "conflicts"
+          repoToken: "${{ secrets.GITHUB_TOKEN }}"
+          commentOnDirty: "This pull request has a merge conflict that needs to be resolved."

.github/workflows/guard-dependencies.yml

@@ -0,0 +1,52 @@
+name: Guard Dependencies
+
+on:
+  pull_request_target: # zizmor: ignore[dangerous-triggers] -- This workflow only reads context.payload metadata, never checks out PR code
+    branches: [master]
+    paths:
+      - pyproject.toml
+      - uv.lock
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  check-author:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if author is org member or allowed bot
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        with:
+          script: |
+            const pr = context.payload.pull_request;
+            const author = pr.user.login;
+            const assoc = pr.author_association;
+
+            const botAllowlist = new Set(['dependabot[bot]']);
+            const orgAuthorAssociations = new Set(['MEMBER', 'OWNER']);
+
+            const allowed =
+              botAllowlist.has(author) ||
+              (assoc != null && orgAuthorAssociations.has(assoc));
+
+            if (!allowed) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.payload.pull_request.number,
+                body: `This PR modifies dependency files (\`pyproject.toml\` or \`uv.lock\`), which is restricted to members of the **${context.repo.owner}** organization on GitHub.\n\nIf you need a dependency change, please [open a discussion](https://github.com/${context.repo.owner}/${context.repo.repo}/discussions/new) describing what you need and why.\n\nClosing this PR automatically.`
+              });
+
+              await github.rest.pulls.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                pull_number: context.payload.pull_request.number,
+                state: 'closed'
+              });
+
+              core.setFailed('Dependency changes are restricted to organization members.');
+            } else {
+              console.log(`Author ${author} (author_association=${assoc}) is allowed to make dependency changes.`);
+            }

.github/workflows/issue-manager.yml

@@ -0,0 +1,34 @@
+name: Issue Manager
+
+on:
+  schedule:
+    - cron: "21 17 * * *"
+  issue_comment:
+    types:
+      - created
+  issues:
+    types:
+      - labeled
+  pull_request_target: # zizmor: ignore[dangerous-triggers]
+    types:
+      - labeled
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  issue-manager:
+    if: github.repository_owner == 'fastapi'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: tiangolo/issue-manager@dc846170c36eb62fb434b3d943b36399fe240fb5 # 0.8.1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/main.yml

@@ -1,19 +0,0 @@
-on:
-  schedule:
-  - cron: "0 0 * * *"
-
-jobs:
-  issue-manager:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: tiangolo/issue-manager@master
-      with:
-        token: ${{ secrets.GITHUB_TOKEN }}
-        config: >
-            {
-              "answered": {
-                "users": ["tiangolo"],
-                "delay": 864000,
-                "message": "Assuming the original issue was solved, it will be automatically closed now. But feel free to add more comments or create new issues."
-              }
-            }

.github/workflows/playwright.yml

@@ -0,0 +1,138 @@
+name: Playwright Tests
+
+on:
+  push:
+    branches:
+    - master
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: 'false'
+
+permissions:
+  contents: read
+
+jobs:
+  changes:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # Set job outputs to values from filter step
+    outputs:
+      changed: ${{ steps.filter.outputs.changed }}
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        fetch-depth: 2
+        persist-credentials: false
+    # For pull requests it's not necessary to checkout the code but for the main branch it is
+    - uses: dorny/paths-filter@7b450fff21473bca461d4b92ce414b9d0420d706 # v4.0.2
+      id: filter
+      with:
+        filters: |
+          changed:
+            - backend/**
+            - frontend/**
+            - .env
+            - compose*.yml
+            - .github/workflows/playwright.yml
+
+  test-playwright:
+    needs:
+      - changes
+    if: ${{ needs.changes.outputs.changed == 'true' }}
+    timeout-minutes: 15
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        shardIndex: [1, 2, 3, 4]
+        shardTotal: [4]
+      fail-fast: false
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        persist-credentials: false
+    - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+      with:
+        bun-version: 1.3.12
+    - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+      with:
+        python-version-file: .python-version
+    - name: Setup tmate session
+      uses: mxschmitt/action-tmate@35b54afac29c97fb54faba5b513f8fbd1882f113 # v3.24
+      if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }}
+      with:
+        limit-access-to-actor: true
+    - name: Install uv
+      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      with:
+        version: "latest-known"
+    - run: uv sync
+      working-directory: backend
+    - run: bun ci
+      working-directory: frontend
+    - run: bash scripts/generate-client.sh
+    - run: docker compose build
+    - run: docker compose down -v --remove-orphans
+    - run: docker compose run --rm backend bash scripts/prestart.sh
+    - name: Run Playwright tests
+      run: docker compose run --rm playwright bunx playwright test --fail-on-flaky-tests --trace=retain-on-failure --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }}
+    - run: docker compose down -v --remove-orphans
+    - name: Upload blob report to GitHub Actions Artifacts
+      if: ${{ !cancelled() }}
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: blob-report-${{ matrix.shardIndex }}
+        path: frontend/blob-report
+        include-hidden-files: true
+        retention-days: 1
+
+  merge-playwright-reports:
+    needs:
+      - test-playwright
+      - changes
+    # Merge reports after playwright-tests, even if some shards have failed
+    if: ${{ !cancelled() && needs.changes.outputs.changed == 'true' }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+    - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      with:
+        persist-credentials: false
+    - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+      with:
+        bun-version: 1.3.12
+    - name: Install dependencies
+      run: bun ci
+    - name: Download blob reports from GitHub Actions Artifacts
+      uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+      with:
+        path: frontend/all-blob-reports
+        pattern: blob-report-*
+        merge-multiple: true
+    - name: Merge into HTML Report
+      run: bunx playwright merge-reports --reporter html ./all-blob-reports
+      working-directory: frontend
+    - name: Upload HTML report
+      uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+      with:
+        name: html-report--attempt-${{ github.run_attempt }}
+        path: frontend/playwright-report
+        retention-days: 30
+        include-hidden-files: true
+
+  # https://github.com/marketplace/actions/alls-green#why
+  alls-green-playwright:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - test-playwright
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
+        with:
+          jobs: ${{ toJSON(needs) }}
+          allowed-skips: test-playwright

.github/workflows/pre-commit.yml

@@ -0,0 +1,114 @@
+name: pre-commit
+
+on:
+  pull_request:
+permissions: {}
+
+env:
+  CAN_PUSH: ${{ github.event.pull_request.head.repo.full_name == github.repository && github.actor != 'dependabot[bot]' }}
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    timeout-minutes: 5
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        name: Checkout PR for own repo
+        if: env.CAN_PUSH == 'true'
+        with:
+          # To be able to commit it needs to fetch the head of the branch, not the
+          # merge commit
+          ref: ${{ github.head_ref }}
+          # And it needs the full history to be able to compute diffs
+          fetch-depth: 0
+          persist-credentials: false
+      # pre-commit lite ci needs the default checkout configs to work
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        name: Checkout PR for fork
+        if: env.CAN_PUSH == 'false'
+        with:
+        # To be able to commit it needs the head branch of the PR, the remote one
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: 1.3.12
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - name: Setup uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+          cache-dependency-glob: |
+            requirements**.txt
+            pyproject.toml
+            uv.lock
+      - name: Install backend dependencies
+        run: uv sync --all-packages
+      - name: Install frontend dependencies
+        run: bun ci
+      - name: Run prek - pre-commit
+        id: precommit
+        run: uv run prek run --from-ref origin/${GITHUB_BASE_REF} --to-ref HEAD --show-diff-on-failure
+        continue-on-error: true
+      - name: Check for changes
+        id: changes
+        run: |
+          if [[ -n "$(git status --porcelain)" ]]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Get PR Push token
+        id: pr-push
+        if: env.CAN_PUSH == 'true' && steps.changes.outputs.changed == 'true'
+        uses: tiangolo/pr-push@ff4e51a433de4c22bbf90597e069e8247b9203d2 # 0.0.1
+      - name: Commit and push changes
+        if: env.CAN_PUSH == 'true' && steps.changes.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ steps.pr-push.outputs.token }}
+        run: |
+          git config user.name "pr-push[bot]"
+          git config user.email "pr-push[bot]@users.noreply.github.com"
+          gh auth setup-git
+          git add -A
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "🎨 Auto format and update with pre-commit"
+            git push
+          fi
+      - uses: pre-commit-ci/lite-action@5d6cc0eb514c891a40562a58a8e71576c5c7fb43 # v1.1.0
+        if: env.CAN_PUSH == 'false'
+        with:
+          msg: 🎨 Auto format and update with pre-commit
+      - name: Error out on pre-commit errors
+        if: steps.precommit.outcome == 'failure'
+        run: exit 1
+
+  # https://github.com/marketplace/actions/alls-green#why
+  pre-commit-alls-green:  # This job does nothing and is only used for the branch protection
+    if: always()
+    needs:
+      - pre-commit
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@05ac9388f0aebcb5727afa17fcccfecd6f8ec5fe # v1.2.2
+        with:
+          jobs: ${{ toJSON(needs) }}

.github/workflows/prepare-release.yml

@@ -0,0 +1,82 @@
+name: Prepare Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump:
+        description: Release bump
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+      date:
+        description: Release date in YYYY-MM-DD format. Defaults to today.
+        required: false
+        type: string
+
+permissions: {}
+
+jobs:
+  prepare-release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Dump GitHub context
+        env:
+          GITHUB_CONTEXT: ${{ toJson(github) }}
+        run: echo "$GITHUB_CONTEXT"
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: ".python-version"
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+      - name: Prepare release
+        env:
+          BUMP: ${{ inputs.bump }}
+          RELEASE_DATE: ${{ inputs.date }}
+        run: uv run python scripts/prepare_release.py prepare "$BUMP" --date "$RELEASE_DATE"
+      - name: Get release version
+        id: release-version
+        run: |
+          version="$(uv run python scripts/prepare_release.py current-version)"
+          echo "$version"
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+      - name: Get PR Submit token
+        id: pr-submit
+        uses: tiangolo/pr-submit@d802fdf59bde80bc3eb8bd3259f4cbeec63de4aa # 0.0.1
+      - name: Create release pull request
+        env:
+          BASE_BRANCH: ${{ github.event.repository.default_branch }}
+          GH_TOKEN: ${{ steps.pr-submit.outputs.token }}
+          VERSION: ${{ steps.release-version.outputs.version }}
+        run: |
+          set -euo pipefail
+          branch="release-${VERSION}-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
+          git config user.name "pr-submit[bot]"
+          git config user.email "pr-submit[bot]@users.noreply.github.com"
+          git switch -c "$branch"
+          git add release-notes.md
+          git commit -m "🔖 Release version ${VERSION}"
+          gh auth setup-git
+          git push --set-upstream origin "$branch"
+          gh label create release \
+            --description "Release preparation" \
+            --color ededed \
+            --force
+          gh pr create \
+            --base "$BASE_BRANCH" \
+            --head "$branch" \
+            --title "🔖 Release version ${VERSION}" \
+            --body "Prepare release ${VERSION}." \
+            --label release

.github/workflows/smokeshow.yml

@@ -0,0 +1,47 @@
+name: Smokeshow
+
+on:
+  workflow_run: # zizmor: ignore[dangerous-triggers]
+    workflows: [Test Backend]
+    types: [completed]
+
+permissions: {}
+
+jobs:
+  smokeshow:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read
+      contents: read
+      statuses: write
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - name: Setup uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+      - run: uv sync --all-packages --no-dev --group github-actions
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: coverage-html
+          path: backend/htmlcov
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ github.event.workflow_run.id }}
+      - run: uv run smokeshow upload backend/htmlcov
+        env:
+          SMOKESHOW_GITHUB_STATUS_DESCRIPTION: Coverage {coverage-percentage}
+          SMOKESHOW_GITHUB_COVERAGE_THRESHOLD: 90
+          SMOKESHOW_GITHUB_CONTEXT: coverage
+          SMOKESHOW_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          SMOKESHOW_GITHUB_PR_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+          SMOKESHOW_AUTH_KEY: ${{ secrets.SMOKESHOW_AUTH_KEY }} # zizmor: ignore[secrets-outside-env]

.github/workflows/test-backend.yml

@@ -0,0 +1,45 @@
+name: Test Backend
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+permissions:
+  contents: read
+
+jobs:
+  test-backend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version-file: .python-version
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          version: "latest-known"
+      - run: docker compose down -v --remove-orphans
+      - run: docker compose up -d db mailpit
+      - name: Migrate DB
+        run: uv run bash scripts/prestart.sh
+        working-directory: backend
+      - name: Run tests
+        run: uv run bash scripts/tests-start.sh "Coverage for ${{ github.sha }}"
+        working-directory: backend
+      - run: docker compose down -v --remove-orphans
+      - name: Store coverage files
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: coverage-html
+          path: backend/htmlcov
+          include-hidden-files: true
+      - name: Coverage report
+        run: uv run coverage report --fail-under=90
+        working-directory: backend

.github/workflows/test-docker-compose.yml

@@ -0,0 +1,29 @@
+name: Test Docker Compose
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+permissions:
+  contents: read
+
+jobs:
+
+  test-docker-compose:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - run: docker compose build
+      - run: docker compose down -v --remove-orphans
+      - run: docker compose run --rm backend bash scripts/prestart.sh
+      - run: docker compose up -d --wait backend adminer
+      - name: Test backend is up
+        run: curl http://localhost:8000/api/v1/utils/health-check
+      - name: Test frontend is up
+        run: curl http://localhost:8000
+      - run: docker compose down -v --remove-orphans

.github/workflows/zizmor.yml

@@ -0,0 +1,30 @@
+name: Zizmor
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  zizmor:
+    name: Run zizmor
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      actions: read
+      contents: read
+      security-events: write # Required for upload-sarif (used by zizmor-action) to upload SARIF files.
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Run zizmor
+        uses: zizmorcore/zizmor-action@6fc4b006235f201fdab3722e17240ab420d580e5 # v0.6.1
+        with:
+          advanced-security: ${{ github.repository_owner == 'fastapi' }}
+          annotations: ${{ github.repository_owner != 'fastapi' }}

.gitignore

@@ -1,4 +1,8 @@
-.vscode
-testing-project
-.mypy_cache
-poetry.lock
+.vscode/*
+!.vscode/extensions.json
+node_modules/
+backend/app/frontend/
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

.pre-commit-config.yaml

@@ -0,0 +1,82 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-yaml
+        args:
+          - --unsafe
+      - id: end-of-file-fixer
+        exclude: |
+            (?x)^(
+                frontend/src/client/.*|
+                backend/app/email-templates/.*
+            )$
+      - id: trailing-whitespace
+        exclude: ^frontend/src/client/.*
+  - repo: https://github.com/crate-ci/typos
+    rev: bee27e3a4fd1ea2111cf90ab89cd076c870fce14 # frozen: v1.48.0
+    hooks:
+      - id: typos
+        args: [--force-exclude]
+  - repo: local
+    hooks:
+      - id: local-biome-check
+        name: biome check
+        entry: npm run lint
+        language: system
+        types: [text]
+        files: ^frontend/
+
+      - id: local-ruff-check
+        name: ruff check
+        entry: uv run ruff check --force-exclude --fix --exit-non-zero-on-fix
+        require_serial: true
+        language: unsupported
+        types: [python]
+
+      - id: local-ruff-format
+        name: ruff format
+        entry: uv run ruff format --force-exclude --exit-non-zero-on-format
+        require_serial: true
+        language: unsupported
+        types: [python]
+
+      - id: local-mypy
+        name: mypy check
+        entry: uv run mypy backend/app
+        require_serial: true
+        language: unsupported
+        pass_filenames: false
+
+      - id: local-ty
+        name: ty check
+        entry: uv run ty check backend/app
+        require_serial: true
+        language: unsupported
+        pass_filenames: false
+
+      - id: generate-frontend-sdk
+        name: Generate Frontend SDK
+        entry: bash ./scripts/generate-client.sh
+        pass_filenames: false
+        language: unsupported
+        files: ^backend/app/.*\.py$|^backend/pyproject\.toml$|^uv\.lock$|^frontend/openapi-ts\.config\.ts$|^scripts/generate-client\.sh$
+
+      - id: add-release-date
+        language: unsupported
+        name: add date to latest release header
+        entry: uv run python scripts/add_latest_release_date.py
+        files: ^release-notes\.md$
+        pass_filenames: false
+
+      - id: zizmor
+        name: zizmor
+        language: python
+        entry: uv run zizmor .
+        files: ^\.github\/workflows\/
+        require_serial: true
+        pass_filenames: false

.python-version

@@ -0,0 +1 @@
+3.14

.travis.yml

@@ -1,12 +0,0 @@
-sudo: required
-
-language: python
-
-install:
-  - pip install cookiecutter
-
-services:
-  - docker
-
-script:
-- bash ./test.sh

.vscode/extensions.json

@@ -0,0 +1,14 @@
+{
+    "recommendations": [
+        "FastAPILabs.fastapi-vscode",
+        "astral-sh.ty",
+        "biomejs.biome",
+        "bradlc.vscode-tailwindcss",
+        "charliermarsh.ruff",
+        "docker.docker",
+        "github.vscode-github-actions",
+        "ms-playwright.playwright",
+        "ms-python.python",
+        "tombi-toml.tombi"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,28 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug FastAPI Project backend: Python Debugger",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "uvicorn",
+            "args": [
+                "app.main:app",
+                "--reload"
+            ],
+            "cwd": "${workspaceFolder}/backend",
+            "jinja": true,
+            "envFile": "${workspaceFolder}/.env",
+        },
+        {
+            "type": "chrome",
+            "request": "launch",
+            "name": "Debug Frontend: Launch Chrome against http://localhost:5173",
+            "url": "http://localhost:5173",
+            "webRoot": "${workspaceFolder}/frontend"
+        },
+    ]
+}

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Thank you for your interest in contributing to the Full Stack FastAPI Template! 🙇
+
+## Discussions First
+
+For **big changes** (new features, architectural changes, significant refactoring), please start by opening a [GitHub Discussion](https://github.com/fastapi/full-stack-fastapi-template/discussions) first. This allows the community and maintainers to provide feedback on the approach before you invest significant time in implementation.
+
+For small, straightforward changes, you can go directly to a Pull Request without starting a discussion first. This includes:
+
+- Typos and grammatical fixes
+- Small reproducible bug fixes
+- Fixing lint warnings or type errors
+- Minor code improvements (e.g., removing unused code)
+
+Note that PRs from non-team members are not allowed to modify `pyproject.toml` or `uv.lock`, to prevent supply chain risk.
+If you would like to add a new dependency, create a new [Discussion](https://github.com/fastapi/full-stack-fastapi-template/discussions) to explain why.
+
+## Developing
+
+For detailed instructions on setting up your development environment, running the stack, linting, pre-commit hooks, and more, see the [Development Guide](development.md).
+
+## Pull Requests
+
+When submitting a pull request:
+
+1. Make sure all tests pass before submitting.
+2. Keep PRs focused on a single change.
+3. Update tests if you're changing functionality.
+4. Reference any related issues in your PR description.
+
+## Automated Code and AI
+
+You are encouraged to use all the tools you want to do your work and contribute as efficiently as possible, this includes AI (LLM) tools, etc. Nevertheless, contributions should have meaningful human intervention, judgement, context, etc.
+
+If the **human effort** put in a PR, e.g. writing LLM prompts, is **less** than the **effort we would need to put** to **review it**, please **don't** submit the PR.
+
+Think of it this way: we can already write LLM prompts or run automated tools ourselves, and that would be faster than reviewing external PRs.
+
+### Closing Automated and AI PRs
+
+If we see PRs that seem AI generated or automated in similar ways, we'll flag them and close them.
+
+The same applies to comments and descriptions, please don't copy paste the content generated by an LLM.
+
+### Human Effort Denial of Service
+
+Using automated tools and AI to submit PRs or comments that we have to carefully review and handle would be the equivalent of a [Denial-of-service attack](https://en.wikipedia.org/wiki/Denial-of-service_attack) on our human effort.
+
+It would be very little effort from the person submitting the PR (an LLM prompt) that generates a large amount of effort on our side (carefully reviewing code).
+
+Please don't do that.
+
+We'll need to block accounts that spam us with repeated automated PRs or comments.
+
+### Use Tools Wisely
+
+As Uncle Ben said:
+
+> With great ~~power~~ **tools** comes great responsibility.
+
+Avoid inadvertently doing harm.
+
+You have amazing tools at hand, use them wisely to help effectively.
+
+## Questions?
+
+If you have questions about contributing, feel free to open a [GitHub Discussion](https://github.com/fastapi/full-stack-fastapi-template/discussions).

README.md

@@ -1,250 +1,88 @@
-# Full Stack FastAPI and PostgreSQL - Base Project Generator
+# Full Stack FastAPI Template
 
-[![Build Status](https://travis-ci.org/tiangolo/full-stack-fastapi-postgresql.svg?branch=master)](https://travis-ci.org/tiangolo/full-stack-fastapi-postgresql)
+[![Test Docker Compose](../../actions/workflows/test-docker-compose.yml/badge.svg)](../../actions/workflows/test-docker-compose.yml)
+[![Test Backend](../../actions/workflows/test-backend.yml/badge.svg)](../../actions/workflows/test-backend.yml)
 
-Generate a backend and frontend stack using Python, including interactive API documentation.
-
-### Interactive API documentation
-
-[![API docs](img/docs.png)](https://github.com/tiangolo/full-stack-fastapi-postgresql)
-
-
-### Alternative API documentation
-
-[![API docs](img/redoc.png)](https://github.com/tiangolo/full-stack-fastapi-postgresql)
+## Technology Stack and Features
 
+- ⚡ [**FastAPI**](https://fastapi.tiangolo.com) for the Python backend API.
+  - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) for the Python SQL database interactions (ORM).
+  - 🔍 [Pydantic](https://docs.pydantic.dev), used by FastAPI, for the data validation and settings management.
+  - 💾 [PostgreSQL](https://www.postgresql.org) as the SQL database.
+- 🚀 [React](https://react.dev) for the frontend.
+  - 🧩 Built into the backend application and served by FastAPI on the same domain as the API.
+  - 💃 Using TypeScript, hooks, [Vite](https://vitejs.dev), and other parts of a modern frontend stack.
+  - 🎨 [Tailwind CSS](https://tailwindcss.com) and [shadcn/ui](https://ui.shadcn.com) for the frontend components.
+  - 🤖 An automatically generated frontend client.
+  - 🧪 [Playwright](https://playwright.dev) for end-to-end testing.
+  - 🦇 Dark mode support.
+- ☁️ [FastAPI Cloud](https://fastapicloud.com) for deployment.
+- 🐋 [Docker Compose](https://www.docker.com) for local services and self-hosted deployment.
+  - 📞 [Traefik](https://traefik.io) as a reverse proxy with automatic HTTPS.
+- 🔒 Secure password hashing by default.
+- 🔑 JWT (JSON Web Token) authentication.
+- 📫 Email-based password recovery.
+- ✉️ [React Email](https://react.email) for email templates.
+- 📬 [Mailpit](https://mailpit.axllent.org) for local email testing during development.
+- ✅ Tests with [Pytest](https://pytest.org).
+- 🏭 CI (continuous integration) and CD (continuous deployment) based on GitHub Actions.
 
 ### Dashboard Login
 
-[![API docs](img/login.png)](https://github.com/tiangolo/full-stack-fastapi-postgresql)
+![Dashboard login screenshot](img/login.png)
 
+### Dashboard - Admin
 
-### Dashboard - Create User
+![Admin dashboard screenshot](img/dashboard.png)
 
-[![API docs](img/dashboard.png)](https://github.com/tiangolo/full-stack-fastapi-postgresql)
+### Dashboard - Items
 
-## Features
+![Items dashboard screenshot](img/dashboard-items.png)
 
-* Full **Docker** integration (Docker based).
-* Docker Swarm Mode deployment.
-* **Docker Compose** integration and optimization for local development.
-* **Production ready** Python web server using Uvicorn and Gunicorn.
-* Python <a href="https://github.com/tiangolo/fastapi" class="external-link" target="_blank">**FastAPI**</a> backend:
-    * **Fast**: Very high performance, on par with **NodeJS** and **Go** (thanks to Starlette and Pydantic).
-    * **Intuitive**: Great editor support. <abbr title="also known as auto-complete, autocompletion, IntelliSense">Completion</abbr> everywhere. Less time debugging.
-    * **Easy**: Designed to be easy to use and learn. Less time reading docs.
-    * **Short**: Minimize code duplication. Multiple features from each parameter declaration.
-    * **Robust**: Get production-ready code. With automatic interactive documentation.
-    * **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" class="external-link" target="_blank">OpenAPI</a> and <a href="http://json-schema.org/" class="external-link" target="_blank">JSON Schema</a>.
-    * <a href="https://fastapi.tiangolo.com/features/" class="external-link" target="_blank">**Many other features**</a> including automatic validation, serialization, interactive documentation, authentication with OAuth2 JWT tokens, etc.
-* **Secure password** hashing by default.
-* **JWT token** authentication.
-* **SQLAlchemy** models (independent of Flask extensions, so they can be used with Celery workers directly).
-* Basic starting models for users (modify and remove as you need).
-* **Alembic** migrations.
-* **CORS** (Cross Origin Resource Sharing).
-* **Celery** worker that can import and use models and code from the rest of the backend selectively.
-* REST backend tests based on **Pytest**, integrated with Docker, so you can test the full API interaction, independent on the database. As it runs in Docker, it can build a new data store from scratch each time (so you can use ElasticSearch, MongoDB, CouchDB, or whatever you want, and just test that the API works).
-* Easy Python integration with **Jupyter Kernels** for remote or in-Docker development with extensions like Atom Hydrogen or Visual Studio Code Jupyter.
-* **Vue** frontend:
-    * Generated with Vue CLI.
-    * **JWT Authentication** handling.
-    * Login view.
-    * After login, main dashboard view.
-    * Main dashboard with user creation and edition.
-    * Self user edition.
-    * **Vuex**.
-    * **Vue-router**.
-    * **Vuetify** for beautiful material design components.
-    * **TypeScript**.
-    * Docker server based on **Nginx** (configured to play nicely with Vue-router).
-    * Docker multi-stage building, so you don't need to save or commit compiled code.
-    * Frontend tests ran at build time (can be disabled too).
-    * Made as modular as possible, so it works out of the box, but you can re-generate with Vue CLI or create it as you need, and re-use what you want.
-* **PGAdmin** for PostgreSQL database, you can modify it to use PHPMyAdmin and MySQL easily.
-* **Flower** for Celery jobs monitoring.
-* Load balancing between frontend and backend with **Traefik**, so you can have both under the same domain, separated by path, but served by different containers.
-* Traefik integration, including Let's Encrypt **HTTPS** certificates automatic generation.
-* GitLab **CI** (continuous integration), including frontend and backend testing.
+### Dashboard - Dark Mode
 
-## How to use it
+![Dark mode dashboard screenshot](img/dashboard-dark.png)
 
-Go to the directory where you want to create your project and run:
+### React Email Templates
 
-```bash
-pip install cookiecutter
-cookiecutter https://github.com/tiangolo/full-stack-fastapi-postgresql
-```
+![Email templates screenshot](img/react-email.png)
 
-### Generate passwords
+### Mailpit - Local Email Testing
 
-You will be asked to provide passwords and secret keys for several components. Open another terminal and run:
+![Mailpit screenshot](img/mailpit.png)
 
-```bash
-openssl rand -hex 32
-# Outputs something like: 99d3b1f01aa639e4a76f4fc281fc834747a543720ba4c8a8648ba755aef9be7f
-```
+### Interactive API Documentation
 
-Copy the contents and use that as password / secret key. And run that again to generate another secure key.
+![API docs](img/docs.png)
 
+## How to Use It
 
-### Input variables
+Click the **Use this template** button at the top of this page to create a new repository.
 
-The generator (cookiecutter) will ask you for some data, you might want to have at hand before generating the project.
+## Backend Development
 
-The input variables, with their default values (some auto generated) are:
+Backend docs: [backend/README.md](./backend/README.md).
 
-* `project_name`: The name of the project
-* `project_slug`: The development friendly name of the project. By default, based on the project name
-* `domain_main`: The domain in where to deploy the project for production (from the branch `production`), used by the load balancer, backend, etc. By default, based on the project slug.
-* `domain_staging`: The domain in where to deploy while staging (before production) (from the branch `master`). By default, based on the main domain.
+## Frontend Development
 
-* `docker_swarm_stack_name_main`: The name of the stack while deploying to Docker in Swarm mode for production. By default, based on the domain.
-* `docker_swarm_stack_name_staging`: The name of the stack while deploying to Docker in Swarm mode for staging. By default, based on the domain.
+Frontend docs: [frontend/README.md](./frontend/README.md).
 
-* `secret_key`: Backend server secret key. Use the method above to generate it.
-* `first_superuser`: The first superuser generated, with it you will be able to create more users, etc. By default, based on the domain.
-* `first_superuser_password`: First superuser password. Use the method above to generate it.
-* `backend_cors_origins`: Origins (domains, more or less) that are enabled for CORS (Cross Origin Resource Sharing). This allows a frontend in one domain (e.g. `https://dashboard.example.com`) to communicate with this backend, that could be living in another domain (e.g. `https://api.example.com`). It can also be used to allow your local frontend (with a custom `hosts` domain mapping, as described in the project's `README.md`) that could be living in `http://dev.example.com:8080` to communicate with the backend at `https://stag.example.com`. Notice the `http` vs `https` and the `dev.` prefix for local development vs the "staging" `stag.` prefix. By default, it includes origins for production, staging and development, with ports commonly used during local development by several popular frontend frameworks (Vue with `:8080`, React, Angular).
-* `smtp_port`: Port to use to send emails via SMTP. By default `587`.
-* `smtp_host`: Host to use to send emails, it would be given by your email provider, like Mailgun, Sparkpost, etc.
-* `smtp_user`: The user to use in the SMTP connection. The value will be given by your email provider.
-* `smtp_password`: The password to be used in the SMTP connection. The value will be given by the email provider.
-* `smtp_emails_from_email`: The email account to use as the sender in the notification emails, it would be something like `info@your-custom-domain.com`.
- 
-* `postgres_password`: Postgres database password. Use the method above to generate it. (You could easily modify it to use MySQL, MariaDB, etc).
-* `pgadmin_default_user`: PGAdmin default user, to log-in to the PGAdmin interface.
-* `pgadmin_default_user_password`: PGAdmin default user password. Generate it with the method above.
- 
-* `traefik_constraint_tag`: The tag to be used by the internal Traefik load balancer (for example, to divide requests between backend and frontend) for production. Used to separate this stack from any other stack you might have. This should identify each stack in each environment (production, staging, etc).
-* `traefik_constraint_tag_staging`: The Traefik tag to be used while on staging. 
-* `traefik_public_constraint_tag`: The tag that should be used by stack services that should communicate with the public.
+## Deployment
 
-* `flower_auth`: Basic HTTP authentication for flower, in the form`user:password`. By default: "`root:changethis`".
+FastAPI Cloud deployment: [deployment.md](./deployment.md).
 
-* `sentry_dsn`: Key URL (DSN) of Sentry, for live error reporting. If you are not using it yet, you should, is open source. E.g.: `https://1234abcd:5678ef@sentry.example.com/30`.
+Self-hosted deployment with Docker Compose: [deployment-docker-compose.md](./deployment-docker-compose.md).
 
-* `docker_image_prefix`: Prefix to use for Docker image names. If you are using GitLab Docker registry it would be based on your code repository. E.g.: `git.example.com/development-team/my-awesome-project/`.
-* `docker_image_backend`: Docker image name for the backend. By default, it will be based on your Docker image prefix, e.g.: `git.example.com/development-team/my-awesome-project/backend`. And depending on your environment, a different tag will be appended ( `prod`, `stag`, `branch` ). So, the final image names used will be like: `git.example.com/development-team/my-awesome-project/backend:prod`.
-* `docker_image_celeryworker`: Docker image for the celery worker. By default, based on your Docker image prefix.
-* `docker_image_frontend`: Docker image for the frontend. By default, based on your Docker image prefix.
+## Development
 
-## How to deploy
+General development docs: [development.md](./development.md).
 
-This stack can be adjusted and used with several deployment options that are compatible with Docker Compose, but it is designed to be used in a cluster controlled with pure Docker in Swarm Mode with a Traefik main load balancer proxy handling automatic HTTPS certificates, using the ideas from <a href="https://dockerswarm.rocks" target="_blank">DockerSwarm.rocks</a>.
-
-Please refer to <a href="https://dockerswarm.rocks" target="_blank">DockerSwarm.rocks</a> to see how to deploy such a cluster in 20 minutes.
-
-## More details
-
-After using this generator, your new project (the directory created) will contain an extensive `README.md` with instructions for development, deployment, etc. You can pre-read [the project `README.md` template here too](./{{cookiecutter.project_slug}}/README.md).
-
-## Sibling project generators
-
-* Based on Couchbase: [https://github.com/tiangolo/full-stack-fastapi-couchbase](https://github.com/tiangolo/full-stack-fastapi-couchbase).
+This includes the local FastAPI and Vite workflow, Docker Compose services, `.env` configuration, and more.
 
 ## Release Notes
 
-### Latest Changes
-
-### 0.5.0
-
-* Make the Traefik public network a fixed default of `traefik-public` as done in DockerSwarm.rocks, to simplify development and iteration of the project generator. PR [#150](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/150).
-* Update to PostgreSQL 12. PR [#148](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/148). by [@RCheese](https://github.com/RCheese).
-* Use Poetry for package management. Initial PR [#144](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/144) by [@RCheese](https://github.com/RCheese).
-* Fix Windows line endings for shell scripts after project generation with Cookiecutter hooks. PR [#149](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/149).
-* Upgrade Vue CLI to version 4. PR [#120](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/120) by [@br3ndonland](https://github.com/br3ndonland).
-* Remove duplicate `login` tag. PR [#135](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/135) by [@Nonameentered](https://github.com/Nonameentered).
-* Fix showing email in dashboard when there's no user's full name. PR [#129](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/129) by [@rlonka](https://github.com/rlonka).
-* Format code with Black and Flake8. PR [#121](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/121) by [@br3ndonland](https://github.com/br3ndonland).
-* Simplify SQLAlchemy Base class. PR [#117](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/117) by [@airibarne](https://github.com/airibarne).
-* Update CRUD utils for users, handling password hashing. PR [#106](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/106) by [@mocsar](https://github.com/mocsar).
-* Use `.` instead of `source` for interoperability. PR [#98](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/98) by [@gucharbon](https://github.com/gucharbon).
-* Use Pydantic's `BaseSettings` for settings/configs and env vars. PR [#87](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/87) by [@StephenBrown2](https://github.com/StephenBrown2).
-* Remove `package-lock.json` to let everyone lock their own versions (depending on OS, etc).
-* Simplify Traefik service labels PR [#139](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/139).
-* Add email validation. PR [#40](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/40) by [@kedod](https://github.com/kedod).
-* Fix typo in README. PR [#83](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/83) by [@ashears](https://github.com/ashears).
-* Fix typo in README. PR [#80](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/80) by [@abjoker](https://github.com/abjoker).
-* Fix function name `read_item` and response code. PR [#74](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/74) by [@jcaguirre89](https://github.com/jcaguirre89).
-* Fix typo in comment. PR [#70](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/70) by [@daniel-butler](https://github.com/daniel-butler).
-* Fix Flower Docker configuration. PR [#37](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/37) by [@dmontagu](https://github.com/dmontagu).
-* Add new CRUD utils based on DB and Pydantic models. Initial PR [#23](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/23) by [@ebreton](https://github.com/ebreton).
-* Add normal user testing Pytest fixture. PR [#20](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/20) by [@ebreton](https://github.com/ebreton).
-
-### 0.4.0
-
-* Fix security on resetting a password. Receive token as body, not query. PR [#34](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/34).
-
-* Fix security on resetting a password. Receive it as body, not query. PR [#33](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/33) by [@dmontagu](https://github.com/dmontagu).
-
-* Fix SQLAlchemy class lookup on initialization. PR [#29](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/29) by [@ebreton](https://github.com/ebreton).
-
-* Fix SQLAlchemy operation errors on database restart. PR [#32](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/32) by [@ebreton](https://github.com/ebreton).
-
-* Fix locations of scripts in generated README. PR [#19](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/19) by [@ebreton](https://github.com/ebreton).
-
-* Forward arguments from script to `pytest` inside container. PR [#17](https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/17) by [@ebreton](https://github.com/ebreton).
-
-* Update development scripts.
-
-* Read Alembic configs from env vars. PR <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/9" target="_blank">#9</a> by <a href="https://github.com/ebreton" target="_blank">@ebreton</a>.
-
-* Create DB Item objects from all Pydantic model's fields.
-
-* Update Jupyter Lab installation and util script/environment variable for local development.
-
-### 0.3.0
-
-* PR <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/14" target="_blank">#14</a>:
-    * Update CRUD utils to use types better.
-    * Simplify Pydantic model names, from `UserInCreate` to `UserCreate`, etc.
-    * Upgrade packages.
-    * Add new generic "Items" models, crud utils, endpoints, and tests. To facilitate re-using them to create new functionality. As they are simple and generic (not like Users), it's easier to copy-paste and adapt them to each use case.
-    * Update endpoints/*path operations* to simplify code and use new utilities, prefix and tags in `include_router`.
-    * Update testing utils.
-    * Update linting rules, relax vulture to reduce false positives.
-    * Update migrations to include new Items.
-    * Update project README.md with tips about how to start with backend.
-
-* Upgrade Python to 3.7 as Celery is now compatible too. PR <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/10" target="_blank">#10</a> by <a href="https://github.com/ebreton" target="_blank">@ebreton</a>.
-
-### 0.2.2
-
-* Fix frontend hijacking /docs in development. Using latest https://github.com/tiangolo/node-frontend with custom Nginx configs in frontend. <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/6" target="_blank">PR #6</a>.
-
-### 0.2.1
-
-* Fix documentation for *path operation* to get user by ID. <a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/4" target="_blank">PR #4</a> by <a href="https://github.com/mpclarkson" target="_blank">@mpclarkson</a> in FastAPI.
-
-* Set `/start-reload.sh` as a command override for development by default.
-
-* Update generated README.
-
-### 0.2.0
-
-**<a href="https://github.com/tiangolo/full-stack-fastapi-postgresql/pull/2" target="_blank">PR #2</a>**:
-
-* Simplify and update backend `Dockerfile`s.
-* Refactor and simplify backend code, improve naming, imports, modules and "namespaces".
-* Improve and simplify Vuex integration with TypeScript accessors.
-* Standardize frontend components layout, buttons order, etc.
-* Add local development scripts (to develop this project generator itself).
-* Add logs to startup modules to detect errors early.
-* Improve FastAPI dependency utilities, to simplify and reduce code (to require a superuser).
-
-### 0.1.2
-
-* Fix path operation to update self-user, set parameters as body payload.
-
-### 0.1.1
-
-Several bug fixes since initial publication, including:
-
-* Order of path operations for users.
-* Frontend sending login data in the correct format.
-* Add https://localhost variants to CORS.
+Check the file [release-notes.md](./release-notes.md).
 
 ## License
 
-This project is licensed under the terms of the MIT license.
+The Full Stack FastAPI Template is licensed under the terms of the MIT license.

backend/.dockerignore

@@ -0,0 +1,8 @@
+# Python
+__pycache__
+app.egg-info
+*.pyc
+.mypy_cache
+.coverage
+htmlcov
+.venv

backend/.gitignore

@@ -0,0 +1,8 @@
+__pycache__
+app.egg-info
+*.pyc
+.mypy_cache
+.coverage
+htmlcov
+.cache
+.venv

backend/Dockerfile

@@ -0,0 +1,65 @@
+FROM oven/bun:1 AS frontend-build
+
+WORKDIR /app
+
+COPY package.json bun.lock /app/
+COPY frontend/package.json /app/frontend/
+
+WORKDIR /app/frontend
+
+RUN bun install
+
+COPY ./frontend /app/frontend
+
+ARG VITE_API_URL=
+
+RUN bun run build
+
+
+FROM python:3.14
+
+ENV PYTHONUNBUFFERED=1
+
+# Install uv
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#installing-uv
+COPY --from=ghcr.io/astral-sh/uv:0.9.26 /uv /uvx /bin/
+
+# Compile bytecode
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#compiling-bytecode
+ENV UV_COMPILE_BYTECODE=1
+
+# uv Cache
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#caching
+ENV UV_LINK_MODE=copy
+
+WORKDIR /app/
+
+# Place executables in the environment at the front of the path
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#using-the-environment
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Install dependencies
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --no-install-workspace --package app
+
+COPY ./backend/scripts /app/backend/scripts
+
+COPY ./backend/pyproject.toml ./backend/alembic.ini /app/backend/
+
+COPY ./backend/app /app/backend/app
+
+COPY --from=frontend-build /app/backend/app/frontend /app/backend/app/frontend
+
+# Sync the project
+# Ref: https://docs.astral.sh/uv/guides/integration/docker/#intermediate-layers
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --frozen --package app
+
+WORKDIR /app/backend/
+
+CMD ["fastapi", "run", "--workers", "4"]

backend/README.md

@@ -0,0 +1,145 @@
+# FastAPI Project - Backend
+
+## Requirements
+
+* [Docker](https://www.docker.com/).
+* [uv](https://docs.astral.sh/uv/) for Python package and environment management.
+
+## Local Development
+
+Run the backend locally and connect it to PostgreSQL in Docker Compose.
+
+From the project root, start PostgreSQL and Mailpit:
+
+```console
+$ docker compose up -d db mailpit
+```
+
+Then, from `./backend/`, install the dependencies, prepare the database, and start the development server:
+
+```console
+$ uv sync
+$ uv run bash scripts/prestart.sh
+$ uv run fastapi dev
+```
+
+The API is available at `http://localhost:8000`, with automatic interactive docs at `http://localhost:8000/docs`.
+
+## General Workflow
+
+Run backend commands from `./backend/` with `uv run`. Make sure your editor uses the Python interpreter at `.venv/bin/python` in the project root.
+
+Modify or add SQLModel models for data and SQL tables in `./backend/app/models.py`, API endpoints in `./backend/app/api/`, CRUD (Create, Read, Update, Delete) utils in `./backend/app/crud.py`.
+
+## VS Code
+
+There are already configurations in place to run the backend through the VS Code debugger, so that you can use breakpoints, pause and explore variables, etc.
+
+The setup is also already configured so you can run the tests through the VS Code Python tests tab.
+
+## Full Stack with Docker Compose
+
+To run the backend and built frontend in Docker Compose:
+
+```console
+$ docker compose run --rm backend bash scripts/prestart.sh
+$ docker compose watch
+```
+
+The application is available at `http://localhost:8000`.
+
+### Docker Compose Override
+
+The `compose.override.yml` file contains local settings for published ports, source synchronization, automatic image rebuilds, and backend reloads. Docker Compose applies it automatically when you run `docker compose` without an explicit file list.
+
+To open a shell in the backend container:
+
+```console
+$ docker compose exec backend bash
+```
+
+## Backend Tests
+
+To test the backend from the `backend` directory, run:
+
+```console
+$ uv run bash scripts/test.sh
+```
+
+The tests run with Pytest. Modify existing tests or add new ones in `./backend/tests/`.
+
+If you use GitHub Actions, the tests will run automatically.
+
+### Test a Running Stack
+
+If your stack is already up and you just want to run the tests, you can use:
+
+```bash
+docker compose exec backend bash scripts/tests-start.sh
+```
+
+The `/app/backend/scripts/tests-start.sh` script calls `pytest` after making sure that the rest of the stack is running. If you need to pass extra arguments to `pytest`, you can pass them to that command and they will be forwarded.
+
+For example, to stop on first error:
+
+```bash
+docker compose exec backend bash scripts/tests-start.sh -x
+```
+
+### Test Coverage
+
+When the tests run, they generate `htmlcov/index.html`. Open it in your browser to inspect the test coverage.
+
+## Migrations
+
+Make sure you create a revision of your models and upgrade the database with that revision every time you change them. From the `backend` directory, use `uv` to run Alembic against the PostgreSQL container:
+
+* Alembic is already configured to import your SQLModel models from `./backend/app/models.py`.
+
+* After changing a model (for example, adding a column), create a revision:
+
+```console
+$ uv run alembic revision --autogenerate -m "Add column last_name to User model"
+```
+
+* Commit to the git repository the files generated in the alembic directory.
+
+* After creating the revision, run the migration in the database (this is what will actually change the database):
+
+```console
+$ uv run alembic upgrade head
+```
+
+If you don't want to use migrations at all, uncomment the lines in the file at `./backend/app/core/db.py` that end in:
+
+```python
+SQLModel.metadata.create_all(engine)
+```
+
+and comment the line in the file `scripts/prestart.sh` that contains:
+
+```console
+$ alembic upgrade head
+```
+
+If you don't want to start with the default models and want to remove them / modify them, from the beginning, without having any previous revision, you can remove the revision files (`.py` Python files) under `./backend/app/alembic/versions/`. And then create a first migration as described above.
+
+## Email Templates
+
+The email templates are written with [React Email](https://react.email) in `./packages/react-email/`. The `emails` directory holds one component per email and the `ui` directory holds the shared components (layout, heading, button, link, callout).
+
+The rendered HTML in `./backend/app/email-templates/` is generated from those components. It is what the application sends and should not be edited by hand.
+
+To preview the emails while editing them, start the dev server from the root of the project:
+
+```console
+$ bun run email:dev
+```
+
+Values coming from the backend are declared as Jinja placeholders in the component props, for example `username = "{{ username }}"`. The context for each email is built in `generate_*_email()` in `./backend/app/utils.py`, so a new placeholder needs to be added there too.
+
+Once you are done, regenerate the templates used by the application:
+
+```console
+$ bun run email:export
+```

backend/alembic.ini

@@ -2,7 +2,7 @@
 
 [alembic]
 # path to migration scripts
-script_location = alembic
+script_location = app/alembic
 
 # template used to generate migration files
 # file_template = %%(rev)s_%%(slug)s

backend/app/alembic/README

@@ -0,0 +1 @@
+Generic single-database configuration.

backend/app/alembic/env.py

@@ -1,10 +1,8 @@
-from __future__ import with_statement
-
 import os
+from logging.config import fileConfig
 
 from alembic import context
 from sqlalchemy import engine_from_config, pool
-from logging.config import fileConfig
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.
@@ -12,6 +10,7 @@ config = context.config
 
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
+assert config.config_file_name is not None
 fileConfig(config.config_file_name)
 
 # add your model's MetaData object here
@@ -20,9 +19,10 @@ fileConfig(config.config_file_name)
 # target_metadata = mymodel.Base.metadata
 # target_metadata = None
 
-from app.db.base import Base  # noqa
+from app.models import SQLModel  # noqa
+from app.core.config import settings # noqa
 
-target_metadata = Base.metadata
+target_metadata = SQLModel.metadata
 
 # other values from the config, defined by the needs of env.py,
 # can be acquired:
@@ -31,11 +31,7 @@ target_metadata = Base.metadata
 
 
 def get_url():
-    user = os.getenv("POSTGRES_USER", "postgres")
-    password = os.getenv("POSTGRES_PASSWORD", "")
-    server = os.getenv("POSTGRES_SERVER", "db")
-    db = os.getenv("POSTGRES_DB", "app")
-    return f"postgresql://{user}:{password}@{server}/{db}"
+    return str(settings.DATABASE_URL)
 
 
 def run_migrations_offline():
@@ -67,9 +63,12 @@ def run_migrations_online():
 
     """
     configuration = config.get_section(config.config_ini_section)
+    assert configuration is not None
     configuration["sqlalchemy.url"] = get_url()
     connectable = engine_from_config(
-        configuration, prefix="sqlalchemy.", poolclass=pool.NullPool,
+        configuration,
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
     )
 
     with connectable.connect() as connection:

backend/app/alembic/script.py.mako

@@ -7,6 +7,7 @@ Create Date: ${create_date}
 """
 from alembic import op
 import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
 ${imports if imports else ""}
 
 # revision identifiers, used by Alembic.

backend/app/alembic/versions/1a31ce608336_add_cascade_delete_relationships.py

@@ -0,0 +1,37 @@
+"""Add cascade delete relationships
+
+Revision ID: 1a31ce608336
+Revises: d98dd8ec85a3
+Create Date: 2024-07-31 22:24:34.447891
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+
+
+# revision identifiers, used by Alembic.
+revision = '1a31ce608336'
+down_revision = 'd98dd8ec85a3'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.alter_column('item', 'owner_id',
+               existing_type=sa.UUID(),
+               nullable=False)
+    op.drop_constraint('item_owner_id_fkey', 'item', type_='foreignkey')
+    op.create_foreign_key(None, 'item', 'user', ['owner_id'], ['id'], ondelete='CASCADE')
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_constraint('item_owner_id_fkey', 'item', type_='foreignkey')
+    op.create_foreign_key('item_owner_id_fkey', 'item', 'user', ['owner_id'], ['id'])
+    op.alter_column('item', 'owner_id',
+               existing_type=sa.UUID(),
+               nullable=True)
+    # ### end Alembic commands ###

backend/app/alembic/versions/9c0a54914c78_add_max_length_for_string_varchar_.py

@@ -0,0 +1,69 @@
+"""Add max length for string(varchar) fields in User and Items models
+
+Revision ID: 9c0a54914c78
+Revises: e2412789c190
+Create Date: 2024-06-17 14:42:44.639457
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+
+
+# revision identifiers, used by Alembic.
+revision = '9c0a54914c78'
+down_revision = 'e2412789c190'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # Adjust the length of the email field in the User table
+    op.alter_column('user', 'email',
+               existing_type=sa.String(),
+               type_=sa.String(length=255),
+               existing_nullable=False)
+
+    # Adjust the length of the full_name field in the User table
+    op.alter_column('user', 'full_name',
+               existing_type=sa.String(),
+               type_=sa.String(length=255),
+               existing_nullable=True)
+
+    # Adjust the length of the title field in the Item table
+    op.alter_column('item', 'title',
+               existing_type=sa.String(),
+               type_=sa.String(length=255),
+               existing_nullable=False)
+
+    # Adjust the length of the description field in the Item table
+    op.alter_column('item', 'description',
+               existing_type=sa.String(),
+               type_=sa.String(length=255),
+               existing_nullable=True)
+
+
+def downgrade():
+    # Revert the length of the email field in the User table
+    op.alter_column('user', 'email',
+               existing_type=sa.String(length=255),
+               type_=sa.String(),
+               existing_nullable=False)
+
+    # Revert the length of the full_name field in the User table
+    op.alter_column('user', 'full_name',
+               existing_type=sa.String(length=255),
+               type_=sa.String(),
+               existing_nullable=True)
+
+    # Revert the length of the title field in the Item table
+    op.alter_column('item', 'title',
+               existing_type=sa.String(length=255),
+               type_=sa.String(),
+               existing_nullable=False)
+
+    # Revert the length of the description field in the Item table
+    op.alter_column('item', 'description',
+               existing_type=sa.String(length=255),
+               type_=sa.String(),
+               existing_nullable=True)

backend/app/alembic/versions/d98dd8ec85a3_edit_replace_id_integers_in_all_models_.py

@@ -0,0 +1,90 @@
+"""Edit replace id integers in all models to use UUID instead
+
+Revision ID: d98dd8ec85a3
+Revises: 9c0a54914c78
+Create Date: 2024-07-19 04:08:04.000976
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = 'd98dd8ec85a3'
+down_revision = '9c0a54914c78'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # Ensure uuid-ossp extension is available
+    op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
+
+    # Create a new UUID column with a default UUID value
+    op.add_column('user', sa.Column('new_id', postgresql.UUID(as_uuid=True), default=sa.text('uuid_generate_v4()')))
+    op.add_column('item', sa.Column('new_id', postgresql.UUID(as_uuid=True), default=sa.text('uuid_generate_v4()')))
+    op.add_column('item', sa.Column('new_owner_id', postgresql.UUID(as_uuid=True), nullable=True))
+
+    # Populate the new columns with UUIDs
+    op.execute('UPDATE "user" SET new_id = uuid_generate_v4()')
+    op.execute('UPDATE item SET new_id = uuid_generate_v4()')
+    op.execute('UPDATE item SET new_owner_id = (SELECT new_id FROM "user" WHERE "user".id = item.owner_id)')
+
+    # Set the new_id as not nullable
+    op.alter_column('user', 'new_id', nullable=False)
+    op.alter_column('item', 'new_id', nullable=False)
+
+    # Drop old columns and rename new columns
+    op.drop_constraint('item_owner_id_fkey', 'item', type_='foreignkey')
+    op.drop_column('item', 'owner_id')
+    op.alter_column('item', 'new_owner_id', new_column_name='owner_id')
+
+    op.drop_column('user', 'id')
+    op.alter_column('user', 'new_id', new_column_name='id')
+
+    op.drop_column('item', 'id')
+    op.alter_column('item', 'new_id', new_column_name='id')
+
+    # Create primary key constraint
+    op.create_primary_key('user_pkey', 'user', ['id'])
+    op.create_primary_key('item_pkey', 'item', ['id'])
+
+    # Recreate foreign key constraint
+    op.create_foreign_key('item_owner_id_fkey', 'item', 'user', ['owner_id'], ['id'])
+
+def downgrade():
+    # Reverse the upgrade process
+    op.add_column('user', sa.Column('old_id', sa.Integer, autoincrement=True))
+    op.add_column('item', sa.Column('old_id', sa.Integer, autoincrement=True))
+    op.add_column('item', sa.Column('old_owner_id', sa.Integer, nullable=True))
+
+    # Populate the old columns with default values
+    # Generate sequences for the integer IDs if not exist
+    op.execute('CREATE SEQUENCE IF NOT EXISTS user_id_seq AS INTEGER OWNED BY "user".old_id')
+    op.execute('CREATE SEQUENCE IF NOT EXISTS item_id_seq AS INTEGER OWNED BY item.old_id')
+
+    op.execute('SELECT setval(\'user_id_seq\', COALESCE((SELECT MAX(old_id) + 1 FROM "user"), 1), false)')
+    op.execute('SELECT setval(\'item_id_seq\', COALESCE((SELECT MAX(old_id) + 1 FROM item), 1), false)')
+
+    op.execute('UPDATE "user" SET old_id = nextval(\'user_id_seq\')')
+    op.execute('UPDATE item SET old_id = nextval(\'item_id_seq\'), old_owner_id = (SELECT old_id FROM "user" WHERE "user".id = item.owner_id)')
+
+    # Drop new columns and rename old columns back
+    op.drop_constraint('item_owner_id_fkey', 'item', type_='foreignkey')
+    op.drop_column('item', 'owner_id')
+    op.alter_column('item', 'old_owner_id', new_column_name='owner_id')
+
+    op.drop_column('user', 'id')
+    op.alter_column('user', 'old_id', new_column_name='id')
+
+    op.drop_column('item', 'id')
+    op.alter_column('item', 'old_id', new_column_name='id')
+
+    # Create primary key constraint
+    op.create_primary_key('user_pkey', 'user', ['id'])
+    op.create_primary_key('item_pkey', 'item', ['id'])
+
+    # Recreate foreign key constraint
+    op.create_foreign_key('item_owner_id_fkey', 'item', 'user', ['owner_id'], ['id'])

backend/app/alembic/versions/e2412789c190_initialize_models.py

@@ -0,0 +1,54 @@
+"""Initialize models
+
+Revision ID: e2412789c190
+Revises:
+Create Date: 2023-11-24 22:55:43.195942
+
+"""
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision = "e2412789c190"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "user",
+        sa.Column("email", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_superuser", sa.Boolean(), nullable=False),
+        sa.Column("full_name", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column(
+            "hashed_password", sqlmodel.sql.sqltypes.AutoString(), nullable=False
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_user_email"), "user", ["email"], unique=True)
+    op.create_table(
+        "item",
+        sa.Column("description", sqlmodel.sql.sqltypes.AutoString(), nullable=True),
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("title", sqlmodel.sql.sqltypes.AutoString(), nullable=False),
+        sa.Column("owner_id", sa.Integer(), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["owner_id"],
+            ["user.id"],
+        ),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("item")
+    op.drop_index(op.f("ix_user_email"), table_name="user")
+    op.drop_table("user")
+    # ### end Alembic commands ###

backend/app/alembic/versions/fe56fa70289e_add_created_at_to_user_and_item.py

@@ -0,0 +1,31 @@
+"""Add created_at to User and Item
+
+Revision ID: fe56fa70289e
+Revises: 1a31ce608336
+Create Date: 2026-01-23 15:50:37.171462
+
+"""
+from alembic import op
+import sqlalchemy as sa
+import sqlmodel.sql.sqltypes
+
+
+# revision identifiers, used by Alembic.
+revision = 'fe56fa70289e'
+down_revision = '1a31ce608336'
+branch_labels = None
+depends_on = None
+
+
+def upgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.add_column('item', sa.Column('created_at', sa.DateTime(timezone=True), nullable=True))
+    op.add_column('user', sa.Column('created_at', sa.DateTime(timezone=True), nullable=True))
+    # ### end Alembic commands ###
+
+
+def downgrade():
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_column('user', 'created_at')
+    op.drop_column('item', 'created_at')
+    # ### end Alembic commands ###

backend/app/api/deps.py

@@ -0,0 +1,57 @@
+from collections.abc import Generator
+from typing import Annotated
+
+import jwt
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jwt.exceptions import InvalidTokenError
+from pydantic import ValidationError
+from sqlmodel import Session
+
+from app.core import security
+from app.core.config import settings
+from app.core.db import engine
+from app.models import TokenPayload, User
+
+reusable_oauth2 = OAuth2PasswordBearer(
+    tokenUrl=f"{settings.API_V1_STR}/login/access-token"
+)
+
+
+def get_db() -> Generator[Session]:
+    with Session(engine) as session:
+        yield session
+
+
+SessionDep = Annotated[Session, Depends(get_db)]
+TokenDep = Annotated[str, Depends(reusable_oauth2)]
+
+
+def get_current_user(session: SessionDep, token: TokenDep) -> User:
+    try:
+        payload = jwt.decode(
+            token, settings.SECRET_KEY, algorithms=[security.ALGORITHM]
+        )
+        token_data = TokenPayload(**payload)
+    except InvalidTokenError, ValidationError:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Could not validate credentials",
+        )
+    user = session.get(User, token_data.sub)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    if not user.is_active:
+        raise HTTPException(status_code=400, detail="Inactive user")
+    return user
+
+
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+
+def get_current_active_superuser(current_user: CurrentUser) -> User:
+    if not current_user.is_superuser:
+        raise HTTPException(
+            status_code=403, detail="The user doesn't have enough privileges"
+        )
+    return current_user

backend/app/api/main.py

@@ -0,0 +1,14 @@
+from fastapi import APIRouter
+
+from app.api.routes import items, login, private, users, utils
+from app.core.config import settings
+
+api_router = APIRouter()
+api_router.include_router(login.router)
+api_router.include_router(users.router)
+api_router.include_router(utils.router)
+api_router.include_router(items.router)
+
+
+if settings.FASTAPI_ENV == "development":
+    api_router.include_router(private.router)

backend/app/api/routes/items.py

@@ -0,0 +1,113 @@
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from sqlmodel import col, func, select
+
+from app.api.deps import CurrentUser, SessionDep
+from app.models import Item, ItemCreate, ItemPublic, ItemsPublic, ItemUpdate, Message
+
+router = APIRouter(prefix="/items", tags=["items"])
+
+
+@router.get("/", response_model=ItemsPublic)
+def read_items(
+    session: SessionDep, current_user: CurrentUser, skip: int = 0, limit: int = 100
+) -> Any:
+    """
+    Retrieve items.
+    """
+
+    if current_user.is_superuser:
+        count_statement = select(func.count()).select_from(Item)
+        count = session.exec(count_statement).one()
+        statement = (
+            select(Item).order_by(col(Item.created_at).desc()).offset(skip).limit(limit)
+        )
+        items = session.exec(statement).all()
+    else:
+        count_statement = (
+            select(func.count())
+            .select_from(Item)
+            .where(Item.owner_id == current_user.id)
+        )
+        count = session.exec(count_statement).one()
+        statement = (
+            select(Item)
+            .where(Item.owner_id == current_user.id)
+            .order_by(col(Item.created_at).desc())
+            .offset(skip)
+            .limit(limit)
+        )
+        items = session.exec(statement).all()
+
+    items_public = [ItemPublic.model_validate(item) for item in items]
+    return ItemsPublic(data=items_public, count=count)
+
+
+@router.get("/{id}", response_model=ItemPublic)
+def read_item(session: SessionDep, current_user: CurrentUser, id: uuid.UUID) -> Any:
+    """
+    Get item by ID.
+    """
+    item = session.get(Item, id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    if not current_user.is_superuser and (item.owner_id != current_user.id):
+        raise HTTPException(status_code=403, detail="Not enough permissions")
+    return item
+
+
+@router.post("/", response_model=ItemPublic)
+def create_item(
+    *, session: SessionDep, current_user: CurrentUser, item_in: ItemCreate
+) -> Any:
+    """
+    Create new item.
+    """
+    item = Item.model_validate(item_in, update={"owner_id": current_user.id})
+    session.add(item)
+    session.commit()
+    session.refresh(item)
+    return item
+
+
+@router.put("/{id}", response_model=ItemPublic)
+def update_item(
+    *,
+    session: SessionDep,
+    current_user: CurrentUser,
+    id: uuid.UUID,
+    item_in: ItemUpdate,
+) -> Any:
+    """
+    Update an item.
+    """
+    item = session.get(Item, id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    if not current_user.is_superuser and (item.owner_id != current_user.id):
+        raise HTTPException(status_code=403, detail="Not enough permissions")
+    update_dict = item_in.model_dump(exclude_unset=True)
+    item.sqlmodel_update(update_dict)
+    session.add(item)
+    session.commit()
+    session.refresh(item)
+    return item
+
+
+@router.delete("/{id}")
+def delete_item(
+    session: SessionDep, current_user: CurrentUser, id: uuid.UUID
+) -> Message:
+    """
+    Delete an item.
+    """
+    item = session.get(Item, id)
+    if not item:
+        raise HTTPException(status_code=404, detail="Item not found")
+    if not current_user.is_superuser and (item.owner_id != current_user.id):
+        raise HTTPException(status_code=403, detail="Not enough permissions")
+    session.delete(item)
+    session.commit()
+    return Message(message="Item deleted successfully")

backend/app/api/routes/login.py

@@ -0,0 +1,123 @@
+from datetime import timedelta
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import HTMLResponse
+from fastapi.security import OAuth2PasswordRequestForm
+
+from app import crud
+from app.api.deps import CurrentUser, SessionDep, get_current_active_superuser
+from app.core import security
+from app.core.config import settings
+from app.models import Message, NewPassword, Token, UserPublic, UserUpdate
+from app.utils import (
+    generate_password_reset_token,
+    generate_reset_password_email,
+    send_email,
+    verify_password_reset_token,
+)
+
+router = APIRouter(tags=["login"])
+
+
+@router.post("/login/access-token")
+def login_access_token(
+    session: SessionDep, form_data: Annotated[OAuth2PasswordRequestForm, Depends()]
+) -> Token:
+    """
+    OAuth2 compatible token login, get an access token for future requests
+    """
+    user = crud.authenticate(
+        session=session, email=form_data.username, password=form_data.password
+    )
+    if not user:
+        raise HTTPException(status_code=400, detail="Incorrect email or password")
+    elif not user.is_active:
+        raise HTTPException(status_code=400, detail="Inactive user")
+    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    return Token(
+        access_token=security.create_access_token(
+            user.id, expires_delta=access_token_expires
+        )
+    )
+
+
+@router.post("/login/test-token", response_model=UserPublic)
+def test_token(current_user: CurrentUser) -> Any:
+    """
+    Test access token
+    """
+    return current_user
+
+
+@router.post("/password-recovery/{email}")
+def recover_password(email: str, session: SessionDep) -> Message:
+    """
+    Password Recovery
+    """
+    user = crud.get_user_by_email(session=session, email=email)
+
+    # Always return the same response to prevent email enumeration attacks
+    # Only send email if user actually exists
+    if user:
+        password_reset_token = generate_password_reset_token(email=email)
+        email_data = generate_reset_password_email(
+            email_to=user.email, email=email, token=password_reset_token
+        )
+        send_email(
+            email_to=user.email,
+            subject=email_data.subject,
+            html_content=email_data.html_content,
+        )
+    return Message(
+        message="If that email is registered, we sent a password recovery link"
+    )
+
+
+@router.post("/reset-password/")
+def reset_password(session: SessionDep, body: NewPassword) -> Message:
+    """
+    Reset password
+    """
+    email = verify_password_reset_token(token=body.token)
+    if not email:
+        raise HTTPException(status_code=400, detail="Invalid token")
+    user = crud.get_user_by_email(session=session, email=email)
+    if not user:
+        # Don't reveal that the user doesn't exist - use same error as invalid token
+        raise HTTPException(status_code=400, detail="Invalid token")
+    elif not user.is_active:
+        raise HTTPException(status_code=400, detail="Inactive user")
+    user_in_update = UserUpdate(password=body.new_password)
+    crud.update_user(
+        session=session,
+        db_user=user,
+        user_in=user_in_update,
+    )
+    return Message(message="Password updated successfully")
+
+
+@router.post(
+    "/password-recovery-html-content/{email}",
+    dependencies=[Depends(get_current_active_superuser)],
+    response_class=HTMLResponse,
+)
+def recover_password_html_content(email: str, session: SessionDep) -> Any:
+    """
+    HTML Content for Password Recovery
+    """
+    user = crud.get_user_by_email(session=session, email=email)
+
+    if not user:
+        raise HTTPException(
+            status_code=404,
+            detail="The user with this username does not exist in the system.",
+        )
+    password_reset_token = generate_password_reset_token(email=email)
+    email_data = generate_reset_password_email(
+        email_to=user.email, email=email, token=password_reset_token
+    )
+
+    return HTMLResponse(
+        content=email_data.html_content, headers={"subject:": email_data.subject}
+    )

backend/app/api/routes/private.py

@@ -0,0 +1,38 @@
+from typing import Any
+
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+from app.api.deps import SessionDep
+from app.core.security import get_password_hash
+from app.models import (
+    User,
+    UserPublic,
+)
+
+router = APIRouter(tags=["private"], prefix="/private")
+
+
+class PrivateUserCreate(BaseModel):
+    email: str
+    password: str
+    full_name: str
+    is_verified: bool = False
+
+
+@router.post("/users/", response_model=UserPublic)
+def create_user(user_in: PrivateUserCreate, session: SessionDep) -> Any:
+    """
+    Create a new user.
+    """
+
+    user = User(
+        email=user_in.email,
+        full_name=user_in.full_name,
+        hashed_password=get_password_hash(user_in.password),
+    )
+
+    session.add(user)
+    session.commit()
+
+    return user

backend/app/api/routes/users.py

@@ -0,0 +1,232 @@
+import uuid
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlmodel import col, delete, func, select
+
+from app import crud
+from app.api.deps import (
+    CurrentUser,
+    SessionDep,
+    get_current_active_superuser,
+)
+from app.core.config import settings
+from app.core.security import get_password_hash, verify_password
+from app.models import (
+    Item,
+    Message,
+    UpdatePassword,
+    User,
+    UserCreate,
+    UserPublic,
+    UserRegister,
+    UsersPublic,
+    UserUpdate,
+    UserUpdateMe,
+)
+from app.utils import generate_new_account_email, send_email
+
+router = APIRouter(prefix="/users", tags=["users"])
+
+
+@router.get(
+    "/",
+    dependencies=[Depends(get_current_active_superuser)],
+    response_model=UsersPublic,
+)
+def read_users(session: SessionDep, skip: int = 0, limit: int = 100) -> Any:
+    """
+    Retrieve users.
+    """
+
+    count_statement = select(func.count()).select_from(User)
+    count = session.exec(count_statement).one()
+
+    statement = (
+        select(User).order_by(col(User.created_at).desc()).offset(skip).limit(limit)
+    )
+    users = session.exec(statement).all()
+
+    users_public = [UserPublic.model_validate(user) for user in users]
+    return UsersPublic(data=users_public, count=count)
+
+
+@router.post(
+    "/", dependencies=[Depends(get_current_active_superuser)], response_model=UserPublic
+)
+def create_user(*, session: SessionDep, user_in: UserCreate) -> Any:
+    """
+    Create new user.
+    """
+    user = crud.get_user_by_email(session=session, email=user_in.email)
+    if user:
+        raise HTTPException(
+            status_code=400,
+            detail="The user with this email already exists in the system.",
+        )
+
+    user = crud.create_user(session=session, user_create=user_in)
+    if settings.emails_enabled and user_in.email:
+        email_data = generate_new_account_email(
+            email_to=user_in.email, username=user_in.email, password=user_in.password
+        )
+        send_email(
+            email_to=user_in.email,
+            subject=email_data.subject,
+            html_content=email_data.html_content,
+        )
+    return user
+
+
+@router.patch("/me", response_model=UserPublic)
+def update_user_me(
+    *, session: SessionDep, user_in: UserUpdateMe, current_user: CurrentUser
+) -> Any:
+    """
+    Update own user.
+    """
+
+    if user_in.email:
+        existing_user = crud.get_user_by_email(session=session, email=user_in.email)
+        if existing_user and existing_user.id != current_user.id:
+            raise HTTPException(
+                status_code=409, detail="User with this email already exists"
+            )
+    user_data = user_in.model_dump(exclude_unset=True)
+    current_user.sqlmodel_update(user_data)
+    session.add(current_user)
+    session.commit()
+    session.refresh(current_user)
+    return current_user
+
+
+@router.patch("/me/password", response_model=Message)
+def update_password_me(
+    *, session: SessionDep, body: UpdatePassword, current_user: CurrentUser
+) -> Any:
+    """
+    Update own password.
+    """
+    verified, _ = verify_password(body.current_password, current_user.hashed_password)
+    if not verified:
+        raise HTTPException(status_code=400, detail="Incorrect password")
+    if body.current_password == body.new_password:
+        raise HTTPException(
+            status_code=400, detail="New password cannot be the same as the current one"
+        )
+    hashed_password = get_password_hash(body.new_password)
+    current_user.hashed_password = hashed_password
+    session.add(current_user)
+    session.commit()
+    return Message(message="Password updated successfully")
+
+
+@router.get("/me", response_model=UserPublic)
+def read_user_me(current_user: CurrentUser) -> Any:
+    """
+    Get current user.
+    """
+    return current_user
+
+
+@router.delete("/me", response_model=Message)
+def delete_user_me(session: SessionDep, current_user: CurrentUser) -> Any:
+    """
+    Delete own user.
+    """
+    if current_user.is_superuser:
+        raise HTTPException(
+            status_code=403, detail="Super users are not allowed to delete themselves"
+        )
+    session.delete(current_user)
+    session.commit()
+    return Message(message="User deleted successfully")
+
+
+@router.post("/signup", response_model=UserPublic)
+def register_user(session: SessionDep, user_in: UserRegister) -> Any:
+    """
+    Create new user without the need to be logged in.
+    """
+    user = crud.get_user_by_email(session=session, email=user_in.email)
+    if user:
+        raise HTTPException(
+            status_code=400,
+            detail="The user with this email already exists in the system",
+        )
+    user_create = UserCreate.model_validate(user_in)
+    user = crud.create_user(session=session, user_create=user_create)
+    return user
+
+
+@router.get("/{user_id}", response_model=UserPublic)
+def read_user_by_id(
+    user_id: uuid.UUID, session: SessionDep, current_user: CurrentUser
+) -> Any:
+    """
+    Get a specific user by id.
+    """
+    user = session.get(User, user_id)
+    if user == current_user:
+        return user
+    if not current_user.is_superuser:
+        raise HTTPException(
+            status_code=403,
+            detail="The user doesn't have enough privileges",
+        )
+    if user is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user
+
+
+@router.patch(
+    "/{user_id}",
+    dependencies=[Depends(get_current_active_superuser)],
+    response_model=UserPublic,
+)
+def update_user(
+    *,
+    session: SessionDep,
+    user_id: uuid.UUID,
+    user_in: UserUpdate,
+) -> Any:
+    """
+    Update a user.
+    """
+
+    db_user = session.get(User, user_id)
+    if not db_user:
+        raise HTTPException(
+            status_code=404,
+            detail="The user with this id does not exist in the system",
+        )
+    if user_in.email:
+        existing_user = crud.get_user_by_email(session=session, email=user_in.email)
+        if existing_user and existing_user.id != user_id:
+            raise HTTPException(
+                status_code=409, detail="User with this email already exists"
+            )
+
+    db_user = crud.update_user(session=session, db_user=db_user, user_in=user_in)
+    return db_user
+
+
+@router.delete("/{user_id}", dependencies=[Depends(get_current_active_superuser)])
+def delete_user(
+    session: SessionDep, current_user: CurrentUser, user_id: uuid.UUID
+) -> Message:
+    """
+    Delete a user.
+    """
+    user = session.get(User, user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    if user == current_user:
+        raise HTTPException(
+            status_code=403, detail="Super users are not allowed to delete themselves"
+        )
+    statement = delete(Item).where(col(Item.owner_id) == user_id)
+    session.exec(statement)
+    session.delete(user)
+    session.commit()
+    return Message(message="User deleted successfully")

backend/app/api/routes/utils.py

@@ -0,0 +1,31 @@
+from fastapi import APIRouter, Depends
+from pydantic.networks import EmailStr
+
+from app.api.deps import get_current_active_superuser
+from app.models import Message
+from app.utils import generate_test_email, send_email
+
+router = APIRouter(prefix="/utils", tags=["utils"])
+
+
+@router.post(
+    "/test-email/",
+    dependencies=[Depends(get_current_active_superuser)],
+    status_code=201,
+)
+def test_email(email_to: EmailStr) -> Message:
+    """
+    Test emails.
+    """
+    email_data = generate_test_email(email_to=email_to)
+    send_email(
+        email_to=email_to,
+        subject=email_data.subject,
+        html_content=email_data.html_content,
+    )
+    return Message(message="Test email sent")
+
+
+@router.get("/health-check/")
+async def health_check() -> bool:
+    return True

backend/app/backend_pre_start.py

@@ -1,8 +1,10 @@
 import logging
 
+from sqlalchemy import Engine
+from sqlmodel import Session, select
 from tenacity import after_log, before_log, retry, stop_after_attempt, wait_fixed
 
-from app.db.session import db_session
+from app.core.db import engine
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
@@ -17,18 +19,19 @@ wait_seconds = 1
     before=before_log(logger, logging.INFO),
     after=after_log(logger, logging.WARN),
 )
-def init():
+def init(db_engine: Engine) -> None:
     try:
-        # Try to create session to check if DB is awake
-        db_session.execute("SELECT 1")
+        with Session(db_engine) as session:
+            # Try to create session to check if DB is awake
+            session.exec(select(1))
     except Exception as e:
         logger.error(e)
         raise e
 
 
-def main():
+def main() -> None:
     logger.info("Initializing service")
-    init()
+    init(engine)
     logger.info("Service finished initializing")
 
 

backend/app/core/config.py

@@ -0,0 +1,91 @@
+import warnings
+from typing import Literal, Self
+
+from pydantic import (
+    EmailStr,
+    HttpUrl,
+    PostgresDsn,
+    computed_field,
+    field_validator,
+    model_validator,
+)
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        # Use top level .env file (one level above ./backend/)
+        env_file="../.env",
+        env_ignore_empty=True,
+        extra="ignore",
+    )
+    API_V1_STR: str = "/api/v1"
+    SECRET_KEY: str
+    # 60 minutes * 24 hours * 8 days = 8 days
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 60 * 24 * 8
+    FRONTEND_HOST: str = "http://localhost:5173"
+    FASTAPI_ENV: Literal["development"] | None = None
+
+    PROJECT_NAME: str
+    SENTRY_DSN: HttpUrl | None = None
+    DATABASE_URL: PostgresDsn
+
+    @field_validator("DATABASE_URL", mode="before")
+    @classmethod
+    def _use_psycopg_driver(cls, value: str | PostgresDsn) -> str:
+        database_url = str(value)
+        for scheme in ("postgres://", "postgresql://"):
+            if database_url.startswith(scheme):
+                return database_url.replace(scheme, "postgresql+psycopg://", 1)
+        return database_url
+
+    SMTP_TLS: bool = True
+    SMTP_SSL: bool = False
+    SMTP_PORT: int = 587
+    SMTP_HOST: str | None = None
+    SMTP_USER: str | None = None
+    SMTP_PASSWORD: str | None = None
+    EMAILS_FROM_EMAIL: EmailStr | None = None
+    EMAILS_FROM_NAME: str | None = None
+
+    @model_validator(mode="after")
+    def _set_default_emails_from(self) -> Self:
+        if not self.EMAILS_FROM_NAME:
+            self.EMAILS_FROM_NAME = self.PROJECT_NAME
+        return self
+
+    EMAIL_RESET_TOKEN_EXPIRE_HOURS: int = 48
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def emails_enabled(self) -> bool:
+        return bool(self.SMTP_HOST and self.EMAILS_FROM_EMAIL)
+
+    EMAIL_TEST_USER: EmailStr = "test@example.com"
+    FIRST_SUPERUSER: EmailStr
+    FIRST_SUPERUSER_PASSWORD: str
+
+    def _check_default_secret(self, var_name: str, value: str | None) -> None:
+        if value == "changethis":
+            message = (
+                f'The value of {var_name} is "changethis", '
+                "for security, please change it, at least for deployments."
+            )
+            if self.FASTAPI_ENV == "development":
+                warnings.warn(message, stacklevel=1)
+            else:
+                raise ValueError(message)
+
+    @model_validator(mode="after")
+    def _enforce_non_default_secrets(self) -> Self:
+        self._check_default_secret("SECRET_KEY", self.SECRET_KEY)
+        for host in self.DATABASE_URL.hosts():
+            self._check_default_secret("DATABASE_URL password", host["password"])
+        self._check_default_secret(
+            "FIRST_SUPERUSER_PASSWORD", self.FIRST_SUPERUSER_PASSWORD
+        )
+
+        return self
+
+
+settings = Settings()  # type: ignore

backend/app/core/db.py

@@ -0,0 +1,33 @@
+from sqlmodel import Session, create_engine, select
+
+from app import crud
+from app.core.config import settings
+from app.models import User, UserCreate
+
+engine = create_engine(str(settings.DATABASE_URL))
+
+
+# make sure all SQLModel models are imported (app.models) before initializing DB
+# otherwise, SQLModel might fail to initialize relationships properly
+# for more details: https://github.com/fastapi/full-stack-fastapi-template/issues/28
+
+
+def init_db(session: Session) -> None:
+    # Tables should be created with Alembic migrations
+    # But if you don't want to use migrations, create
+    # the tables un-commenting the next lines
+    # from sqlmodel import SQLModel
+
+    # This works because the models are already imported and registered from app.models
+    # SQLModel.metadata.create_all(engine)
+
+    user = session.exec(
+        select(User).where(User.email == settings.FIRST_SUPERUSER)
+    ).first()
+    if not user:
+        user_in = UserCreate(
+            email=settings.FIRST_SUPERUSER,
+            password=settings.FIRST_SUPERUSER_PASSWORD,
+            is_superuser=True,
+        )
+        user = crud.create_user(session=session, user_create=user_in)

backend/app/core/security.py

@@ -0,0 +1,36 @@
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import jwt
+from pwdlib import PasswordHash
+from pwdlib.hashers.argon2 import Argon2Hasher
+from pwdlib.hashers.bcrypt import BcryptHasher
+
+from app.core.config import settings
+
+password_hash = PasswordHash(
+    (
+        Argon2Hasher(),
+        BcryptHasher(),
+    )
+)
+
+
+ALGORITHM = "HS256"
+
+
+def create_access_token(subject: str | Any, expires_delta: timedelta) -> str:
+    expire = datetime.now(UTC) + expires_delta
+    to_encode = {"exp": expire, "sub": str(subject)}
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=ALGORITHM)
+    return encoded_jwt
+
+
+def verify_password(
+    plain_password: str, hashed_password: str
+) -> tuple[bool, str | None]:
+    return password_hash.verify_and_update(plain_password, hashed_password)
+
+
+def get_password_hash(password: str) -> str:
+    return password_hash.hash(password)

backend/app/crud.py

@@ -0,0 +1,68 @@
+import uuid
+from typing import Any
+
+from sqlmodel import Session, select
+
+from app.core.security import get_password_hash, verify_password
+from app.models import Item, ItemCreate, User, UserCreate, UserUpdate
+
+
+def create_user(*, session: Session, user_create: UserCreate) -> User:
+    db_obj = User.model_validate(
+        user_create, update={"hashed_password": get_password_hash(user_create.password)}
+    )
+    session.add(db_obj)
+    session.commit()
+    session.refresh(db_obj)
+    return db_obj
+
+
+def update_user(*, session: Session, db_user: User, user_in: UserUpdate) -> Any:
+    user_data = user_in.model_dump(exclude_unset=True)
+    extra_data = {}
+    if "password" in user_data:
+        password = user_data["password"]
+        hashed_password = get_password_hash(password)
+        extra_data["hashed_password"] = hashed_password
+    db_user.sqlmodel_update(user_data, update=extra_data)
+    session.add(db_user)
+    session.commit()
+    session.refresh(db_user)
+    return db_user
+
+
+def get_user_by_email(*, session: Session, email: str) -> User | None:
+    statement = select(User).where(User.email == email)
+    session_user = session.exec(statement).first()
+    return session_user
+
+
+# Dummy hash to use for timing attack prevention when user is not found
+# This is an Argon2 hash of a random password, used to ensure constant-time comparison
+DUMMY_HASH = "$argon2id$v=19$m=65536,t=3,p=4$MjQyZWE1MzBjYjJlZTI0Yw$YTU4NGM5ZTZmYjE2NzZlZjY0ZWY3ZGRkY2U2OWFjNjk"
+
+
+def authenticate(*, session: Session, email: str, password: str) -> User | None:
+    db_user = get_user_by_email(session=session, email=email)
+    if not db_user:
+        # Prevent timing attacks by running password verification even when user doesn't exist
+        # This ensures the response time is similar whether or not the email exists
+        verify_password(password, DUMMY_HASH)
+        return None
+    verified, updated_password_hash = verify_password(password, db_user.hashed_password)
+    if not verified:
+        return None
+    if updated_password_hash:
+        db_user.hashed_password = updated_password_hash
+        session.add(db_user)
+        session.commit()
+        session.refresh(db_user)
+    return db_user
+
+
+def create_item(*, session: Session, item_in: ItemCreate, owner_id: uuid.UUID) -> Item:
+    db_item = Item.model_validate(item_in, update={"owner_id": owner_id})
+    session.add(db_item)
+    session.commit()
+    session.refresh(db_item)
+    return db_item

backend/app/initial_data.py

@@ -1,17 +1,19 @@
 import logging
 
-from app.db.init_db import init_db
-from app.db.session import db_session
+from sqlmodel import Session
+
+from app.core.db import engine, init_db
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-def init():
-    init_db(db_session)
+def init() -> None:
+    with Session(engine) as session:
+        init_db(session)
 
 
-def main():
+def main() -> None:
     logger.info("Creating initial data")
     init()
     logger.info("Initial data created")

backend/app/main.py

@@ -0,0 +1,36 @@
+from pathlib import Path
+
+import sentry_sdk
+from fastapi import FastAPI
+from fastapi.routing import APIRoute
+from starlette.middleware.cors import CORSMiddleware
+
+from app.api.main import api_router
+from app.core.config import settings
+
+FRONTEND_DIR = Path(__file__).parent / "frontend"
+
+
+def custom_generate_unique_id(route: APIRoute) -> str:
+    return f"{route.tags[0]}-{route.name}"
+
+
+if settings.SENTRY_DSN and settings.FASTAPI_ENV != "development":
+    sentry_sdk.init(dsn=str(settings.SENTRY_DSN), enable_tracing=True)
+
+app = FastAPI(
+    title=settings.PROJECT_NAME,
+    openapi_url=f"{settings.API_V1_STR}/openapi.json",
+    generate_unique_id_function=custom_generate_unique_id,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[settings.FRONTEND_HOST],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(api_router, prefix=settings.API_V1_STR)
+app.frontend("/", directory=FRONTEND_DIR)

backend/app/models.py

@@ -0,0 +1,133 @@
+import uuid
+from datetime import UTC, datetime
+
+from pydantic import EmailStr
+from sqlalchemy import DateTime
+from sqlmodel import Field, Relationship, SQLModel
+
+
+def get_datetime_utc() -> datetime:
+    return datetime.now(UTC)
+
+
+# Shared properties
+class UserBase(SQLModel):
+    email: EmailStr = Field(unique=True, index=True, max_length=255)
+    is_active: bool = True
+    is_superuser: bool = False
+    full_name: str | None = Field(default=None, max_length=255)
+
+
+# Properties to receive via API on creation
+class UserCreate(UserBase):
+    password: str = Field(min_length=8, max_length=128)
+
+
+class UserRegister(SQLModel):
+    email: EmailStr = Field(max_length=255)
+    password: str = Field(min_length=8, max_length=128)
+    full_name: str | None = Field(default=None, max_length=255)
+
+
+# Properties to receive via API on update, all are optional
+class UserUpdate(SQLModel):
+    email: EmailStr | None = Field(default=None, max_length=255)
+    is_active: bool | None = None
+    is_superuser: bool | None = None
+    full_name: str | None = Field(default=None, max_length=255)
+    password: str | None = Field(default=None, min_length=8, max_length=128)
+
+
+class UserUpdateMe(SQLModel):
+    full_name: str | None = Field(default=None, max_length=255)
+    email: EmailStr | None = Field(default=None, max_length=255)
+
+
+class UpdatePassword(SQLModel):
+    current_password: str = Field(min_length=8, max_length=128)
+    new_password: str = Field(min_length=8, max_length=128)
+
+
+# Database model, database table inferred from class name
+class User(UserBase, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    hashed_password: str
+    created_at: datetime | None = Field(
+        default_factory=get_datetime_utc,
+        sa_type=DateTime(timezone=True),  # type: ignore
+    )
+    items: list[Item] = Relationship(back_populates="owner", cascade_delete=True)
+
+
+# Properties to return via API, id is always required
+class UserPublic(UserBase):
+    id: uuid.UUID
+    created_at: datetime | None = None
+
+
+class UsersPublic(SQLModel):
+    data: list[UserPublic]
+    count: int
+
+
+# Shared properties
+class ItemBase(SQLModel):
+    title: str = Field(min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=255)
+
+
+# Properties to receive on item creation
+class ItemCreate(ItemBase):
+    pass
+
+
+# Properties to receive on item update
+class ItemUpdate(SQLModel):
+    title: str | None = Field(default=None, min_length=1, max_length=255)
+    description: str | None = Field(default=None, max_length=255)
+
+
+# Database model, database table inferred from class name
+class Item(ItemBase, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    created_at: datetime | None = Field(
+        default_factory=get_datetime_utc,
+        sa_type=DateTime(timezone=True),  # type: ignore
+    )
+    owner_id: uuid.UUID = Field(
+        foreign_key="user.id", nullable=False, ondelete="CASCADE"
+    )
+    owner: User | None = Relationship(back_populates="items")
+
+
+# Properties to return via API, id is always required
+class ItemPublic(ItemBase):
+    id: uuid.UUID
+    owner_id: uuid.UUID
+    created_at: datetime | None = None
+
+
+class ItemsPublic(SQLModel):
+    data: list[ItemPublic]
+    count: int
+
+
+# Generic message
+class Message(SQLModel):
+    message: str
+
+
+# JSON payload containing access token
+class Token(SQLModel):
+    access_token: str
+    token_type: str = "bearer"
+
+
+# Contents of JWT token
+class TokenPayload(SQLModel):
+    sub: str | None = None
+
+
+class NewPassword(SQLModel):
+    token: str
+    new_password: str = Field(min_length=8, max_length=128)

backend/app/tests_pre_start.py

@@ -1,8 +1,10 @@
 import logging
 
+from sqlalchemy import Engine
+from sqlmodel import Session, select
 from tenacity import after_log, before_log, retry, stop_after_attempt, wait_fixed
 
-from app.db.session import db_session
+from app.core.db import engine
 
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
@@ -17,18 +19,19 @@ wait_seconds = 1
     before=before_log(logger, logging.INFO),
     after=after_log(logger, logging.WARN),
 )
-def init():
+def init(db_engine: Engine) -> None:
     try:
         # Try to create session to check if DB is awake
-        db_session.execute("SELECT 1")
+        with Session(db_engine) as session:
+            session.exec(select(1))
     except Exception as e:
         logger.error(e)
         raise e
 
 
-def main():
+def main() -> None:
     logger.info("Initializing service")
-    init()
+    init(engine)
     logger.info("Service finished initializing")
 
 

backend/app/utils.py

@@ -0,0 +1,124 @@
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import emails
+import jwt
+from jinja2 import Template
+from jwt.exceptions import InvalidTokenError
+
+from app.core import security
+from app.core.config import settings
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EmailData:
+    html_content: str
+    subject: str
+
+
+def render_email_template(*, template_name: str, context: dict[str, Any]) -> str:
+    template_str = (
+        Path(__file__).parent / "email-templates" / template_name
+    ).read_text()
+    html_content = Template(template_str).render(context)
+    return html_content
+
+
+def send_email(
+    *,
+    email_to: str,
+    subject: str = "",
+    html_content: str = "",
+) -> None:
+    assert settings.emails_enabled, "no provided configuration for email variables"
+    assert settings.EMAILS_FROM_EMAIL  # For type checker
+    message = emails.message.Message(
+        subject=subject,
+        html=html_content,
+        mail_from=(settings.EMAILS_FROM_NAME, settings.EMAILS_FROM_EMAIL),
+    )
+    smtp_options = {"host": settings.SMTP_HOST, "port": settings.SMTP_PORT}
+    if settings.SMTP_TLS:
+        smtp_options["tls"] = True
+    elif settings.SMTP_SSL:
+        smtp_options["ssl"] = True
+    if settings.SMTP_USER:
+        smtp_options["user"] = settings.SMTP_USER
+    if settings.SMTP_PASSWORD:
+        smtp_options["password"] = settings.SMTP_PASSWORD
+    response = message.send(to=email_to, smtp=smtp_options)
+    logger.info(f"send email result: {response}")
+
+
+def generate_test_email(email_to: str) -> EmailData:
+    project_name = settings.PROJECT_NAME
+    subject = f"{project_name} - Test email"
+    html_content = render_email_template(
+        template_name="test_email.html",
+        context={"project_name": settings.PROJECT_NAME, "email": email_to},
+    )
+    return EmailData(html_content=html_content, subject=subject)
+
+
+def generate_reset_password_email(email_to: str, email: str, token: str) -> EmailData:
+    project_name = settings.PROJECT_NAME
+    subject = f"{project_name} - Password recovery for user {email}"
+    link = f"{settings.FRONTEND_HOST}/reset-password?token={token}"
+    html_content = render_email_template(
+        template_name="reset_password.html",
+        context={
+            "project_name": settings.PROJECT_NAME,
+            "username": email,
+            "email": email_to,
+            "valid_hours": settings.EMAIL_RESET_TOKEN_EXPIRE_HOURS,
+            "link": link,
+        },
+    )
+    return EmailData(html_content=html_content, subject=subject)
+
+
+def generate_new_account_email(
+    email_to: str, username: str, password: str
+) -> EmailData:
+    project_name = settings.PROJECT_NAME
+    subject = f"{project_name} - New account for user {username}"
+    html_content = render_email_template(
+        template_name="new_account.html",
+        context={
+            "project_name": settings.PROJECT_NAME,
+            "username": username,
+            "password": password,
+            "email": email_to,
+            "link": settings.FRONTEND_HOST,
+        },
+    )
+    return EmailData(html_content=html_content, subject=subject)
+
+
+def generate_password_reset_token(email: str) -> str:
+    delta = timedelta(hours=settings.EMAIL_RESET_TOKEN_EXPIRE_HOURS)
+    now = datetime.now(UTC)
+    expires = now + delta
+    exp = expires.timestamp()
+    encoded_jwt = jwt.encode(
+        {"exp": exp, "nbf": now, "sub": email},
+        settings.SECRET_KEY,
+        algorithm=security.ALGORITHM,
+    )
+    return encoded_jwt
+
+
+def verify_password_reset_token(token: str) -> str | None:
+    try:
+        decoded_token = jwt.decode(
+            token, settings.SECRET_KEY, algorithms=[security.ALGORITHM]
+        )
+        return str(decoded_token["sub"])
+    except InvalidTokenError:
+        return None

backend/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "app"
+version = "0.1.0"
+description = ""
+requires-python = ">=3.14,<4.0"
+dependencies = [
+    "fastapi[standard]>=0.141.1,<1.0.0",
+    "python-multipart<1.0.0,>=0.0.27",
+    "email-validator<3.0.0.0,>=2.1.0.post1",
+    "tenacity<10.0.0,>=8.2.3",
+    "pydantic>2.0",
+    "emails>=1.1.2,<2.0",
+    "jinja2<4.0.0,>=3.1.4",
+    "alembic<2.0.0,>=1.12.1",
+    "httpx<1.0.0,>=0.25.1",
+    "psycopg[binary]>=3.3.4,<4.0.0",
+    "sqlmodel>=0.0.39,<1.0.0",
+    "pydantic-settings<3.0.0,>=2.2.1",
+    "sentry-sdk[fastapi]>=2.66.1,<3.0.0",
+    "pyjwt<3.0.0,>=2.13.0",
+    "pwdlib[argon2,bcrypt]>=0.3.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest<10.0.0,>=7.4.3",
+    "mypy<3.0.0,>=1.8.0",
+    "ty>=0.0.25",
+    "ruff<1.0.0,>=0.2.2",
+    "coverage<8.0.0,>=7.4.3",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.mypy]
+strict = true
+exclude = ["venv", ".venv", "alembic"]
+
+[tool.ruff]
+target-version = "py314"
+exclude = ["alembic"]
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG001", # unused arguments in functions
+    "T201",   # print statements are not allowed
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+    "W191",  # indentation contains tabs
+    "B904",  # Allow raising exceptions without from e, for HTTPException
+]
+
+[tool.ruff.lint.pyupgrade]
+# Preserve types, even if a file imports `from __future__ import annotations`.
+keep-runtime-typing = true
+
+[tool.coverage.run]
+source = ["app"]
+dynamic_context = "test_function"
+
+[tool.coverage.report]
+show_missing = true
+sort = "-Cover"
+
+[tool.coverage.html]
+show_contexts = true
+
+[tool.ty.terminal]
+error-on-warning = true
+
+[tool.fastapi]
+entrypoint = "app.main:app"

backend/scripts/format.sh

@@ -0,0 +1,5 @@
+#!/bin/sh -e
+set -x
+
+ruff check app scripts --fix
+ruff format app scripts

backend/scripts/lint.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+mypy app
+ty check app
+ruff check app
+ruff format app --check

backend/scripts/prestart.sh

@@ -1,10 +1,13 @@
 #! /usr/bin/env bash
 
+set -e
+set -x
+
 # Let the DB start
-python /app/app/backend_pre_start.py
+python app/backend_pre_start.py
 
 # Run migrations
 alembic upgrade head
 
 # Create initial data in DB
-python /app/app/initial_data.py
+python app/initial_data.py

backend/scripts/test.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+
+set -e
+set -x
+
+FASTAPI_ENV=development coverage run -m pytest tests/
+coverage report
+coverage html --title "${@-coverage}"

backend/scripts/tests-start.sh

@@ -0,0 +1,7 @@
+#! /usr/bin/env bash
+set -e
+set -x
+
+python app/tests_pre_start.py
+
+bash scripts/test.sh "$@"

backend/tests/api/routes/test_items.py

@@ -0,0 +1,164 @@
+import uuid
+
+from fastapi.testclient import TestClient
+from sqlmodel import Session
+
+from app.core.config import settings
+from tests.utils.item import create_random_item
+
+
+def test_create_item(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    data = {"title": "Foo", "description": "Fighters"}
+    response = client.post(
+        f"{settings.API_V1_STR}/items/",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert response.status_code == 200
+    content = response.json()
+    assert content["title"] == data["title"]
+    assert content["description"] == data["description"]
+    assert "id" in content
+    assert "owner_id" in content
+
+
+def test_read_item(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    response = client.get(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=superuser_token_headers,
+    )
+    assert response.status_code == 200
+    content = response.json()
+    assert content["title"] == item.title
+    assert content["description"] == item.description
+    assert content["id"] == str(item.id)
+    assert content["owner_id"] == str(item.owner_id)
+
+
+def test_read_item_not_found(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    response = client.get(
+        f"{settings.API_V1_STR}/items/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+    )
+    assert response.status_code == 404
+    content = response.json()
+    assert content["detail"] == "Item not found"
+
+
+def test_read_item_not_enough_permissions(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    response = client.get(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=normal_user_token_headers,
+    )
+    assert response.status_code == 403
+    content = response.json()
+    assert content["detail"] == "Not enough permissions"
+
+
+def test_read_items(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    create_random_item(db)
+    create_random_item(db)
+    response = client.get(
+        f"{settings.API_V1_STR}/items/",
+        headers=superuser_token_headers,
+    )
+    assert response.status_code == 200
+    content = response.json()
+    assert len(content["data"]) >= 2
+
+
+def test_update_item(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    data = {"title": "Updated title", "description": "Updated description"}
+    response = client.put(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert response.status_code == 200
+    content = response.json()
+    assert content["title"] == data["title"]
+    assert content["description"] == data["description"]
+    assert content["id"] == str(item.id)
+    assert content["owner_id"] == str(item.owner_id)
+
+
+def test_update_item_not_found(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    data = {"title": "Updated title", "description": "Updated description"}
+    response = client.put(
+        f"{settings.API_V1_STR}/items/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert response.status_code == 404
+    content = response.json()
+    assert content["detail"] == "Item not found"
+
+
+def test_update_item_not_enough_permissions(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    data = {"title": "Updated title", "description": "Updated description"}
+    response = client.put(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=normal_user_token_headers,
+        json=data,
+    )
+    assert response.status_code == 403
+    content = response.json()
+    assert content["detail"] == "Not enough permissions"
+
+
+def test_delete_item(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    response = client.delete(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=superuser_token_headers,
+    )
+    assert response.status_code == 200
+    content = response.json()
+    assert content["message"] == "Item deleted successfully"
+
+
+def test_delete_item_not_found(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    response = client.delete(
+        f"{settings.API_V1_STR}/items/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+    )
+    assert response.status_code == 404
+    content = response.json()
+    assert content["detail"] == "Item not found"
+
+
+def test_delete_item_not_enough_permissions(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    item = create_random_item(db)
+    response = client.delete(
+        f"{settings.API_V1_STR}/items/{item.id}",
+        headers=normal_user_token_headers,
+    )
+    assert response.status_code == 403
+    content = response.json()
+    assert content["detail"] == "Not enough permissions"

backend/tests/api/routes/test_login.py

@@ -0,0 +1,191 @@
+from unittest.mock import patch
+
+from fastapi.testclient import TestClient
+from pwdlib.hashers.bcrypt import BcryptHasher
+from sqlmodel import Session
+
+from app.core.config import settings
+from app.core.security import get_password_hash, verify_password
+from app.crud import create_user
+from app.models import User, UserCreate
+from app.utils import generate_password_reset_token
+from tests.utils.user import user_authentication_headers
+from tests.utils.utils import random_email, random_lower_string
+
+
+def test_get_access_token(client: TestClient) -> None:
+    login_data = {
+        "username": settings.FIRST_SUPERUSER,
+        "password": settings.FIRST_SUPERUSER_PASSWORD,
+    }
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    tokens = r.json()
+    assert r.status_code == 200
+    assert "access_token" in tokens
+    assert tokens["access_token"]
+
+
+def test_get_access_token_incorrect_password(client: TestClient) -> None:
+    login_data = {
+        "username": settings.FIRST_SUPERUSER,
+        "password": "incorrect",
+    }
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    assert r.status_code == 400
+
+
+def test_use_access_token(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    r = client.post(
+        f"{settings.API_V1_STR}/login/test-token",
+        headers=superuser_token_headers,
+    )
+    result = r.json()
+    assert r.status_code == 200
+    assert "email" in result
+
+
+def test_recovery_password(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    with (
+        patch("app.core.config.settings.SMTP_HOST", "smtp.example.com"),
+        patch("app.core.config.settings.SMTP_USER", "admin@example.com"),
+    ):
+        email = "test@example.com"
+        r = client.post(
+            f"{settings.API_V1_STR}/password-recovery/{email}",
+            headers=normal_user_token_headers,
+        )
+        assert r.status_code == 200
+        assert r.json() == {
+            "message": "If that email is registered, we sent a password recovery link"
+        }
+
+
+def test_recovery_password_user_not_exits(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    email = "jVgQr@example.com"
+    r = client.post(
+        f"{settings.API_V1_STR}/password-recovery/{email}",
+        headers=normal_user_token_headers,
+    )
+    # Should return 200 with generic message to prevent email enumeration attacks
+    assert r.status_code == 200
+    assert r.json() == {
+        "message": "If that email is registered, we sent a password recovery link"
+    }
+
+
+def test_reset_password(client: TestClient, db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    new_password = random_lower_string()
+
+    user_create = UserCreate(
+        email=email,
+        full_name="Test User",
+        password=password,
+        is_active=True,
+        is_superuser=False,
+    )
+    user = create_user(session=db, user_create=user_create)
+    token = generate_password_reset_token(email=email)
+    headers = user_authentication_headers(client=client, email=email, password=password)
+    data = {"new_password": new_password, "token": token}
+
+    r = client.post(
+        f"{settings.API_V1_STR}/reset-password/",
+        headers=headers,
+        json=data,
+    )
+
+    assert r.status_code == 200
+    assert r.json() == {"message": "Password updated successfully"}
+
+    db.refresh(user)
+    verified, _ = verify_password(new_password, user.hashed_password)
+    assert verified
+
+
+def test_reset_password_invalid_token(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    data = {"new_password": "changethis", "token": "invalid"}
+    r = client.post(
+        f"{settings.API_V1_STR}/reset-password/",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    response = r.json()
+
+    assert "detail" in response
+    assert r.status_code == 400
+    assert response["detail"] == "Invalid token"
+
+
+def test_login_with_bcrypt_password_upgrades_to_argon2(
+    client: TestClient, db: Session
+) -> None:
+    """Test that logging in with a bcrypt password hash upgrades it to argon2."""
+    email = random_email()
+    password = random_lower_string()
+
+    # Create a bcrypt hash directly (simulating legacy password)
+    bcrypt_hasher = BcryptHasher()
+    bcrypt_hash = bcrypt_hasher.hash(password)
+    assert bcrypt_hash.startswith("$2")  # bcrypt hashes start with $2
+
+    user = User(email=email, hashed_password=bcrypt_hash, is_active=True)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+
+    assert user.hashed_password.startswith("$2")
+
+    login_data = {"username": email, "password": password}
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    assert r.status_code == 200
+    tokens = r.json()
+    assert "access_token" in tokens
+
+    db.refresh(user)
+
+    # Verify the hash was upgraded to argon2
+    assert user.hashed_password.startswith("$argon2")
+
+    verified, updated_hash = verify_password(password, user.hashed_password)
+    assert verified
+    # Should not need another update since it's already argon2
+    assert updated_hash is None
+
+
+def test_login_with_argon2_password_keeps_hash(client: TestClient, db: Session) -> None:
+    """Test that logging in with an argon2 password hash does not update it."""
+    email = random_email()
+    password = random_lower_string()
+
+    # Create an argon2 hash (current default)
+    argon2_hash = get_password_hash(password)
+    assert argon2_hash.startswith("$argon2")
+
+    # Create user with argon2 hash
+    user = User(email=email, hashed_password=argon2_hash, is_active=True)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+
+    original_hash = user.hashed_password
+
+    login_data = {"username": email, "password": password}
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    assert r.status_code == 200
+    tokens = r.json()
+    assert "access_token" in tokens
+
+    db.refresh(user)
+
+    assert user.hashed_password == original_hash
+    assert user.hashed_password.startswith("$argon2")

backend/tests/api/routes/test_private.py

@@ -0,0 +1,26 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session, select
+
+from app.core.config import settings
+from app.models import User
+
+
+def test_create_user(client: TestClient, db: Session) -> None:
+    r = client.post(
+        f"{settings.API_V1_STR}/private/users/",
+        json={
+            "email": "pollo@listo.com",
+            "password": "password123",
+            "full_name": "Pollo Listo",
+        },
+    )
+
+    assert r.status_code == 200
+
+    data = r.json()
+
+    user = db.exec(select(User).where(User.id == data["id"])).first()
+
+    assert user
+    assert user.email == "pollo@listo.com"
+    assert user.full_name == "Pollo Listo"

backend/tests/api/routes/test_users.py

@@ -0,0 +1,521 @@
+import uuid
+from unittest.mock import patch
+
+from fastapi.testclient import TestClient
+from sqlmodel import Session, select
+
+from app import crud
+from app.core.config import settings
+from app.core.security import verify_password
+from app.models import User, UserCreate
+from tests.utils.user import create_random_user
+from tests.utils.utils import random_email, random_lower_string
+
+
+def test_get_users_superuser_me(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    r = client.get(f"{settings.API_V1_STR}/users/me", headers=superuser_token_headers)
+    current_user = r.json()
+    assert current_user
+    assert current_user["is_active"] is True
+    assert current_user["is_superuser"]
+    assert current_user["email"] == settings.FIRST_SUPERUSER
+
+
+def test_get_users_normal_user_me(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    r = client.get(f"{settings.API_V1_STR}/users/me", headers=normal_user_token_headers)
+    current_user = r.json()
+    assert current_user
+    assert current_user["is_active"] is True
+    assert current_user["is_superuser"] is False
+    assert current_user["email"] == settings.EMAIL_TEST_USER
+
+
+def test_create_user_new_email(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    with (
+        patch("app.utils.send_email", return_value=None),
+        patch("app.core.config.settings.SMTP_HOST", "smtp.example.com"),
+        patch("app.core.config.settings.SMTP_USER", "admin@example.com"),
+    ):
+        username = random_email()
+        password = random_lower_string()
+        data = {"email": username, "password": password}
+        r = client.post(
+            f"{settings.API_V1_STR}/users/",
+            headers=superuser_token_headers,
+            json=data,
+        )
+        assert 200 <= r.status_code < 300
+        created_user = r.json()
+        user = crud.get_user_by_email(session=db, email=username)
+        assert user
+        assert user.email == created_user["email"]
+
+
+def test_get_existing_user_as_superuser(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    user_id = user.id
+    r = client.get(
+        f"{settings.API_V1_STR}/users/{user_id}",
+        headers=superuser_token_headers,
+    )
+    assert 200 <= r.status_code < 300
+    api_user = r.json()
+    existing_user = crud.get_user_by_email(session=db, email=username)
+    assert existing_user
+    assert existing_user.email == api_user["email"]
+
+
+def test_get_non_existing_user_as_superuser(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    r = client.get(
+        f"{settings.API_V1_STR}/users/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+    )
+    assert r.status_code == 404
+    assert r.json() == {"detail": "User not found"}
+
+
+def test_get_existing_user_current_user(client: TestClient, db: Session) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    user_id = user.id
+
+    login_data = {
+        "username": username,
+        "password": password,
+    }
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    tokens = r.json()
+    a_token = tokens["access_token"]
+    headers = {"Authorization": f"Bearer {a_token}"}
+
+    r = client.get(
+        f"{settings.API_V1_STR}/users/{user_id}",
+        headers=headers,
+    )
+    assert 200 <= r.status_code < 300
+    api_user = r.json()
+    existing_user = crud.get_user_by_email(session=db, email=username)
+    assert existing_user
+    assert existing_user.email == api_user["email"]
+
+
+def test_get_existing_user_permissions_error(
+    db: Session,
+    client: TestClient,
+    normal_user_token_headers: dict[str, str],
+) -> None:
+    user = create_random_user(db)
+
+    r = client.get(
+        f"{settings.API_V1_STR}/users/{user.id}",
+        headers=normal_user_token_headers,
+    )
+    assert r.status_code == 403
+    assert r.json() == {"detail": "The user doesn't have enough privileges"}
+
+
+def test_get_non_existing_user_permissions_error(
+    client: TestClient,
+    normal_user_token_headers: dict[str, str],
+) -> None:
+    user_id = uuid.uuid4()
+
+    r = client.get(
+        f"{settings.API_V1_STR}/users/{user_id}",
+        headers=normal_user_token_headers,
+    )
+    assert r.status_code == 403
+    assert r.json() == {"detail": "The user doesn't have enough privileges"}
+
+
+def test_create_user_existing_username(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    # username = email
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    crud.create_user(session=db, user_create=user_in)
+    data = {"email": username, "password": password}
+    r = client.post(
+        f"{settings.API_V1_STR}/users/",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    created_user = r.json()
+    assert r.status_code == 400
+    assert "_id" not in created_user
+
+
+def test_create_user_by_normal_user(
+    client: TestClient, normal_user_token_headers: dict[str, str]
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    data = {"email": username, "password": password}
+    r = client.post(
+        f"{settings.API_V1_STR}/users/",
+        headers=normal_user_token_headers,
+        json=data,
+    )
+    assert r.status_code == 403
+
+
+def test_retrieve_users(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    crud.create_user(session=db, user_create=user_in)
+
+    username2 = random_email()
+    password2 = random_lower_string()
+    user_in2 = UserCreate(email=username2, password=password2)
+    crud.create_user(session=db, user_create=user_in2)
+
+    r = client.get(f"{settings.API_V1_STR}/users/", headers=superuser_token_headers)
+    all_users = r.json()
+
+    assert len(all_users["data"]) > 1
+    assert "count" in all_users
+    for item in all_users["data"]:
+        assert "email" in item
+
+
+def test_update_user_me(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    full_name = "Updated Name"
+    email = random_email()
+    data = {"full_name": full_name, "email": email}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me",
+        headers=normal_user_token_headers,
+        json=data,
+    )
+    assert r.status_code == 200
+    updated_user = r.json()
+    assert updated_user["email"] == email
+    assert updated_user["full_name"] == full_name
+
+    user_query = select(User).where(User.email == email)
+    user_db = db.exec(user_query).first()
+    assert user_db
+    assert user_db.email == email
+    assert user_db.full_name == full_name
+
+
+def test_update_password_me(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    new_password = random_lower_string()
+    data = {
+        "current_password": settings.FIRST_SUPERUSER_PASSWORD,
+        "new_password": new_password,
+    }
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me/password",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 200
+    updated_user = r.json()
+    assert updated_user["message"] == "Password updated successfully"
+
+    user_query = select(User).where(User.email == settings.FIRST_SUPERUSER)
+    user_db = db.exec(user_query).first()
+    assert user_db
+    assert user_db.email == settings.FIRST_SUPERUSER
+    verified, _ = verify_password(new_password, user_db.hashed_password)
+    assert verified
+
+    # Revert to the old password to keep consistency in test
+    old_data = {
+        "current_password": new_password,
+        "new_password": settings.FIRST_SUPERUSER_PASSWORD,
+    }
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me/password",
+        headers=superuser_token_headers,
+        json=old_data,
+    )
+    db.refresh(user_db)
+
+    assert r.status_code == 200
+    verified, _ = verify_password(
+        settings.FIRST_SUPERUSER_PASSWORD, user_db.hashed_password
+    )
+    assert verified
+
+
+def test_update_password_me_incorrect_password(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    new_password = random_lower_string()
+    data = {"current_password": new_password, "new_password": new_password}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me/password",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 400
+    updated_user = r.json()
+    assert updated_user["detail"] == "Incorrect password"
+
+
+def test_update_user_me_email_exists(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+
+    data = {"email": user.email}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me",
+        headers=normal_user_token_headers,
+        json=data,
+    )
+    assert r.status_code == 409
+    assert r.json()["detail"] == "User with this email already exists"
+
+
+def test_update_password_me_same_password_error(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    data = {
+        "current_password": settings.FIRST_SUPERUSER_PASSWORD,
+        "new_password": settings.FIRST_SUPERUSER_PASSWORD,
+    }
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/me/password",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 400
+    updated_user = r.json()
+    assert (
+        updated_user["detail"] == "New password cannot be the same as the current one"
+    )
+
+
+def test_register_user(client: TestClient, db: Session) -> None:
+    username = random_email()
+    password = random_lower_string()
+    full_name = random_lower_string()
+    data = {"email": username, "password": password, "full_name": full_name}
+    r = client.post(
+        f"{settings.API_V1_STR}/users/signup",
+        json=data,
+    )
+    assert r.status_code == 200
+    created_user = r.json()
+    assert created_user["email"] == username
+    assert created_user["full_name"] == full_name
+
+    user_query = select(User).where(User.email == username)
+    user_db = db.exec(user_query).first()
+    assert user_db
+    assert user_db.email == username
+    assert user_db.full_name == full_name
+    verified, _ = verify_password(password, user_db.hashed_password)
+    assert verified
+
+
+def test_register_user_already_exists_error(client: TestClient) -> None:
+    password = random_lower_string()
+    full_name = random_lower_string()
+    data = {
+        "email": settings.FIRST_SUPERUSER,
+        "password": password,
+        "full_name": full_name,
+    }
+    r = client.post(
+        f"{settings.API_V1_STR}/users/signup",
+        json=data,
+    )
+    assert r.status_code == 400
+    assert r.json()["detail"] == "The user with this email already exists in the system"
+
+
+def test_update_user(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+
+    data = {"full_name": "Updated_full_name"}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/{user.id}",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 200
+    updated_user = r.json()
+
+    assert updated_user["full_name"] == "Updated_full_name"
+
+    user_query = select(User).where(User.email == username)
+    user_db = db.exec(user_query).first()
+    db.refresh(user_db)
+    assert user_db
+    assert user_db.full_name == "Updated_full_name"
+
+
+def test_update_user_not_exists(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    data = {"full_name": "Updated_full_name"}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 404
+    assert r.json()["detail"] == "The user with this id does not exist in the system"
+
+
+def test_update_user_email_exists(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+
+    username2 = random_email()
+    password2 = random_lower_string()
+    user_in2 = UserCreate(email=username2, password=password2)
+    user2 = crud.create_user(session=db, user_create=user_in2)
+
+    data = {"email": user2.email}
+    r = client.patch(
+        f"{settings.API_V1_STR}/users/{user.id}",
+        headers=superuser_token_headers,
+        json=data,
+    )
+    assert r.status_code == 409
+    assert r.json()["detail"] == "User with this email already exists"
+
+
+def test_delete_user_me(client: TestClient, db: Session) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    user_id = user.id
+
+    login_data = {
+        "username": username,
+        "password": password,
+    }
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=login_data)
+    tokens = r.json()
+    a_token = tokens["access_token"]
+    headers = {"Authorization": f"Bearer {a_token}"}
+
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/me",
+        headers=headers,
+    )
+    assert r.status_code == 200
+    deleted_user = r.json()
+    assert deleted_user["message"] == "User deleted successfully"
+    result = db.exec(select(User).where(User.id == user_id)).first()
+    assert result is None
+
+    user_query = select(User).where(User.id == user_id)
+    user_db = db.execute(user_query).first()
+    assert user_db is None
+
+
+def test_delete_user_me_as_superuser(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/me",
+        headers=superuser_token_headers,
+    )
+    assert r.status_code == 403
+    response = r.json()
+    assert response["detail"] == "Super users are not allowed to delete themselves"
+
+
+def test_delete_user_super_user(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    user_id = user.id
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/{user_id}",
+        headers=superuser_token_headers,
+    )
+    assert r.status_code == 200
+    deleted_user = r.json()
+    assert deleted_user["message"] == "User deleted successfully"
+    result = db.exec(select(User).where(User.id == user_id)).first()
+    assert result is None
+
+
+def test_delete_user_not_found(
+    client: TestClient, superuser_token_headers: dict[str, str]
+) -> None:
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/{uuid.uuid4()}",
+        headers=superuser_token_headers,
+    )
+    assert r.status_code == 404
+    assert r.json()["detail"] == "User not found"
+
+
+def test_delete_user_current_super_user_error(
+    client: TestClient, superuser_token_headers: dict[str, str], db: Session
+) -> None:
+    super_user = crud.get_user_by_email(session=db, email=settings.FIRST_SUPERUSER)
+    assert super_user
+    user_id = super_user.id
+
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/{user_id}",
+        headers=superuser_token_headers,
+    )
+    assert r.status_code == 403
+    assert r.json()["detail"] == "Super users are not allowed to delete themselves"
+
+
+def test_delete_user_without_privileges(
+    client: TestClient, normal_user_token_headers: dict[str, str], db: Session
+) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+
+    r = client.delete(
+        f"{settings.API_V1_STR}/users/{user.id}",
+        headers=normal_user_token_headers,
+    )
+    assert r.status_code == 403
+    assert r.json()["detail"] == "The user doesn't have enough privileges"

backend/tests/conftest.py

@@ -0,0 +1,42 @@
+from collections.abc import Generator
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlmodel import Session, delete
+
+from app.core.config import settings
+from app.core.db import engine, init_db
+from app.main import app
+from app.models import Item, User
+from tests.utils.user import authentication_token_from_email
+from tests.utils.utils import get_superuser_token_headers
+
+
+@pytest.fixture(scope="session", autouse=True)
+def db() -> Generator[Session]:
+    with Session(engine) as session:
+        init_db(session)
+        yield session
+        statement = delete(Item)
+        session.execute(statement)
+        statement = delete(User)
+        session.execute(statement)
+        session.commit()
+
+
+@pytest.fixture(scope="module")
+def client() -> Generator[TestClient]:
+    with TestClient(app) as c:
+        yield c
+
+
+@pytest.fixture(scope="module")
+def superuser_token_headers(client: TestClient) -> dict[str, str]:
+    return get_superuser_token_headers(client)
+
+
+@pytest.fixture(scope="module")
+def normal_user_token_headers(client: TestClient, db: Session) -> dict[str, str]:
+    return authentication_token_from_email(
+        client=client, email=settings.EMAIL_TEST_USER, db=db
+    )

backend/tests/crud/test_user.py

@@ -0,0 +1,130 @@
+from fastapi.encoders import jsonable_encoder
+from pwdlib.hashers.bcrypt import BcryptHasher
+from sqlmodel import Session
+
+from app import crud
+from app.core.security import verify_password
+from app.models import User, UserCreate, UserUpdate
+from tests.utils.utils import random_email, random_lower_string
+
+
+def test_create_user(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    assert user.email == email
+    assert hasattr(user, "hashed_password")
+
+
+def test_authenticate_user(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    authenticated_user = crud.authenticate(session=db, email=email, password=password)
+    assert authenticated_user
+    assert user.email == authenticated_user.email
+
+
+def test_not_authenticate_user(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user = crud.authenticate(session=db, email=email, password=password)
+    assert user is None
+
+
+def test_check_if_user_is_active(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    assert user.is_active is True
+
+
+def test_check_if_user_is_active_inactive(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password, is_active=False)
+    user = crud.create_user(session=db, user_create=user_in)
+    assert user.is_active is False
+
+
+def test_check_if_user_is_superuser(db: Session) -> None:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password, is_superuser=True)
+    user = crud.create_user(session=db, user_create=user_in)
+    assert user.is_superuser is True
+
+
+def test_check_if_user_is_superuser_normal_user(db: Session) -> None:
+    username = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=username, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    assert user.is_superuser is False
+
+
+def test_get_user(db: Session) -> None:
+    password = random_lower_string()
+    username = random_email()
+    user_in = UserCreate(email=username, password=password, is_superuser=True)
+    user = crud.create_user(session=db, user_create=user_in)
+    user_2 = db.get(User, user.id)
+    assert user_2
+    assert user.email == user_2.email
+    assert jsonable_encoder(user) == jsonable_encoder(user_2)
+
+
+def test_update_user(db: Session) -> None:
+    password = random_lower_string()
+    email = random_email()
+    user_in = UserCreate(email=email, password=password, is_superuser=True)
+    user = crud.create_user(session=db, user_create=user_in)
+    new_password = random_lower_string()
+    user_in_update = UserUpdate(password=new_password, is_superuser=True)
+    if user.id is not None:
+        crud.update_user(session=db, db_user=user, user_in=user_in_update)
+    user_2 = db.get(User, user.id)
+    assert user_2
+    assert user.email == user_2.email
+    verified, _ = verify_password(new_password, user_2.hashed_password)
+    assert verified
+
+
+def test_authenticate_user_with_bcrypt_upgrades_to_argon2(db: Session) -> None:
+    """Test that a user with bcrypt password hash gets upgraded to argon2 on login."""
+    email = random_email()
+    password = random_lower_string()
+
+    # Create a bcrypt hash directly (simulating legacy password)
+    bcrypt_hasher = BcryptHasher()
+    bcrypt_hash = bcrypt_hasher.hash(password)
+    assert bcrypt_hash.startswith("$2")  # bcrypt hashes start with $2
+
+    # Create user with bcrypt hash directly in the database
+    user = User(email=email, hashed_password=bcrypt_hash)
+    db.add(user)
+    db.commit()
+    db.refresh(user)
+
+    # Verify the hash is bcrypt before authentication
+    assert user.hashed_password.startswith("$2")
+
+    # Authenticate - this should upgrade the hash to argon2
+    authenticated_user = crud.authenticate(session=db, email=email, password=password)
+    assert authenticated_user
+    assert authenticated_user.email == email
+
+    db.refresh(authenticated_user)
+
+    # Verify the hash was upgraded to argon2
+    assert authenticated_user.hashed_password.startswith("$argon2")
+
+    verified, updated_hash = verify_password(
+        password, authenticated_user.hashed_password
+    )
+    assert verified
+    # Should not need another update since it's already argon2
+    assert updated_hash is None

backend/tests/scripts/test_backend_pre_start.py

@@ -0,0 +1,33 @@
+from unittest.mock import MagicMock, patch
+
+from sqlmodel import select
+
+from app.backend_pre_start import init, logger
+
+
+def test_init_successful_connection() -> None:
+    engine_mock = MagicMock()
+
+    session_mock = MagicMock()
+    session_mock.__enter__.return_value = session_mock
+
+    select1 = select(1)
+
+    with (
+        patch("app.backend_pre_start.Session", return_value=session_mock),
+        patch("app.backend_pre_start.select", return_value=select1),
+        patch.object(logger, "info"),
+        patch.object(logger, "error"),
+        patch.object(logger, "warn"),
+    ):
+        try:
+            init(engine_mock)
+            connection_successful = True
+        except Exception:
+            connection_successful = False
+
+        assert connection_successful, (
+            "The database connection should be successful and not raise an exception."
+        )
+
+        session_mock.exec.assert_called_once_with(select1)

backend/tests/scripts/test_test_pre_start.py

@@ -0,0 +1,33 @@
+from unittest.mock import MagicMock, patch
+
+from sqlmodel import select
+
+from app.tests_pre_start import init, logger
+
+
+def test_init_successful_connection() -> None:
+    engine_mock = MagicMock()
+
+    session_mock = MagicMock()
+    session_mock.__enter__.return_value = session_mock
+
+    select1 = select(1)
+
+    with (
+        patch("app.tests_pre_start.Session", return_value=session_mock),
+        patch("app.tests_pre_start.select", return_value=select1),
+        patch.object(logger, "info"),
+        patch.object(logger, "error"),
+        patch.object(logger, "warn"),
+    ):
+        try:
+            init(engine_mock)
+            connection_successful = True
+        except Exception:
+            connection_successful = False
+
+        assert connection_successful, (
+            "The database connection should be successful and not raise an exception."
+        )
+
+        session_mock.exec.assert_called_once_with(select1)

backend/tests/utils/item.py

@@ -0,0 +1,16 @@
+from sqlmodel import Session
+
+from app import crud
+from app.models import Item, ItemCreate
+from tests.utils.user import create_random_user
+from tests.utils.utils import random_lower_string
+
+
+def create_random_item(db: Session) -> Item:
+    user = create_random_user(db)
+    owner_id = user.id
+    assert owner_id is not None
+    title = random_lower_string()
+    description = random_lower_string()
+    item_in = ItemCreate(title=title, description=description)
+    return crud.create_item(session=db, item_in=item_in, owner_id=owner_id)

backend/tests/utils/user.py

@@ -0,0 +1,49 @@
+from fastapi.testclient import TestClient
+from sqlmodel import Session
+
+from app import crud
+from app.core.config import settings
+from app.models import User, UserCreate, UserUpdate
+from tests.utils.utils import random_email, random_lower_string
+
+
+def user_authentication_headers(
+    *, client: TestClient, email: str, password: str
+) -> dict[str, str]:
+    data = {"username": email, "password": password}
+
+    r = client.post(f"{settings.API_V1_STR}/login/access-token", data=data)
+    response = r.json()
+    auth_token = response["access_token"]
+    headers = {"Authorization": f"Bearer {auth_token}"}
+    return headers
+
+
+def create_random_user(db: Session) -> User:
+    email = random_email()
+    password = random_lower_string()
+    user_in = UserCreate(email=email, password=password)
+    user = crud.create_user(session=db, user_create=user_in)
+    return user
+
+
+def authentication_token_from_email(
+    *, client: TestClient, email: str, db: Session
+) -> dict[str, str]:
+    """
+    Return a valid token for the user with given email.
+
+    If the user doesn't exist it is created first.
+    """
+    password = random_lower_string()
+    user = crud.get_user_by_email(session=db, email=email)
+    if not user:
+        user_in_create = UserCreate(email=email, password=password)
+        user = crud.create_user(session=db, user_create=user_in_create)
+    else:
+        user_in_update = UserUpdate(password=password)
+        if not user.id:
+            raise Exception("User id not set")
+        user = crud.update_user(session=db, db_user=user, user_in=user_in_update)
+
+    return user_authentication_headers(client=client, email=email, password=password)