Azornes-Comfyui-Model-Resolver/docs/architecture.md

Backend architecture

Model Resolver keeps the ComfyUI entry point small and separates HTTP wiring from the feature logic that powers each route.

Runtime flow

1. __init__.py exposes the ComfyUI compatibility exports and initializes the extension.
2. core/extension.py owns runtime state such as progress trackers and starts route registration.
3. core/routes/registry.py loads the available integrations and builds a RouteContext with explicit dependencies.
4. Modules in core/routes/ adapt HTTP requests and responses to service calls.
5. Services in core/services/ contain feature behavior and receive their dependencies through RouteContext.

Route registration imports the concrete route modules directly. The actual handlers live in focused route adapters and services; no compatibility grouping layer is kept for this application-only package.

Adding a route

When adding a feature, keep the request parsing, status codes, and JSON response in a route adapter. Put reusable behavior in a service and add its dependency to RouteContext explicitly. Use json_api_endpoint for the common error boundary, and preserve deliberate aiohttp.web.HTTPException statuses when returning client errors.

Add a focused route/service test before changing behavior. For changes that touch route registration or shared backend code, run the complete Python suite as well.

Local verification

Run these commands with the same Python interpreter used by ComfyUI:

python -m pytest
python -m ruff check __init__.py core
python -m compileall -q __init__.py core
python -m coverage run -m pytest
python -m coverage report -m

The development tools are declared in the dev optional dependency group in pyproject.toml. Coverage configuration is kept there as well, with branch coverage enabled and core/ as the measured source.