# handsupmin/mono-pix architecture

> Architecture diagram of the GitHub repository handsupmin/mono-pix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/handsupmin/mono-pix
- Repository: https://github.com/handsupmin/mono-pix

## Overview

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: [`src/components/MainLayout.tsx`](https://github.com/handsupmin/mono-pix/blob/main/src/components/MainLayout.tsx) (Main layout), [`src/stores/conversion.store.ts`](https://github.com/handsupmin/mono-pix/blob/main/src/stores/conversion.store.ts) (Conversion store), [`src/hooks/useConvert.ts`](https://github.com/handsupmin/mono-pix/blob/main/src/hooks/useConvert.ts) (Convert hook), [`src/components/ui/button.tsx`](https://github.com/handsupmin/mono-pix/blob/main/src/components/ui/button.tsx) (UI primitives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Client runtime"]
  node_main["Entry point<br/>React boot<br/>[main.tsx]"]
  node_app["App shell<br/>React composition<br/>[App.tsx]"]
  node_layout["Main layout<br/>UI shell<br/>[MainLayout.tsx]"]
end

subgraph group_features["Feature panels"]
  node_upload["Upload zone<br/>image input<br/>[UploadZone.tsx]"]
  node_crop["Crop editor<br/>crop UI<br/>[CropEditor.tsx]"]
  node_controls["Control panel<br/>conversion UI<br/>[ControlPanel.tsx]"]
  node_preview["Preview area<br/>result viewer<br/>[PreviewArea.tsx]"]
  node_history["History panel<br/>recent outputs<br/>[HistoryPanel.tsx]"]
  node_actions["Actions"]
end

subgraph group_state["State layer"]
  node_upload_store(("Upload store<br/>zustand store<br/>[upload.store.ts]"))
  node_crop_store(("Crop store<br/>zustand store<br/>[crop.store.ts]"))
  node_conversion_store(("Conversion store<br/>zustand store"))
  node_history_store(("History store<br/>zustand store<br/>[history.store.ts]"))
  node_settings_store(("Settings store<br/>zustand store<br/>[settings.store.ts]"))
end

subgraph group_processing["Processing engine"]
  node_use_convert(("Convert hook<br/>orchestration hook<br/>[useConvert.ts]"))
  node_resolutions(("Resolution guard<br/>validation hook"))
  node_worker[("Pixel worker<br/>web worker<br/>[pixelate.worker.ts]")]
end

subgraph group_support["Support systems"]
  node_db[("Local DB<br/>indexeddb store<br/>[db.ts]")]
  node_i18n["Localization<br/>i18n layer<br/>[i18n.ts]"]
  node_ui["UI primitives<br/>component kit<br/>[button.tsx]"]
end

node_main -->|"mounts"| node_app
node_app -->|"composes"| node_layout
node_layout -->|"hosts"| node_upload
node_layout -->|"hosts"| node_crop
node_layout -->|"hosts"| node_controls
node_layout -->|"hosts"| node_preview
node_layout -->|"hosts"| node_history
node_layout -->|"uses"| node_actions
node_upload -->|"reads/writes"| node_upload_store
node_crop -->|"reads/writes"| node_crop_store
node_controls -->|"reads/writes"| node_conversion_store
node_preview -->|"reads"| node_conversion_store
node_history -->|"reads"| node_history_store
node_actions -->|"triggers"| node_conversion_store
node_actions -->|"uses"| node_upload_store
node_use_convert -->|"orchestrates"| node_conversion_store
node_use_convert -->|"dispatches"| node_worker
node_use_convert -->|"validates"| node_resolutions
node_worker -.->|"persists output"| node_db
node_history_store -->|"loads/saves"| node_db
node_i18n -.->|"supports"| node_ui
node_i18n -.->|"provides text"| node_app
node_ui -.->|"primitives"| node_controls
node_ui -.->|"primitives"| node_preview

click node_main "https://github.com/handsupmin/mono-pix/blob/main/src/main.tsx"
click node_app "https://github.com/handsupmin/mono-pix/blob/main/src/App.tsx"
click node_layout "https://github.com/handsupmin/mono-pix/blob/main/src/components/MainLayout.tsx"
click node_upload "https://github.com/handsupmin/mono-pix/blob/main/src/components/upload/UploadZone.tsx"
click node_crop "https://github.com/handsupmin/mono-pix/blob/main/src/components/crop/CropEditor.tsx"
click node_controls "https://github.com/handsupmin/mono-pix/blob/main/src/components/sidebar/ControlPanel.tsx"
click node_preview "https://github.com/handsupmin/mono-pix/blob/main/src/components/preview/PreviewArea.tsx"
click node_history "https://github.com/handsupmin/mono-pix/blob/main/src/components/history/HistoryPanel.tsx"
click node_upload_store "https://github.com/handsupmin/mono-pix/blob/main/src/stores/upload.store.ts"
click node_crop_store "https://github.com/handsupmin/mono-pix/blob/main/src/stores/crop.store.ts"
click node_conversion_store "https://github.com/handsupmin/mono-pix/blob/main/src/stores/conversion.store.ts"
click node_history_store "https://github.com/handsupmin/mono-pix/blob/main/src/stores/history.store.ts"
click node_settings_store "https://github.com/handsupmin/mono-pix/blob/main/src/stores/settings.store.ts"
click node_use_convert "https://github.com/handsupmin/mono-pix/blob/main/src/hooks/useConvert.ts"
click node_resolutions "https://github.com/handsupmin/mono-pix/blob/main/src/hooks/useValidResolutions.ts"
click node_worker "https://github.com/handsupmin/mono-pix/blob/main/src/workers/pixelate.worker.ts"
click node_db "https://github.com/handsupmin/mono-pix/blob/main/src/lib/db.ts"
click node_i18n "https://github.com/handsupmin/mono-pix/blob/main/src/lib/i18n.ts"
click node_ui "https://github.com/handsupmin/mono-pix/blob/main/src/components/ui/button.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_layout toneBlue
class node_upload,node_crop,node_controls,node_preview,node_history,node_actions toneAmber
class node_upload_store,node_crop_store,node_conversion_store,node_history_store,node_settings_store toneMint
class node_use_convert,node_resolutions,node_worker toneRose
class node_db,node_i18n,node_ui toneIndigo
```

## Components

### Client runtime

Browser-based React SPA and its main UI composition.

- [Entry point](https://github.com/handsupmin/mono-pix/blob/main/src/main.tsx): React boot · Bootstraps the client app. · `src/main.tsx`
- [App shell](https://github.com/handsupmin/mono-pix/blob/main/src/App.tsx): React composition · Assembles the top-level feature flow. · `src/App.tsx`
- [Main layout](https://github.com/handsupmin/mono-pix/blob/main/src/components/MainLayout.tsx): UI shell · 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](https://github.com/handsupmin/mono-pix/blob/main/src/components/upload/UploadZone.tsx): image input · Handles image import and demo entry. · `src/components/upload/UploadZone.tsx`
- [Crop editor](https://github.com/handsupmin/mono-pix/blob/main/src/components/crop/CropEditor.tsx): crop UI · Lets users frame the image before conversion. · `src/components/crop/CropEditor.tsx`
- [Control panel](https://github.com/handsupmin/mono-pix/blob/main/src/components/sidebar/ControlPanel.tsx): conversion UI · Selects mode, size, and processing options. · `src/components/sidebar/ControlPanel.tsx`
- [Preview area](https://github.com/handsupmin/mono-pix/blob/main/src/components/preview/PreviewArea.tsx): result viewer · Shows before/after comparisons and magnified output. · `src/components/preview/PreviewArea.tsx`
- [History panel](https://github.com/handsupmin/mono-pix/blob/main/src/components/history/HistoryPanel.tsx): recent outputs · Surfaces locally saved conversion results. · `src/components/history/HistoryPanel.tsx`
- **Actions**: shared actions · Shared conversion, dialog, loading, and demo controls.

### State layer

Zustand stores and UI-facing orchestration hooks.

- [Upload store](https://github.com/handsupmin/mono-pix/blob/main/src/stores/upload.store.ts): zustand store · Tracks uploaded image and input state. · `src/stores/upload.store.ts`
- [Crop store](https://github.com/handsupmin/mono-pix/blob/main/src/stores/crop.store.ts): zustand store · Tracks crop editor state and selection. · `src/stores/crop.store.ts`
- [Conversion store](https://github.com/handsupmin/mono-pix/blob/main/src/stores/conversion.store.ts): zustand store · Holds conversion options and processing status. · `src/stores/conversion.store.ts`
- [History store](https://github.com/handsupmin/mono-pix/blob/main/src/stores/history.store.ts): zustand store · Tracks recent results exposed in history. · `src/stores/history.store.ts`
- [Settings store](https://github.com/handsupmin/mono-pix/blob/main/src/stores/settings.store.ts): zustand 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](https://github.com/handsupmin/mono-pix/blob/main/src/hooks/useConvert.ts): orchestration hook · Coordinates UI state with the worker conversion flow. · `src/hooks/useConvert.ts`
- [Resolution guard](https://github.com/handsupmin/mono-pix/blob/main/src/hooks/useValidResolutions.ts): validation hook · Validates supported output sizes for pixel-art conversion. · `src/hooks/useValidResolutions.ts`
- [Pixel worker](https://github.com/handsupmin/mono-pix/blob/main/src/workers/pixelate.worker.ts): web 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](https://github.com/handsupmin/mono-pix/blob/main/src/lib/db.ts): indexeddb store · Persists local history and other browser-only data. · `src/lib/db.ts`
- [Localization](https://github.com/handsupmin/mono-pix/blob/main/src/lib/i18n.ts): i18n layer · Loads translation resources for supported languages. · `src/lib/i18n.ts`
- [UI primitives](https://github.com/handsupmin/mono-pix/blob/main/src/components/ui/button.tsx): component kit · Shared shadcn-style controls used across the app. · `src/components/ui/button.tsx`

## Connections

- 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.
