igny8/master-docs/30-frontend/writer/IMAGE-EDITOR.md

Image Editor Page (Images List & Generation)

Purpose

Manage generated images linked to writer content: list images grouped by content, filter/search, trigger generation, update statuses, and download/view images. Uses table template patterns similar to content/tasks.

Code Locations (exact paths)

• Page: frontend/src/pages/Writer/Images.tsx
• API: frontend/src/services/api (fetchContentImages, fetchImageGenerationSettings, generateImages, bulkUpdateImagesStatus, deleteContent, bulkDeleteContent)
• Config: frontend/src/config/pages/images.config (columns/filters)
• UI components: frontend/src/components/common/ImageQueueModal, frontend/src/components/common/SingleRecordStatusUpdateModal, frontend/src/components/common/PageHeader, frontend/src/components/navigation/ModuleNavigationTabs, frontend/src/components/ui/modal
• Hooks: frontend/src/hooks/useResourceDebug (AI logs toggle), frontend/src/hooks/useProgressModal (via modal usage pattern)

High-Level Responsibilities

• Fetch and render content-image groups with client-side filtering/search/sorting/pagination.
• Trigger image generation for selected content with queue modal and provider/model selection.
• Update image status in bulk and delete images/content.
• Provide AI function log visibility when resource debug is enabled.

Detailed Behavior

• Data load: loadImages calls fetchContentImages({}), applies client-side search (content_title) and status filter (overall_status), sorts (default content_title), paginates client-side (page size 10), and adds id field mirroring content_id for selection.
• Filters: search text; status dropdown; sort controls; pagination tracked in local state.
• Actions:
  • Generate images: opens ImageQueueModal, builds queue items, calls generateImages with provider/model; tracks taskId/model/provider state; shows AI logs when resource debug enabled.
  • Bulk status update: bulkUpdateImagesStatus on selected ids.
  • Delete (single/bulk): uses deleteContent/bulkDeleteContent.
  • Download/view: handled by row actions in config (template-driven).
• Navigation: writer tabs rendered via ModuleNavigationTabs (Queue/Drafts/Images/Review/Published).
• Resource debug: AI logs captured only when useResourceDebug returns true; addAiLog appends logs for visibility.
• Loading UX: loading + showContent gating; debounced search resets page as needed.

Data Structures / Models Involved (no code)

• ContentImagesGroup: content_id, content_title, overall_status, images[].
• ContentImage: individual image entries with URL/status/prompt (from API).
• Generation settings: provider/model options from fetchImageGenerationSettings.

Execution Flow

• useEffect → loadImages.
• Filters/sort/page changes → recompute client-side subsets.
• Generate action → open modal → call generateImages → optionally log steps → reload images.
• Status update/delete actions → call API → reload.

Cross-Module Interactions

• Tied to writer content records; delete actions use writer content endpoints.
• AI generation leverages shared API endpoints that consume credits server-side.

State Transitions

• loading/showContent manage render timing; modal open states for queue/status/image viewer.
• aiLogs maintained only when debug is enabled.

Error Handling

• Toast errors for load/generate/update/delete; generation errors also recorded in AI logs when enabled.
• Debounced search handles errors gracefully by keeping prior data until reload.

Tenancy Rules

• Backend enforces account/site/sector; client passes no explicit tenant fields beyond any default filters in API layer.

Billing Rules (if applicable)

• Image generation consumes credits on backend; page performs no credit gating.

Background Tasks / Schedulers (if applicable)

• None; generation is user-triggered, and polling is not used here.

Key Design Considerations

• Client-side pagination used because API returns grouped images; keeps UI responsive without extra endpoints.
• Resource debug toggle avoids unnecessary log storage unless explicitly enabled.

How Developers Should Work With This Module

• If server adds server-side pagination/filtering, remove client-side slicing and pass filters to API.
• Extend row actions by updating images.config with handlers wired to new behaviors.
• Keep generation flow in sync with backend provider/model options; surface credit estimates if backend exposes them.