How katsu996/miro works
1. Overall shape
- This is a browser-only whiteboard app built with Next.js App Router + React + TypeScript.
- There is no backend API, auth service, or database. All application data lives in the user’s browser via LocalStorage.
2. Runtime boundary
- The app is designed to be stateless on the server and persistent only on the client.
- Deployment targets static hosting (GitHub Pages), so the architecture is essentially: static app bundle → browser → local persistence.
3. Application entry
- app/layout.tsx provides the root document structure and global styling.
- app/page.tsx is the main page entry and mounts the top-level React app from components/App.tsx.
4. Top-level UI composition
- components/App.tsx is the main orchestrator.
- It likely switches between the board dashboard and the active whiteboard editor, coordinating board selection and editor state.
5. Board management subsystem
- components/Dashboard.tsx represents the multi-board overview: create, rename, delete, and preview boards.
- The README indicates thumbnail previews, so the dashboard is the navigation/control layer for switching between boards.
6. Whiteboard editor subsystem
- components/Whiteboard.tsx is the core editing surface.
- It handles the infinite canvas, pan/zoom, selection, drawing, object manipulation, and the main interaction model.
- components/ItemView.tsx is the per-item rendering layer, separating generic board logic from rendering of individual items.
7. Content model
- lib/types.ts defines the board/item domain model: sticky notes, shapes, text boxes, pen strokes, connectors, selection state, and probably board metadata.
- lib/constants.ts centralizes shared defaults such as colors, sizes, tool modes, and editor constants.
- lib/utils.ts contains shared geometry and editor helpers, likely including hit testing, snapping, bounding-box math, and transformation logic.
8. Persistence and state flow
- lib/storage.ts is the persistence boundary and wraps LocalStorage access.
- Data flow is: user action → React state update → serialize to LocalStorage → reload/restore on next visit.
- Because storage is browser-local, boards are isolated per browser profile/device.
9. Rendering approach
- The README states the editor uses SVG-based drawing and does not rely on an external canvas library.
- That means shapes, connectors, text, and strokes are rendered as structured SVG elements rather than a third-party scene graph.
10. Interaction model
- The editor supports multiple tools: select, hand/pan, sticky note, shape, text, pen, and connector.
- Common operations include multi-select, move, resize, duplicate, delete, z-order changes, undo/redo, and clipboard actions.
- The architecture therefore centers on a single editor state machine that interprets mouse/touch/keyboard input into board mutations.
11. Connector and object coupling
- Connectors snap to shapes/stickies and follow them when endpoints move.
- This implies a dependency graph between connectors and attached items, handled inside the editor/utility layer rather than as a separate service.
12. Mobile and gesture support
- The same editor supports touch input, including one-finger interaction and two-finger pan/pinch zoom.
- This is important architecturally because input handling is unified across mouse, keyboard, and touch rather than split into separate apps.
13. Tooling and deployment
- next.config.ts plus the README’s “static export” setup indicate a build that outputs to out/ for static hosting.
- .github/workflows/deploy.yml automates build and deployment to GitHub Pages.
- scripts/smoke-test.mjs is a post-build validation step, likely checking that the exported site is usable before deployment.
14. Public hosting details
- public/.nojekyll is a GitHub Pages compatibility file, preventing Jekyll processing of the static export.
- The app is therefore intended to be served as a pure static artifact with no server-side rendering dependency at runtime.
Main entry points: Whiteboard.tsx Whiteboard · App.tsx App shell · ItemView.tsx Item view · deploy.yml Deploy workflow
Components 16
UI shell
Root app structure and top-level screen composition.
- Root layout · Defines the root document shell and global app structure.
app/layout.tsx - Main page · Top-level entry that mounts the application.
app/page.tsx - App shell · Coordinates dashboard vs active board and overall app state.
components/App.tsx - Global styles · Global styling for the application shell and editor.
app/globals.css
Whiteboard system
Dashboard and whiteboard editing surface.
- Dashboard · Board listing and management surface for create, rename, delete, and switching boards.
components/Dashboard.tsx - Whiteboard · Main infinite-canvas editor handling selection, pan/zoom, drawing, and object manipulation.
components/Whiteboard.tsx - Item view · Renders individual board items inside the editor.
components/ItemView.tsx - Icons · Shared icon set used across the interface.
components/Icons.tsx
Shared logic
Domain model, constants, utilities, and storage.
- Domain types · Shared board, item, tool, and selection data model definitions.
lib/types.ts - Constants · Shared defaults for tools, colors, sizes, and editor behavior.
lib/constants.ts - Utils · Shared math and editor helpers for hit testing, bounds, snapping, and transforms.
lib/utils.ts - Storage · Browser persistence boundary for saving and restoring boards.
lib/storage.ts
Build and deploy
Static export and GitHub Pages deployment.
- Next config · Configures Next.js for static export and hosting.
next.config.ts - Deploy workflow · Builds and deploys the exported site to GitHub Pages.
.github/workflows/deploy.yml - Smoke test · Validates the exported site after build.
scripts/smoke-test.mjs - .nojekyll · Prevents Jekyll processing on GitHub Pages.
public/.nojekyll
Connections 19
- Main page → App shell: mounts · Main page renders the application shell.
- Root layout → Global styles: loads · Root layout applies global styling.
- App shell → Dashboard: shows · Shell can present the board dashboard.
- App shell → Whiteboard: shows · Shell can present the active whiteboard editor.
- App shell → Storage: persists · Shell coordinates reading and writing boards in browser storage.
- Dashboard → Storage: reads/writes · Dashboard manages the board list in LocalStorage.
- Whiteboard → Domain types: uses · Editor operates on the shared board and item model.
- Whiteboard → Constants: uses · Editor relies on shared tool and visual defaults.
- Whiteboard → Utils: uses · Editor uses geometry and interaction helpers.
- Whiteboard → Storage: saves · Board edits are serialized back to browser storage.
- Whiteboard → Item view: renders · Editor delegates per-item drawing to item views.
- Item view → Domain types: uses · Item renderer depends on item definitions.
- Item view → Constants: uses · Item renderer uses shared presentation defaults.
- Item view → Icons: uses · Item renderer may share iconography with the UI.
- Utils → Domain types: uses · Helper logic works over shared model types.
- Deploy workflow → Next config: builds with · Deployment uses the Next.js static export configuration.
- Deploy workflow → Smoke test: verifies · Workflow runs a post-build smoke test before deploy.
- Deploy workflow → .nojekyll: publishes · GitHub Pages deployment includes the nojekyll marker.
- Next config → Main page: exports · Static build includes the app routes and page entry.