How handsupmin/mono-pix works
1. Project shape: MonoPix is a browser-only single-page app for pixel-art conversion and cleanup. There is no application server or API layer in the repo; the entire product runs in the client, with a Web Worker handling heavy image processing and IndexedDB handling local persistence.
2. Top-level runtime: The app is a React 19 + TypeScript application built with Vite. src/main.tsx boots the app, src/App.tsx assembles the feature flow, and src/components/MainLayout.tsx likely provides the overall shell, sidebar/main workspace split, and responsive layout.
3. Primary user workflow: The product flow is image import → optional crop → choose conversion mode/resolution → run processing → inspect preview/comparison → download result. This is reflected in the feature components: UploadZone, CropEditor, ControlPanel, PreviewArea, HistoryPanel, and shared action components like ConvertButton, ConfirmDialog, and TryDemoFab.
4. State management boundary: The app uses separate Zustand stores to isolate concerns:
- upload.store.ts for uploaded image/input state
- crop.store.ts for crop editor state
- conversion.store.ts for conversion parameters and processing status
- history.store.ts for recent outputs
- settings.store.ts for preferences such as theme or UI settings
This makes the UI mostly a set of consumers of shared state rather than deeply nested prop chains.
5. Processing boundary: Actual pixel conversion is offloaded to src/workers/pixelate.worker.ts. This is the key computational boundary: the UI sends image data and options to the worker, and the worker returns processed output. The README confirms that “all processing runs in a Web Worker,” so the architecture avoids blocking the main thread during image manipulation.
6. Conversion logic: The worker is backed by the fast-pixelizer engine mentioned in the README. The app supports two main conversion families:
- Snap: auto-detects a pixel grid and rebuilds uniform cells, preserving transparency
- Clean / Detail: converts arbitrary images to pixel art using either dominant-color or average-color reconstruction
The hook useConvert.ts is the UI-facing orchestration layer around this processing pipeline.
7. Cropping and preview interaction: react-easy-crop is likely used inside CropEditor.tsx for a 1:1 crop editor with drag/zoom. PreviewArea.tsx handles result presentation, including comparison modes described in the README (before/after/split and a magnifier for Snap results). This separates input shaping from output inspection.
8. Resolution and validation logic: useValidResolutions.ts suggests the app constrains output sizes to supported pixel-grid dimensions rather than arbitrary scaling. That matters architecturally because the conversion UI is not just “apply filter”; it must validate image size choices against the pixel-art engine’s supported ranges.
9. Persistence and history: src/lib/db.ts uses Dexie.js to store local data in IndexedDB, most likely for the “last 10 results” history described in the README. HistoryPanel.tsx is the UI surface for that persisted state. This is a client-side data boundary: history is durable on the device but never leaves the browser.
10. Internationalization and UI system: src/lib/i18n.ts plus locale JSON files under src/locales/* provide multilingual support for English, Korean, Japanese, Chinese, and Spanish. UI primitives in src/components/ui use the shadcn/ui pattern, with Tailwind CSS v4 handling styling. These choices mostly affect presentation rather than core data flow.
11. Static hosting and deployment: The presence of staticwebapp.config.json and an Azure Static Web Apps workflow indicates the app is deployed as a static front end with SPA routing support. That fits the architecture: build artifacts are served from static hosting, while all computation remains client-side.
12. Operational boundaries: There is no network dependency in the conversion path, so privacy and latency are largely determined by local device performance. The only “external” runtime dependencies are browser APIs, the worker thread, and local storage. This is an intentionally offline-first architecture centered on local image processing.
13. How to diagram it: The clearest architecture diagram should show:
- browser UI shell
- feature panels for upload/crop/control/preview/history
- central Zustand state stores
- a one-way message boundary to the pixelate Web Worker
- local persistence via Dexie/IndexedDB
- localization and shared UI primitives as supporting layers
There is no backend service to draw, which is itself an important architectural fact.
Main entry points: MainLayout.tsx Main layout · conversion.store.ts Conversion store · useConvert.ts Convert hook · button.tsx UI primitives
Components 20
Client runtime
Browser-based React SPA and its main UI composition.
- Entry point · Bootstraps the client app.
src/main.tsx - App shell · Assembles the top-level feature flow.
src/App.tsx - Main layout · Provides the main workspace and sidebar structure.
src/components/MainLayout.tsx
Feature panels
Primary user-facing workflow components for importing, editing, converting, and reviewing images.
- Upload zone · Handles image import and demo entry.
src/components/upload/UploadZone.tsx - Crop editor · Lets users frame the image before conversion.
src/components/crop/CropEditor.tsx - Control panel · Selects mode, size, and processing options.
src/components/sidebar/ControlPanel.tsx - Preview area · Shows before/after comparisons and magnified output.
src/components/preview/PreviewArea.tsx - History panel · Surfaces locally saved conversion results.
src/components/history/HistoryPanel.tsx - Actions · Shared conversion, dialog, loading, and demo controls.
State layer
Zustand stores and UI-facing orchestration hooks.
- Upload store · Tracks uploaded image and input state.
src/stores/upload.store.ts - Crop store · Tracks crop editor state and selection.
src/stores/crop.store.ts - Conversion store · Holds conversion options and processing status.
src/stores/conversion.store.ts - History store · Tracks recent results exposed in history.
src/stores/history.store.ts - Settings store · Stores preferences such as theme and UI settings.
src/stores/settings.store.ts
Processing engine
Worker-backed image conversion pipeline and validation helpers.
- Convert hook · Coordinates UI state with the worker conversion flow.
src/hooks/useConvert.ts - Resolution guard · Validates supported output sizes for pixel-art conversion.
src/hooks/useValidResolutions.ts - Pixel worker · Runs the heavy pixel conversion pipeline off the main thread.
src/workers/pixelate.worker.ts
Support systems
Persistence, localization, and reusable UI primitives.
- Local DB · Persists local history and other browser-only data.
src/lib/db.ts - Localization · Loads translation resources for supported languages.
src/lib/i18n.ts - UI primitives · Shared shadcn-style controls used across the app.
src/components/ui/button.tsx
Connections 24
- Entry point → App shell: mounts · The entry point renders the root application.
- App shell → Main layout: composes · The app is organized around the main shell.
- Main layout → Upload zone: hosts · The shell contains the import area.
- Main layout → Crop editor: hosts · The shell contains the crop editor.
- Main layout → Control panel: hosts · The shell contains conversion controls.
- Main layout → Preview area: hosts · The shell contains the preview surface.
- Main layout → History panel: hosts · The shell contains result history.
- Main layout → Actions: uses · Shared dialogs and actions are part of the shell.
- Upload zone → Upload store: reads/writes · Upload state is centralized in Zustand.
- Crop editor → Crop store: reads/writes · Crop state is centralized in Zustand.
- Control panel → Conversion store: reads/writes · Conversion settings and status live in shared state.
- Preview area → Conversion store: reads · Preview reflects current conversion state.
- History panel → History store: reads · History panel consumes recent results state.
- Actions → Conversion store: triggers · Convert and loading actions update processing state.
- Actions → Upload store: uses · Demo and confirm flows depend on input state.
- Convert hook → Conversion store: orchestrates · The hook coordinates processing state.
- Convert hook → Pixel worker: dispatches · Image data and options are sent to the worker.
- Convert hook → Resolution guard: validates · Requested sizes are checked before conversion.
- Pixel worker → Local DB: persists output · Processed results can be stored locally.
- History store → Local DB: loads/saves · History is backed by browser persistence.
- Localization → UI primitives: supports · Shared components render localized labels.
- Localization → App shell: provides text · The app consumes translation resources globally.
- UI primitives → Control panel: primitives · Controls are built from shared UI primitives.
- UI primitives → Preview area: primitives · Preview and dialogs reuse the shared component kit.