# jydv402/memno architecture

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

- Interactive diagram: https://gitdiagram.com/jydv402/memno
- Repository: https://github.com/jydv402/memno

## Overview

1. **Project type and runtime**
   - Memno is a **Flutter/Dart client application** with a shared codebase targeting **Android** and **Windows** as the primary platforms.
   - The repository also contains standard Flutter scaffolding for **iOS, macOS, Linux, and Web**, but the product focus is clearly on mobile + desktop.

2. **Top-level architecture**
   - The app is organized into three main layers:
     - **UI layer** in `lib/mobile` and `lib/desktop`
     - **Logic/data layer** in `lib/logic`
     - **Platform shells** in `android/`, `ios/`, `macos/`, `linux/`, `windows/`, and `web/`
   - This is a **local-first offline app**, not a backend-driven system.

3. **Application entry and platform split**
   - `lib/main.dart` is the entry point and likely decides which experience to launch based on platform.
   - The app has two distinct UI shells:
     - **Mobile flow** centered around `home.dart` and `lib/mobile/...`
     - **Desktop flow** centered around `lib/desktop/desktop_shell.dart` and desktop pages/components

4. **Mobile UI subsystem**
   - `lib/mobile/components` contains reusable mobile surfaces such as:
     - inner page navigation
     - settings page
     - share-target handling
     - toast feedback
     - subtile/list item widgets
   - `lib/mobile/home.dart` is the main mobile landing experience.
   - The mobile side is optimized for compact navigation and sharing/importing content into the app.

5. **Desktop UI subsystem**
   - `lib/desktop` provides a dedicated widescreen experience with:
     - a **dock/sidebar**
     - a **search overlay**
     - desktop note pages
     - settings pages
     - specialized cards/tiles/notifications
   - This side is explicitly tailored for keyboard-driven navigation and productivity workflows.

6. **Data model and persistence**
   - `lib/logic/database` contains Hive-backed persisted models:
     - `code_data`
     - `preview_data`
     - `toggles_data`
   - The presence of generated `.g.dart` files indicates **Hive type adapters** and strongly suggests **local on-device storage** as the system of record.
   - The app stores notes, links, preview metadata, and user toggles/settings locally for offline access.

7. **Core functional services**
   - `lib/logic/functionality` holds the non-UI application services:
     - `code_gen.dart` for generating the unique **6-digit access codes**
     - `preview_map.dart` and related utilities for metadata/preview extraction and mapping
     - `link_utils.dart` for URL handling
     - `import_export.dart` for moving data in and out of the app
     - `check_update.dart` for release/update checks
   - These services form the main business logic boundary between UI and persistence.

8. **Primary data flow**
   - The main user flow is:
     1. User saves a link and adds a note
     2. Link utilities normalize/inspect the URL
     3. Metadata/preview logic fetches or maps title/description/image
     4. A 6-digit code is generated
     5. The record is stored in Hive
     6. Mobile or desktop UI reads from the same local store to render cards, search results, or detail pages
   - Because the app is offline-first, read and write paths stay local after the initial metadata fetch.

9. **Cross-cutting UI concerns**
   - `lib/logic/theme/app_colors.dart` centralizes color/theme definitions.
   - The README also calls out **dark mode support**, so theme selection is part of the shared app shell rather than isolated to one screen.
   - Settings/toggles are persisted separately so UI preferences survive restarts.

10. **Share/import and external entry points**
   - The mobile folder includes a **share-target page**, which suggests the app can receive links from the OS share sheet and convert them into saved entries.
   - `import_export.dart` provides another integration boundary for transferring library data without a server.

11. **Platform integration**
   - Each native folder is the standard Flutter embedder layer for its platform:
     - Android uses Kotlin `MainActivity`
     - iOS/macOS use Swift app delegates and Xcode projects
     - Windows uses the C++ runner/installer stack
     - Linux uses a C++/CMake runner
   - These folders mostly wrap the shared Flutter runtime; the app’s actual product logic remains in `lib/`.

12. **Packaging and distribution**
   - The repository includes **Fastlane metadata** for Android store/release packaging and a **Windows installer script** under `windows/installer.iss`.
   - Assets such as icons, branding images, screenshots, and fonts are bundled for app presentation and distribution, not core behavior.

13. **Testing and CI**
   - `test/widget_test.dart` provides Flutter test coverage.
   - `.github/workflows/main.yml` indicates CI automation for build/test validation.
   - This is a relatively lightweight test surface compared with the app itself, so runtime architecture remains centered on the shared Flutter client.

14. **Diagram takeaway**
   - If you are drawing the architecture, the key boxes are:
     - **Flutter app shell**
     - **Mobile UI**
     - **Desktop UI**
     - **Local Hive storage**
     - **Link/preview/code-generation services**
     - **Platform wrappers and packaging**
   - The main arrows are:
     - user interaction → UI → logic services → local database
     - share/import/update-related flows feeding into the same logic layer
     - shared data store powering both mobile and desktop experiences

Main entry points: [`lib/main.dart`](https://github.com/jydv402/memno/blob/main/lib/main.dart) (Main entry), [`lib/desktop/pages`](https://github.com/jydv402/memno/tree/main/lib/desktop/pages) (Desktop pages), [`lib/logic/database/code_data.dart`](https://github.com/jydv402/memno/blob/main/lib/logic/database/code_data.dart) (Code data), [`lib/logic/database/preview_data.dart`](https://github.com/jydv402/memno/blob/main/lib/logic/database/preview_data.dart) (Preview data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_app["Flutter app"]
  node_n_main["Main entry<br/>dart entrypoint<br/>[main.dart]"]
  node_n_mobile_home["Mobile home<br/>mobile shell<br/>[home.dart]"]
  node_n_mobile_components["Mobile components<br/>ui components"]
  node_n_desktop_shell["Desktop shell<br/>[desktop_shell.dart]"]
  node_n_desktop_pages["Desktop pages<br/>desktop views"]
  node_n_desktop_components["Desktop components<br/>desktop widgets"]
end

subgraph group_grp_logic["Core logic"]
  node_n_code_data[("Code data<br/>hive model<br/>[code_data.dart]")]
  node_n_preview_data[("Preview data<br/>hive model<br/>[preview_data.dart]")]
  node_n_toggles_data[("Toggles data<br/>hive model<br/>[toggles_data.dart]")]
  node_n_code_gen{{"Code gen<br/>[code_gen.dart]"}}
  node_n_link_utils{{"Link utils<br/>[link_utils.dart]"}}
  node_n_preview_map{{"Preview map<br/>[preview_map.dart]"}}
  node_n_import_export{{"Import export<br/>[import_export.dart]"}}
  node_n_check_update{{"Update check<br/>[check_update.dart]"}}
  node_n_theme["App colors<br/>theme<br/>[app_colors.dart]"]
end

subgraph group_grp_platform["Platform runners"]
  node_n_android["Android runner<br/>native shell<br/>[MainActivity.kt]"]
  node_n_ios["iOS runner<br/>native shell<br/>[AppDelegate.swift]"]
  node_n_macos["macOS runner<br/>native shell"]
  node_n_linux["Linux runner<br/>native shell<br/>[main.cc]"]
  node_n_windows["Windows runner<br/>native shell<br/>[main.cpp]"]
end

node_n_main -->|"launches"| node_n_mobile_home
node_n_main -->|"launches"| node_n_desktop_shell
node_n_mobile_home -->|"uses"| node_n_mobile_components
node_n_mobile_components -->|"reads/writes"| node_n_code_data
node_n_mobile_components -->|"reads/writes"| node_n_preview_data
node_n_desktop_shell -->|"navigates"| node_n_desktop_pages
node_n_desktop_shell -->|"uses"| node_n_desktop_components
node_n_desktop_pages -->|"uses"| node_n_desktop_components
node_n_desktop_pages -->|"reads/writes"| node_n_code_data
node_n_desktop_pages -->|"reads"| node_n_preview_data
node_n_code_data -->|"generated by"| node_n_code_gen
node_n_main -->|"routes to"| node_n_link_utils
node_n_link_utils -->|"feeds"| node_n_preview_map
node_n_preview_map -->|"populates"| node_n_preview_data
node_n_import_export -->|"moves"| node_n_code_data
node_n_import_export -->|"moves"| node_n_preview_data
node_n_main -->|"loads"| node_n_toggles_data
node_n_main -->|"applies"| node_n_theme
node_n_check_update -->|"notifies"| node_n_main
node_n_android -->|"hosts"| node_n_main
node_n_ios -->|"hosts"| node_n_main
node_n_macos -->|"hosts"| node_n_main
node_n_linux -->|"hosts"| node_n_main
node_n_windows -->|"hosts"| node_n_main

click node_n_main "https://github.com/jydv402/memno/blob/main/lib/main.dart"
click node_n_mobile_home "https://github.com/jydv402/memno/blob/main/lib/mobile/home.dart"
click node_n_mobile_components "https://github.com/jydv402/memno/tree/main/lib/mobile/components"
click node_n_desktop_shell "https://github.com/jydv402/memno/blob/main/lib/desktop/desktop_shell.dart"
click node_n_desktop_pages "https://github.com/jydv402/memno/tree/main/lib/desktop/pages"
click node_n_desktop_components "https://github.com/jydv402/memno/tree/main/lib/desktop/components"
click node_n_code_data "https://github.com/jydv402/memno/blob/main/lib/logic/database/code_data.dart"
click node_n_preview_data "https://github.com/jydv402/memno/blob/main/lib/logic/database/preview_data.dart"
click node_n_toggles_data "https://github.com/jydv402/memno/blob/main/lib/logic/database/toggles_data.dart"
click node_n_code_gen "https://github.com/jydv402/memno/blob/main/lib/logic/functionality/code_gen.dart"
click node_n_link_utils "https://github.com/jydv402/memno/blob/main/lib/logic/functionality/link_utils.dart"
click node_n_preview_map "https://github.com/jydv402/memno/blob/main/lib/logic/functionality/preview_map.dart"
click node_n_import_export "https://github.com/jydv402/memno/blob/main/lib/logic/functionality/import_export.dart"
click node_n_check_update "https://github.com/jydv402/memno/blob/main/lib/logic/functionality/check_update.dart"
click node_n_theme "https://github.com/jydv402/memno/blob/main/lib/logic/theme/app_colors.dart"
click node_n_android "https://github.com/jydv402/memno/blob/main/android/app/src/main/kotlin/com/example/memno/MainActivity.kt"
click node_n_ios "https://github.com/jydv402/memno/blob/main/ios/Runner/AppDelegate.swift"
click node_n_macos "https://github.com/jydv402/memno/blob/main/macos/Runner/MainFlutterWindow.swift"
click node_n_linux "https://github.com/jydv402/memno/blob/main/linux/main.cc"
click node_n_windows "https://github.com/jydv402/memno/blob/main/windows/runner/main.cpp"

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_n_main,node_n_mobile_home,node_n_mobile_components,node_n_desktop_shell,node_n_desktop_pages,node_n_desktop_components toneBlue
class node_n_code_data,node_n_preview_data,node_n_toggles_data,node_n_code_gen,node_n_link_utils,node_n_preview_map,node_n_import_export,node_n_check_update,node_n_theme toneAmber
class node_n_android,node_n_ios,node_n_macos,node_n_linux,node_n_windows toneMint
```

## Components

### Flutter app

Shared Dart application and UI shells.

- [Main entry](https://github.com/jydv402/memno/blob/main/lib/main.dart): dart entrypoint · Bootstraps the app and selects the appropriate shell. · `lib/main.dart`
- [Mobile home](https://github.com/jydv402/memno/blob/main/lib/mobile/home.dart): mobile shell · Primary compact experience for handheld use. · `lib/mobile/home.dart`
- [Mobile components](https://github.com/jydv402/memno/tree/main/lib/mobile/components): ui components · Reusable mobile surfaces for navigation, sharing, settings, and feedback. · `lib/mobile/components`
- [Desktop shell](https://github.com/jydv402/memno/blob/main/lib/desktop/desktop_shell.dart): desktop shell · Wide-screen application frame for keyboard-driven workflows. · `lib/desktop/desktop_shell.dart`
- [Desktop pages](https://github.com/jydv402/memno/tree/main/lib/desktop/pages): desktop views · Home, note, search, and settings screens for desktop. · `lib/desktop/pages`
- [Desktop components](https://github.com/jydv402/memno/tree/main/lib/desktop/components): desktop widgets · Reusable desktop UI pieces such as dock, cards, tiles, and notifications. · `lib/desktop/components`

### Core logic

Local data, business rules, and shared theme.

- [Code data](https://github.com/jydv402/memno/blob/main/lib/logic/database/code_data.dart): hive model · Persisted note/link records stored locally. · `lib/logic/database/code_data.dart`
- [Preview data](https://github.com/jydv402/memno/blob/main/lib/logic/database/preview_data.dart): hive model · Cached preview and metadata records for saved links. · `lib/logic/database/preview_data.dart`
- [Toggles data](https://github.com/jydv402/memno/blob/main/lib/logic/database/toggles_data.dart): hive model · Persisted user preferences and feature toggles. · `lib/logic/database/toggles_data.dart`
- [Code gen](https://github.com/jydv402/memno/blob/main/lib/logic/functionality/code_gen.dart): service · Generates the 6-digit access codes used for entries. · `lib/logic/functionality/code_gen.dart`
- [Link utils](https://github.com/jydv402/memno/blob/main/lib/logic/functionality/link_utils.dart): service · Normalizes and inspects URLs before saving. · `lib/logic/functionality/link_utils.dart`
- [Preview map](https://github.com/jydv402/memno/blob/main/lib/logic/functionality/preview_map.dart): service · Extracts or maps link metadata and preview content. · `lib/logic/functionality/preview_map.dart`
- [Import export](https://github.com/jydv402/memno/blob/main/lib/logic/functionality/import_export.dart): service · Transfers library data in and out of the app. · `lib/logic/functionality/import_export.dart`
- [Update check](https://github.com/jydv402/memno/blob/main/lib/logic/functionality/check_update.dart): service · Checks for newer releases or updates. · `lib/logic/functionality/check_update.dart`
- [App colors](https://github.com/jydv402/memno/blob/main/lib/logic/theme/app_colors.dart): theme · Shared color and theme definitions including dark mode support. · `lib/logic/theme/app_colors.dart`

### Platform runners

Native embedder shells and packaging for each target platform.

- [Android runner](https://github.com/jydv402/memno/blob/main/android/app/src/main/kotlin/com/example/memno/MainActivity.kt): native shell · Android embedder and app packaging layer. · `android/app/src/main/kotlin/com/example/memno/MainActivity.kt`
- [iOS runner](https://github.com/jydv402/memno/blob/main/ios/Runner/AppDelegate.swift): native shell · iOS embedder and Xcode application layer. · `ios/Runner/AppDelegate.swift`
- [macOS runner](https://github.com/jydv402/memno/blob/main/macos/Runner/MainFlutterWindow.swift): native shell · macOS embedder and window/application layer. · `macos/Runner/MainFlutterWindow.swift`
- [Linux runner](https://github.com/jydv402/memno/blob/main/linux/main.cc): native shell · Linux embedder and CMake-based runner layer. · `linux/main.cc`
- [Windows runner](https://github.com/jydv402/memno/blob/main/windows/runner/main.cpp): native shell · Windows embedder and installer/distribution layer. · `windows/runner/main.cpp`

## Connections

- Main entry → Mobile home: launches · Chooses the mobile experience on compact platforms.
- Main entry → Desktop shell: launches · Chooses the desktop experience on larger screens.
- Mobile home → Mobile components: uses · Builds the compact UI from reusable mobile surfaces.
- Mobile components → Code data: reads/writes · Displays and edits saved entries.
- Mobile components → Preview data: reads/writes · Shows cached preview metadata.
- Desktop shell → Desktop pages: navigates · Hosts the main desktop pages.
- Desktop shell → Desktop components: uses · Composes dock, cards, overlays, and notifications.
- Desktop pages → Desktop components: uses · Shares desktop-specific widgets across pages.
- Desktop pages → Code data: reads/writes · Loads and edits stored records.
- Desktop pages → Preview data: reads · Renders preview metadata for saved links.
- Code data → Code gen: generated by · Entry codes are assigned by the code generator.
- Main entry → Link utils: routes to · Entry flow passes link handling into shared logic.
- Link utils → Preview map: feeds · URL handling informs metadata lookup and preview extraction.
- Preview map → Preview data: populates · Preview results are stored locally.
- Import export → Code data: moves · Exports and imports saved entries.
- Import export → Preview data: moves · Transfers preview metadata with the library.
- Main entry → Toggles data: loads · Restores persisted preferences at startup.
- Main entry → App colors: applies · Initializes shared theme and color setup.
- Update check → Main entry: notifies · Update checks surface from the shared app flow.
- Android runner → Main entry: hosts · Android runner launches the shared Flutter app.
- iOS runner → Main entry: hosts · iOS runner launches the shared Flutter app.
- macOS runner → Main entry: hosts · macOS runner launches the shared Flutter app.
- Linux runner → Main entry: hosts · Linux runner launches the shared Flutter app.
- Windows runner → Main entry: hosts · Windows runner launches the shared Flutter app.