# ufumzy/flownoteapp architecture

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

- Interactive diagram: https://gitdiagram.com/ufumzy/flownoteapp
- Repository: https://github.com/ufumzy/flownoteapp

## Overview

FlowNote is a desktop note-taking app built as an Electron application with a clear three-process boundary: Electron main process, preload bridge, and React renderer UI. The architecture is optimized around local note editing and window chrome control rather than a client/server backend.

1. **Top-level runtime split**
- **Main process**: app lifecycle, native window creation, packaging, and Electron-specific system integration.
- **Preload layer**: the only intended bridge between Node/Electron capabilities and the browser-like UI.
- **Renderer process**: the full user-facing application, implemented as a React single-page app.

2. **Main process responsibilities**
- `src/main/index.ts` is the entrypoint for Electron startup.
- `src/main/lib` likely holds window/setup helpers and any main-process utilities.
- This layer is the boundary for native behavior such as BrowserWindow setup, app events, splash/welcome handling, and packaging hooks.

3. **Preload as the security boundary**
- `src/preload/index.ts` exposes a limited API surface to the renderer.
- `src/preload/index.d.ts` provides TypeScript typing for that exposed API.
- This is the architectural boundary preventing direct renderer access to Node/Electron internals.

4. **Renderer as the product UI**
- `src/renderer` contains the React application and all note-taking UI.
- `src/renderer/src/App.tsx` and `main.tsx` bootstrap the app shell.
- The UI is organized around a custom layout, floating title area, window controls, note list sidebar, editor pane, search, and settings modal.

5. **Core note workflow**
- The primary interaction flow is: select or create a note, preview it in the sidebar, edit its Markdown/MDX content, and manage it through action buttons.
- `MarkdownEditor.tsx` is the central editing surface and likely wraps `@mdxeditor/editor`.
- `NotePreviewList.tsx`, `NotePreview.tsx`, `SearchInput.tsx`, `NewNoteButton.tsx`, and `DeleteNoteButton.tsx` form the note-management surface.

6. **State management**
- The app uses **Jotai** (`src/renderer/src/store`) for atomic state.
- `src/renderer/src/hooks/useNotesList.tsx` and `useMarkdownEditor.tsx` suggest stateful UI orchestration lives in hooks, not inside individual components.
- `store/mocks` indicates mocked store data or a development/test fallback path for rendering without real note data.

7. **Shared domain layer**
- `src/shared/constants.ts`, `models.ts`, and `types.ts` define cross-process contracts and app-wide data shapes.
- This shared layer is important because Electron apps often need consistent types between main, preload, and renderer.
- It likely contains note models, UI constants, and IPC-related types or enums.

8. **UI composition and layout**
- `AppLayout.tsx`, `DraggableTopBar.tsx`, `FloatingNoteTitle.tsx`, and `WindowControls.tsx` define the desktop-native shell.
- The app intentionally uses a custom draggable top bar instead of relying on default OS chrome.
- This is a key architectural feature because it changes how the window is drawn and how users interact with the app frame.

9. **Settings and customization**
- `SettingsModal.tsx` supports personalization, matching the README’s emphasis on background opacity, font colors, and sizes.
- Styling is handled with Tailwind and local CSS (`src/renderer/src/assets/index.css`), so visual customization is primarily renderer-side and theme-driven.

10. **Static resources and onboarding**
- `resources/splash.html` is a packaging/runtime asset for startup presentation.
- `resources/welcomeNote.md` suggests the app ships with a starter note or onboarding content.
- These resources support first-run and branding behavior without needing a backend.

11. **Build and packaging boundary**
- The repo uses **Vite** for the renderer and Electron tooling for multi-process builds.
- `electron.vite.config.ts` and `electron-builder.yml` indicate separate build orchestration for main, preload, and renderer, plus packaged app output for Windows/macOS/Linux.
- This is a desktop-distribution architecture, not a web deployment architecture.

12. **What is not present**
- There is no server, API layer, or database service visible in the tree.
- The app appears to be a self-contained local desktop client, with all product logic happening inside Electron and the renderer state layer.

For an architecture diagram, the main boxes should be: Electron main process, preload bridge, React renderer shell, note editor/listing UI, Jotai state/hooks, and shared types/constants, with packaging/build tooling as a separate supporting lane.

Main entry points: [`src/renderer/src/components/ActionButtonsRow.tsx`](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/ActionButtonsRow.tsx) (Note workspace), [`src/main/index.ts`](https://github.com/ufumzy/flownoteapp/blob/main/src/main/index.ts) (Main entry), [`src/renderer/src/store/index.ts`](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/store/index.ts) (State store), [`src/preload/index.ts`](https://github.com/ufumzy/flownoteapp/blob/main/src/preload/index.ts) (Preload bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_entry["Main entry<br/>electron main<br/>[index.ts]"]
  node_main_lib["Main helpers<br/>main utils<br/>[index.ts]"]
  node_preload_bridge["Preload bridge<br/>secure bridge<br/>[index.ts]"]
  node_preload_types["Bridge types<br/>api typings<br/>[index.d.ts]"]
end

subgraph group_ui["Renderer UI"]
  node_renderer_boot["App bootstrap<br/>react entry<br/>[main.tsx]"]
  node_app_shell["App shell<br/>react shell<br/>[App.tsx]"]
  node_layout_shell["Layout shell<br/>desktop chrome<br/>[AppLayout.tsx]"]
  node_top_bar["Top bar<br/>window chrome"]
  node_window_controls["Window controls<br/>chrome controls<br/>[WindowControls.tsx]"]
  node_note_workspace["Note workspace<br/>note ui"]
  node_note_list["Note list<br/>list view"]
  node_markdown_editor["Editor<br/>[MarkdownEditor.tsx]"]
  node_settings_modal["Settings<br/>preferences ui<br/>[SettingsModal.tsx]"]
  node_ui_hooks["UI hooks<br/>view hooks<br/>[useNotesList.tsx]"]
  node_store["State store<br/>jotai state<br/>[index.ts]"]
  node_store_mocks["Mock store<br/>mock data<br/>[index.ts]"]
end

subgraph group_shared["Shared Domain"]
  node_shared_models["Models<br/>domain model<br/>[models.ts]"]
  node_shared_types["Types<br/>[types.ts]"]
  node_shared_constants["Constants<br/>[constants.ts]"]
end

subgraph group_support["Support"]
  node_splash["Splash screen<br/>startup asset<br/>[splash.html]"]
  node_welcome_note["Welcome note<br/>starter content<br/>[welcomeNote.md]"]
  node_build_config["Build config<br/>packaging build"]
end

node_main_entry -->|"uses"| node_main_lib
node_main_entry -->|"loads"| node_preload_bridge
node_preload_bridge -->|"defines"| node_preload_types
node_renderer_boot -->|"mounts"| node_app_shell
node_app_shell -->|"composes"| node_layout_shell
node_layout_shell -->|"includes"| node_top_bar
node_layout_shell -->|"includes"| node_window_controls
node_app_shell -->|"renders"| node_note_workspace
node_note_workspace -->|"contains"| node_note_list
node_note_workspace -->|"contains"| node_markdown_editor
node_note_workspace -->|"opens"| node_settings_modal
node_ui_hooks -->|"orchestrates"| node_store
node_store -.->|"falls back to"| node_store_mocks
node_note_workspace -->|"uses"| node_ui_hooks
node_store -->|"shapes"| node_shared_models
node_store -->|"contracts"| node_shared_types
node_main_entry -->|"contracts"| node_shared_types
node_preload_bridge -->|"contracts"| node_shared_types
node_renderer_boot -->|"uses"| node_shared_constants
node_main_entry -->|"builds with"| node_build_config
node_build_config -->|"bundles"| node_splash
node_build_config -->|"bundles"| node_welcome_note

click node_main_entry "https://github.com/ufumzy/flownoteapp/blob/main/src/main/index.ts"
click node_main_lib "https://github.com/ufumzy/flownoteapp/blob/main/src/main/lib/index.ts"
click node_preload_bridge "https://github.com/ufumzy/flownoteapp/blob/main/src/preload/index.ts"
click node_preload_types "https://github.com/ufumzy/flownoteapp/blob/main/src/preload/index.d.ts"
click node_renderer_boot "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/main.tsx"
click node_app_shell "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/App.tsx"
click node_layout_shell "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/AppLayout.tsx"
click node_top_bar "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/DraggableTopBar.tsx"
click node_window_controls "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/WindowControls.tsx"
click node_note_workspace "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/ActionButtonsRow.tsx"
click node_note_list "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/NotePreviewList.tsx"
click node_markdown_editor "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/MarkdownEditor.tsx"
click node_settings_modal "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/SettingsModal.tsx"
click node_ui_hooks "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/hooks/useNotesList.tsx"
click node_store "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/store/index.ts"
click node_store_mocks "https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/store/mocks/index.ts"
click node_shared_models "https://github.com/ufumzy/flownoteapp/blob/main/src/shared/models.ts"
click node_shared_types "https://github.com/ufumzy/flownoteapp/blob/main/src/shared/types.ts"
click node_shared_constants "https://github.com/ufumzy/flownoteapp/blob/main/src/shared/constants.ts"
click node_splash "https://github.com/ufumzy/flownoteapp/blob/main/resources/splash.html"
click node_welcome_note "https://github.com/ufumzy/flownoteapp/blob/main/resources/welcomeNote.md"
click node_build_config "https://github.com/ufumzy/flownoteapp/blob/main/electron.vite.config.ts"

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_entry,node_main_lib,node_preload_bridge,node_preload_types toneBlue
class node_renderer_boot,node_app_shell,node_layout_shell,node_top_bar,node_window_controls,node_note_workspace,node_note_list,node_markdown_editor,node_settings_modal,node_ui_hooks,node_store,node_store_mocks toneAmber
class node_shared_models,node_shared_types,node_shared_constants toneMint
class node_splash,node_welcome_note,node_build_config toneRose
```

## Components

### Runtime

Electron runtime boundary split across main, preload, and renderer.

- [Main entry](https://github.com/ufumzy/flownoteapp/blob/main/src/main/index.ts): electron main · Starts Electron, manages app lifecycle, and creates native windows. · `src/main/index.ts`
- [Main helpers](https://github.com/ufumzy/flownoteapp/blob/main/src/main/lib/index.ts): main utils · Main-process helpers and setup logic. · `src/main/lib/index.ts`
- [Preload bridge](https://github.com/ufumzy/flownoteapp/blob/main/src/preload/index.ts): secure bridge · Exposes a limited API from Electron to the renderer. · `src/preload/index.ts`
- [Bridge types](https://github.com/ufumzy/flownoteapp/blob/main/src/preload/index.d.ts): api typings · TypeScript definitions for the preload-exposed API. · `src/preload/index.d.ts`

### Renderer UI

React application, note workflow, and desktop shell.

- [App bootstrap](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/main.tsx): react entry · Bootstraps the React renderer application. · `src/renderer/src/main.tsx`
- [App shell](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/App.tsx): react shell · Top-level application composition and page routing shell. · `src/renderer/src/App.tsx`
- [Layout shell](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/AppLayout.tsx): desktop chrome · Custom draggable window layout and frame composition. · `src/renderer/src/components/AppLayout.tsx`
- [Top bar](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/DraggableTopBar.tsx): window chrome · Draggable title area and window control surface. · `src/renderer/src/components/DraggableTopBar.tsx`
- [Window controls](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/WindowControls.tsx): chrome controls · Minimize, maximize, and close controls for the desktop window. · `src/renderer/src/components/WindowControls.tsx`
- [Note workspace](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/ActionButtonsRow.tsx): note ui · Primary note-management surface combining list, search, actions, and editor. · `src/renderer/src/components/ActionButtonsRow.tsx`
- [Note list](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/NotePreviewList.tsx): list view · Sidebar preview list for browsing and selecting notes. · `src/renderer/src/components/NotePreviewList.tsx`
- [Editor](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/MarkdownEditor.tsx): markdown editor · Central Markdown/MDX editing surface. · `src/renderer/src/components/MarkdownEditor.tsx`
- [Settings](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/components/SettingsModal.tsx): preferences ui · Customization modal for appearance and app preferences. · `src/renderer/src/components/SettingsModal.tsx`
- [UI hooks](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/hooks/useNotesList.tsx): view hooks · Stateful orchestration for notes and editor behavior. · `src/renderer/src/hooks/useNotesList.tsx`
- [State store](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/store/index.ts): jotai state · Atomic application state for notes and UI. · `src/renderer/src/store/index.ts`
- [Mock store](https://github.com/ufumzy/flownoteapp/blob/main/src/renderer/src/store/mocks/index.ts): mock data · Fallback or development note data for the store. · `src/renderer/src/store/mocks/index.ts`

### Shared Domain

Contracts and types shared across processes.

- [Models](https://github.com/ufumzy/flownoteapp/blob/main/src/shared/models.ts): domain model · Shared note and application data models. · `src/shared/models.ts`
- [Types](https://github.com/ufumzy/flownoteapp/blob/main/src/shared/types.ts): shared types · Cross-process TypeScript types and IPC-related contracts. · `src/shared/types.ts`
- [Constants](https://github.com/ufumzy/flownoteapp/blob/main/src/shared/constants.ts): shared constants · App-wide constants used across processes. · `src/shared/constants.ts`

### Support

Packaging assets and build orchestration.

- [Splash screen](https://github.com/ufumzy/flownoteapp/blob/main/resources/splash.html): startup asset · Packaged startup splash page. · `resources/splash.html`
- [Welcome note](https://github.com/ufumzy/flownoteapp/blob/main/resources/welcomeNote.md): starter content · Built-in onboarding or seed note content. · `resources/welcomeNote.md`
- [Build config](https://github.com/ufumzy/flownoteapp/blob/main/electron.vite.config.ts): packaging build · Electron and packaging configuration for app builds. · `electron.vite.config.ts`

## Connections

- Main entry → Main helpers: uses · Main startup delegates helper logic to main-process utilities.
- Main entry → Preload bridge: loads · Electron main loads the preload script into renderer windows.
- Preload bridge → Bridge types: defines · Preload implementation is paired with its exposed API typings.
- App bootstrap → App shell: mounts · Renderer entry mounts the application shell.
- App shell → Layout shell: composes · App shell is framed by the custom desktop layout.
- Layout shell → Top bar: includes · Layout includes the draggable title area.
- Layout shell → Window controls: includes · Layout includes native window control buttons.
- App shell → Note workspace: renders · The shell centers on the main note-taking workspace.
- Note workspace → Note list: contains · Workspace includes note browsing and selection.
- Note workspace → Editor: contains · Workspace includes the main editing surface.
- Note workspace → Settings: opens · Workspace can surface app settings and customization.
- UI hooks → State store: orchestrates · Hooks coordinate state access and update flow.
- State store → Mock store: falls back to · Store can use mock data for development or empty-state rendering.
- Note workspace → UI hooks: uses · Note UI relies on hooks for stateful behavior.
- State store → Models: shapes · State uses shared domain models for notes and app data.
- State store → Types: contracts · State and IPC flows rely on shared type contracts.
- Main entry → Types: contracts · Main process shares typed boundaries with preload and renderer.
- Preload bridge → Types: contracts · Preload bridge exposes typed capabilities to the renderer.
- App bootstrap → Constants: uses · Renderer bootstrapping consumes shared constants.
- Main entry → Build config: builds with · Electron entry is packaged through the build configuration.
- Build config → Splash screen: bundles · Build tooling includes the splash asset.
- Build config → Welcome note: bundles · Build tooling includes starter note content.