97 lines
3.9 KiB
Markdown
97 lines
3.9 KiB
Markdown
# 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.
|
|
|
|
## Frontend architecture
|
|
|
|
The frontend keeps ComfyUI-specific integration at the extension boundary in
|
|
`web/model_resolver.js` and composes the dialog behavior in
|
|
`web/resolver/resolver_dialog.js`. The dialog is assembled from focused method
|
|
groups:
|
|
|
|
1. `web/resolver/shell/` owns lifecycle, workflow identity, and tab state.
|
|
2. `web/resolver/search/` owns source selection, search state, aliases, and hash
|
|
matching.
|
|
3. `web/resolver/views/` owns view-specific state such as missing models and
|
|
model information.
|
|
4. `web/resolver/downloads/` owns queue storage and download progress policy.
|
|
5. `web/resolver/utils/` owns shared API, keybinding, and browser helpers.
|
|
|
|
Pure policies and state transitions are exported as small ES modules so they
|
|
can be tested without booting ComfyUI. The extension entry point and the dialog
|
|
composition are covered separately as integration contracts.
|
|
|
|
## 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
|
|
|
|
For frontend changes, run these commands from the project directory:
|
|
|
|
```powershell
|
|
npm test
|
|
npm run test:coverage
|
|
npm run lint
|
|
```
|
|
|
|
`test:coverage` uses Node's built-in test coverage reporter and prints the
|
|
current statement, branch, and function coverage. It is an inspection report,
|
|
not a hard threshold, because runtime-only ComfyUI adapters cannot be fully
|
|
exercised outside the host application.
|
|
|
|
## Pull request checks
|
|
|
|
The repository workflow lives in `.github/workflows/ci.yml`. It runs the
|
|
frontend and backend checks for pull requests whose source repository is
|
|
outside this repository, which keeps automated validation focused on external
|
|
contributions. It does not run for direct pushes to `main`; local changes by
|
|
the maintainer should use the verification commands above before committing.
|
|
|
|
The workflow uses the tracked `package-lock.json` with `npm ci`, has read-only
|
|
repository permissions, and does not require secrets. Its two jobs run:
|
|
|
|
1. `npm test` and `npm run lint` for the frontend.
|
|
2. `pytest`, Ruff, and `compileall` for the backend.
|
|
|
|
The workflow uses `pull_request`, not `pull_request_target`, so code from an
|
|
external fork is tested with the restricted pull-request token context.
|
|
|
|
Run these commands with the same Python interpreter used by ComfyUI:
|
|
|
|
```powershell
|
|
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.
|