visible-unknown/scribecrop

1. Repository shape

- This is a two-target monorepo: web/ contains the actual image-annotation application, and desktop/ wraps the same app in Electron.

- The root package primarily coordinates shared scripts for development and build, while the feature logic lives almost entirely in web/src.

2. Primary product boundary: the web app

- The web application is a Next.js + React + TypeScript app.

- It is the “source of truth” for the editor UI, canvas interaction, crop generation, previewing, and export.

- The desktop app does not reimplement the editor; it loads the web build or local dev server.

3. Desktop boundary: Electron shell

- desktop/main.js is the Electron main-process entry point.

- Its role is to launch a native window around the web application, providing a desktop packaging/runtime layer rather than separate business logic.

- This means the architecture is “web app first, desktop wrapper second,” not two independent clients.

4. Application entry and layout

- In web/src/app, the Next.js App Router structure defines the top-level page and layout.

- layout.tsx, page.tsx, and the CSS files establish the shell that contains the editor surface and supporting panels.

- This is the UI composition boundary: everything else plugs into that page-level structure.

5. Core editing subsystem

- web/src/components/CanvasEditor.tsx is the central interaction surface.

- Based on the README and dependencies, this is where image regions are drawn, moved, resized, and rotated, likely using Konva for canvas scene management and transformer-style handles.

- This component is the primary stateful boundary between user gestures and crop/annotation data.

6. Image ingestion subsystem

- web/src/components/Dropzone.tsx and web/src/hooks/useImage.ts handle getting an image into the app.

- The flow is: user selects or drops an image, the hook normalizes image loading/state, and the editor receives a usable source image plus metadata.

- This boundary isolates file ingestion from the canvas/editor logic.

7. Crop data and region management

- web/src/types/index.ts defines the shared domain model for things like crop regions, image state, and editor-related entities.

- The crop regions are the central data structure linking drawing, preview, renaming, and export.

- The README’s emphasis on rectangles, squares, circles, and polygons suggests the data model supports multiple annotation shapes rather than only simple rectangular crops.

8. Preview and review subsystem

- web/src/components/PreviewPanel.tsx is the review layer for extracted regions.

- It likely shows the generated crops, labels, and ordering before export, making it the user-facing validation step between canvas editing and file export.

- This is a distinct boundary from the canvas: canvas edits the source image space, preview shows derived outputs.

9. Crop generation utilities

- web/src/utils/cropImage.ts and web/src/utils/exportCrops.ts are the processing layer.

- cropImage is responsible for turning a region definition plus source image into an actual cropped image representation.

- exportCrops packages the set of generated crops into downloadable output, and the README indicates ZIP export is the intended final artifact.

10. Naming and sequencing behavior

- The README’s “reactive renaming” capability implies the app maintains ordered crop metadata with prefix and numeric indexing.

- This behavior is important architecturally because export names are not just labels; they are part of the processing pipeline and likely update live as crop order changes.

- That makes naming a data transformation concern, not just a UI convenience.

11. Data flow through the system

- Typical flow: image input → loaded image state → canvas annotations → derived crop regions → preview generation → ZIP/export package.

- The crop regions are the handoff point between interactive editing and batch processing.

- The preview/export stages depend on the editor state but do not need the full interactive canvas once regions are finalized.

12. Styling and UI structure

- Styling is intentionally local and component-scoped via CSS Modules, with global styles only for app-wide baseline layout.

- This keeps the editor, dropzone, and preview panel visually isolated, which matters in a tool-heavy interface with multiple panes.

13. Tooling and runtime significance

- Next.js provides the web runtime and build/export pipeline; Electron provides desktop distribution; TypeScript adds shared model safety across components and utilities.

- Konva is a key architectural dependency because the editor is canvas-driven rather than DOM-drawn.

- Electron Builder is relevant only for packaging/distribution, not for the editor’s core runtime behavior.

14. What to draw in an architecture diagram

- Show one central web application box containing: image input, canvas editor, preview panel, crop utilities, and export pipeline.

- Show Electron as a thin outer host that launches the web app in desktop mode.

- Emphasize the one-way flow from user input to derived crop artifacts, with crop metadata shared across editor, preview, and export subsystems.