# Backend development and compatibility

The FastAPI project lives entirely in `vocero-api/`. It uses uv 0.12.5, Python
3.12, and a committed `uv.lock`. The frontend and speech pipeline keep their
own tooling. Runtime dependency versions match the environment used to capture
the pre-migration server; framework upgrades require a separate compatibility
review.

The Python distribution is named `vocero-api`, and its import package is
`vocero_api`. The browser package and directory are both named `vocero-frontend`.
`start_ui.sh` creates the API environment at its current path on the next start;
do not move an existing virtual environment because its executables contain
absolute paths. Reinstall optional Git hooks after a project-directory rename
with `make -C vocero-api hooks-install`.

Pytest filters only the known `anyio.abc.BlockingPortal` deprecation emitted by
Starlette's test client ([upstream issue](https://github.com/Kludex/starlette/issues/3497)).
The filter matches the exact message, warning category, and module; other
warnings remain visible. Remove it when a compatible Starlette upgrade replaces
the deprecated alias. Runtime dependencies and warning handling are unchanged.

## Commands

From the repository root:

```bash
make -C vocero-api install       # uv sync --locked, including development tools
make -C vocero-api format        # Ruff safe fixes and formatting
make -C vocero-api check         # lock freshness, format, lint, mypy, pytest
make -C vocero-api test-launcher # Bash supervisor integration fixtures
make -C vocero-api test-image    # Docker build and isolated runtime smoke test
```

Run `uv lock` inside `vocero-api/` when intentionally changing dependencies.
Do not install server packages into a shared root environment. The launcher
syncs `vocero-api/.venv` and retains root `.env` loading, port defaults,
readiness checks, and process-group shutdown. Offline starts require the
locked packages and Python runtime to have been installed or cached already.

Optional hooks use `make -C vocero-api hooks-install`; the configuration stays
in `vocero-api/.pre-commit-config.yaml`. `make -C vocero-api hooks-run` runs the
same hooks without installing them. Hooks and Python quality checks apply
only to the client service. The server entry points are `vocero_api.main:app`
and the retained `server:app` shim; use `--app-dir vocero-api` from the root.

## Schema boundaries

`models/requests.py` retains the existing search, reasoning, and ApiPilot
request models, including their defaults, coercion, and ignored extra fields.
The queue beacon still accepts malformed JSON and non-object bodies as before;
its Pydantic view is applied only after the original object check, and
`queueId` remains unconstrained.

`models/responses.py` validates structure constructed by this server. Fields
owned by external services remain `Any` where the old parser imposed no type
constraint. Object models allow extra fields. Caller profiles can be arbitrary
JSON; load-balancer fields remain optional; execution results and error details
remain open. Existing provider parsing, authentication precedence, argument
filtering, environment parsing, and WebSocket frames are unchanged.

HTTP handlers call `validated_json_response`: Pydantic validates the payload,
then `JSONResponse` serializes the original object. Returning a dumped model
would insert defaults or change values/key order, so do not replace this helper
with model serialization without a contract review. Route `response_model`
declarations publish the new response schemas in OpenAPI. Existing request
schemas and validation errors remain unchanged. HTTP exceptions retain their
existing error shapes; there is no new common error envelope.

## Compatibility evidence

`tests/fixtures/legacy-contracts.json` was captured from the original monolithic
server at commit `3d42df5`, before refactoring. Tests compare 82 HTTP scenarios,
including exact response text, statuses, selected headers, and outgoing mock
HTTP requests. They also compare request OpenAPI definitions and representative
realtime frames. Additional tests cover response validation and permissive
upstream values; the original local HTTP/WebSocket tests remain in the suite.
Four captures belonging exclusively to the retired workflow reasoning service
were removed with that integration; all retained captures are unchanged.

The captures deliberately preserve unknown fields, omitted fields, unusual JSON
values, queue beacon edge cases, permissive tool arguments, and known failures.
Examples include reasoning's existing uninitialized local variables in certain
configuration combinations, API-key-only tool precheck behavior, the catalog
cache's existing key, and relay termination after a suppressed invalid
`session.update` error. Fix those in separately reviewed behavior changes;
do not regenerate golden captures to make a refactor pass.

These checks use local fixtures and do not claim exhaustive coverage of all
provider responses, live speech models, or production configuration. No deployed
services or real credentials are needed. The Docker check verifies the actual
runtime image, API configuration, documentation, OpenAPI, and the backend's
existing root 404; it removes its temporary container and image afterward.