docs(ui): more documentation

Author: psychedelicious

invokeai/frontend/web/src/features/ui/README.md

@@ -0,0 +1,26 @@
+# UI/Layout
+
+We use https://github.com/mathuo/dockview for layout. This library supports resizable and dockable panels. Users can drag and drop panels to rearrange them.
+
+The intention when adopting this library was to allow users to create their own custom layouts and save them. However, this feature is not yet implemented and each tab only has a predefined layout.
+
+This works well, but it _is_ fairly complex. You can see that we've needed to write a fairly involved API to manage the layouts: invokeai/frontend/web/src/features/ui/layouts/navigation-api.ts
+
+And the layouts themselves are awkward to define, especially when compared to plain JSX: invokeai/frontend/web/src/features/ui/layouts/generate-tab-auto-layout.tsx
+
+This complexity may or may not be worth it.
+
+## Previous approach
+
+Previously we used https://github.com/bvaughn/react-resizable-panels and simple JSX components.
+
+This library is great except it doesn't support absolute size constraints, only relative/percentage constraints. We had a brittle abstraction layer on top of it to try to enforce minimum pixel sizes for panels but it was janky and had FP precision issues causing drifting sizes.
+
+It also doesn't support dockable panels.
+
+## Future possibilities
+
+1. Continue with dockview and implement custom layout saving/loading. We experimented with this and it was _really_ nice. We defined a component for each panel type and use react context to manage state. But we thought that it would be confusing for most users, so we flagged it for a future iteration and instead shipped with predefined layouts.
+2. Switch to a simpler layout library or roll our own.
+
+In hindsight, we should have skipped dockview and found something else that was simpler until we were ready to invest in custom layouts.

invokeai/frontend/web/src/services/api/README.md

@@ -0,0 +1,20 @@
+# API
+
+The API client is a fairly standard Redux Toolkit Query (RTK-Query) setup.
+
+It defines a simple base query with special handling for OpenAPI schema queries and endpoints: invokeai/frontend/web/src/services/api/index.ts
+
+## Types
+
+The API provides an OpenAPI schema and we generate TS types from it. They are stored in: invokeai/frontend/web/src/services/api/schema.ts
+
+We use https://github.com/openapi-ts/openapi-typescript/ to generate the types.
+
+- Python script to outut the OpenAPI schema: scripts/generate_openapi_schema.py
+- Node script to call openapi-typescript and generate the TS types: invokeai/frontend/web/scripts/typegen.js
+
+Pipe the output of the python script to the node script to update the types. There is a `make` target that does this in one fell swoop (after activating venv): `make frontend-typegen`
+
+Alternatively, start the ptyhon server and run `pnpm typegen`.
+
+The schema.ts file is pushed to the repo, and a CI check ensures it is up to date.

invokeai/frontend/web/src/services/events/onInvocationComplete.tsx

@@ -26,8 +26,18 @@ import type { JsonObject } from 'type-fest';
 
 const log = logger('events');
 
+// These nodes are passthrough nodes. They do not add images to the gallery, so we must skip that handling for them.
 const nodeTypeDenylist = ['load_image', 'image'];
 
+/**
+ * Builds the socket event handler for invocation complete events. Adds output images to the gallery and/or updates
+ * node execution states for the workflow editor.
+ *
+ * @param getState The Redux getState function.
+ * @param dispatch The Redux dispatch function.
+ * @param finishedQueueItemIds A cache of finished queue item IDs to prevent duplicate handling and avoid race
+ * conditions that can happen when a graph finishes very quickly.
+ */
 export const buildOnInvocationComplete = (
   getState: AppGetState,
   dispatch: AppDispatch,

invokeai/frontend/web/src/services/events/onModelInstallError.tsx

@@ -39,6 +39,9 @@ const getHFTokenStatus = async (dispatch: AppDispatch): Promise<S['HFTokenStatus
   }
 };
 
+/**
+ * Handles model install error events by logging the error, displaying appropriate toast notifications.
+ */
 export const buildOnModelInstallError = (getState: AppGetState, dispatch: AppDispatch) => {
   return async (data: S['ModelInstallErrorEvent']) => {
     log.error({ data }, 'Model install error');

invokeai/frontend/web/src/services/events/setEventListeners.tsx

@@ -33,6 +33,10 @@ type SetEventListenersArg = {
 
 const selectModelInstalls = modelsApi.endpoints.listModelInstalls.select();
 
+/**
+ * Sets up event listeners for the socketio client. Some components will set up their own listeners. These are the ones
+ * that have app-wide implications.
+ */
 export const setEventListeners = ({ socket, store, setIsConnected }: SetEventListenersArg) => {
   const { dispatch, getState } = store;