Improve the documentation.

.gitignore

@@ -69,3 +69,5 @@ dist/
 *.doctree
 *.pot
 *.mo
+
+.codex

.pre-commit-config.yaml

@@ -0,0 +1,62 @@
+# 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: v4.4.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/build/.*
+            )$
+      - id: trailing-whitespace
+        exclude: ^frontend/src/client/.*
+  - 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-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/.*$|^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

.vscode/extensions.json

@@ -3,9 +3,12 @@
     "biomejs.biome",
     "bradlc.vscode-tailwindcss",
     "ms-python.debugpy",
-    "ms-python.python",
     "mechatroner.rainbow-csv",
     "redhat.vscode-yaml",
-    "ms-python.isort"
+    "ms-python.isort",
+    "charliermarsh.ruff",
+    "ms-python.vscode-python-envs",
+    "astral-sh.ty",
+    "tombi-toml.tombi"
   ]
 }

AGENTS.md

@@ -0,0 +1,7 @@
+Run Python commands inside the backend folder with uv run.
+
+Use pnpm inside the frontend folder.
+
+Always write type safe Python and strictly 3.14 syntax.
+
+frontend/src/lib/client should be generated by running `uv run app/scripts/generate_client.py` (inside of the backend folder) to generate the client after making changes to the API.

Makefile

@@ -19,3 +19,4 @@ frontend:
 
 backend:
 	cd backend && uv sync && uv run fastapi dev
+

README.md

@@ -22,6 +22,11 @@ Run common commands from the root of the project using `make`.
 > [!Important] 
 > Before running anything, first create the required `.env` files. See [environment variable documentation](https://opensacorg.github.io/app-capanel-doc/developer-guide/environment-variables).
 
+#### **TODO:** Improve environment variable documentation.
+
+- [ ] Add public/mock env files to the root and frontend folder.
+- [ ] Document in this README the commonly needed and missed environment variables that are required to first run.
+
 ### Backend documentation (Sphinx)
 
 `make reload`

backend/README.md

@@ -1,42 +1,58 @@
-# California Accountability Panel backend
+# California Accountability Panel back-end documentation
 
-This project is a copy of the main application backend, but there are slight differences. The goals are:
+This project is a copy of the main application back-end, but there are slight differences. The goals are:
 
-- A simpler development environment without Docker.
 - Use Sphinx to generate documentation with autodoc.
 - Test the project extensively, in more ways than with the main application.
+- A simpler development environment without Docker.
 
 > **Note:** This project must be manually kept in sync by copy-pasting files to and from the main application. See the [sync documentation](https://opensacorg.github.io/app-capanel-doc/developer-guide/documentation-repository-sync).
 
-## Overvie  w
-
-- [Developer Guide](https://opensacorg.github.io/app-capanel-doc/developer-guide/)
-- [Install](https://opensacorg.github.io/app-capanel-doc/developer-guide/install/)
-- [Development workflow](https://opensacorg.github.io/app-capanel-doc/developer-guide/development)
-- [Run application](https://opensacorg.github.io/app-capanel-doc/developer-guide/run-application)
-- [Testing](https://opensacorg.github.io/app-capanel-doc/developer-guide/testing)
-- [Extended backend/frontend README reference](https://opensacorg.github.io/app-capanel-doc/developer-guide/readme-reference)
-
-## Requirements
+## Prerequisites
 
 - [uv](https://docs.astral.sh/uv/)
 
-## Quickstart
+## Quick start
 
-First, install the backend dependencies.
+First, install the back-end dependencies.
 - `cd backend`
 - `uv sync`
 
 > [!Warning]
 > Before running anything, first create the required `.env` files. See [environment variable documentation](https://opensacorg.github.io/app-capanel-doc/developer-guide/environment-variables).
 
+> [!Note]
+> Python commands must be run from the backend folder. It is recommended to open the backend folders separately in VS Code. To run from the root of the project, it is recommended to use Make.  
+
+### Run the sphinx autoload
+
+```
+sphinx-autobuild docs/source docs/build/html
+```
+
+You can also run with Make. Be aware that this will create a .venv folder inside of backend/docs. This might be confusing.
+
+## Run the application
+
 ### Initialize the database
 
-If you haven't already done so, initialize the database. This will run the migrations and create a default super user.
+Initialize the database. This will run the migrations and create a default superuser.
 
-`uv run app/scripts/initial_data.py`
+```
+uv run app/scripts/initial_data.py
+```
 
 ### Start the local development server
-`uv run --env-file ../.env fastapi dev`
-or from the root of the project:
-`uv run --env-file .env fastapi dev backend\app\main.py`
+
+- From the backend folder: `uv run --env-file ../.env fastapi dev`
+- From the root of the project: `uv run fastapi dev backend/app/main.py`.
+
+
+## Resources
+
+- [Developer Guide](https://opensacorg.github.io/app-capanel-doc/developer-guide/)
+- [Install](https://opensacorg.github.io/app-capanel-doc/developer-guide/install/)
+- [Development workflow](https://opensacorg.github.io/app-capanel-doc/developer-guide/development)
+- [Run application](https://opensacorg.github.io/app-capanel-doc/developer-guide/run-application)
+- [Testing](https://opensacorg.github.io/app-capanel-doc/developer-guide/testing)
+- [Extended backend/frontend README reference](https://opensacorg.github.io/app-capanel-doc/developer-guide/readme-reference)

backend/app/alembic/env.py

@@ -3,32 +3,16 @@
 from alembic import context
 from sqlalchemy import engine_from_config, pool
 
-# this is the Alembic Config object, which provides
-# access to the values within the .ini file in use.
 config = context.config
-
-# Interpret the config file for Python logging.
-# This line sets up loggers basically.
-# mypy says config.config_file_name can be None, but Alembic always sets it.
 assert config.config_file_name is not None, "config_file_name is required"
 fileConfig(config.config_file_name)
 
-# add your model's MetaData object here
-# for 'autogenerate' support
-# from myapp import mymodel
-# target_metadata = mymodel.Base.metadata
-# target_metadata = None
-
-from app.model.models import SQLModel  # noqa
+from app.model.other import SQLModel  # noqa
+import app.model  # noqa
 from app.core.config import settings # noqa
 
 target_metadata = SQLModel.metadata
 
-# other values from the config, defined by the needs of env.py,
-# can be acquired:
-# my_important_option = config.get_main_option("my_important_option")
-# ... etc.
-
 
 def get_url():
     return str(settings.SQLALCHEMY_DATABASE_URI)
@@ -62,7 +46,7 @@ def run_migrations_online():
     and associate a connection with the context.
 
     """
-    configuration = config.get_section(config.config_ini_section)
+    configuration = config.get_section(config.config_ini_section) or {}
     configuration["sqlalchemy.url"] = get_url()
     connectable = engine_from_config(
         configuration,