# zhao-gl/zgl-todo architecture

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

- Interactive diagram: https://gitdiagram.com/zhao-gl/zgl-todo
- Repository: https://github.com/zhao-gl/zgl-todo

## Overview

1. **Overall shape**
   - This is a **desktop application** built with **Electron + React + TypeScript**, not a typical browser-only web app.
   - The architecture is split into an **Electron main process** for native app/runtime responsibilities and a **renderer process** for the UI.

2. **Main process boundary**
   - `electron/main.js` is the entry point for the Electron side.
   - It is responsible for app startup, window lifecycle, and connecting the UI to local services.
   - This is the boundary where desktop-specific capabilities live, separate from the React UI.

3. **IPC bridge**
   - `electron/ipc/ipc.js` defines the inter-process communication layer between renderer and main.
   - `electron/preload.js` is the security boundary that exposes a controlled API to the renderer.
   - The renderer should not access the database directly; it talks to the main process through IPC.

4. **Local persistence layer**
   - Data is stored locally in **SQLite** via `better-sqlite3` according to the README.
   - `electron/db/db.js` appears to own database initialization/connection.
   - This makes the app a **local-first** desktop tool with offline persistence.

5. **Domain data controllers**
   - `electron/db/controller/` contains the main data-access boundaries:
     - `todo.js` for task CRUD and task state changes
     - `type.js` for categories/tags/type definitions
     - `user.js` for user-related data
     - `settings.js` for application/user settings
   - These controllers likely encapsulate SQL and provide domain-specific operations to IPC handlers.

6. **Renderer application shell**
   - `src/main.tsx` boots the React app.
   - `src/App.tsx` is the top-level composition point for UI layout/routing.
   - `src/router/index.tsx` defines page navigation and the app’s screen structure.

7. **UI layout and shared chrome**
   - `src/layout/GlobalLayout.tsx` provides the common shell around pages.
   - Shared UI components in `src/components/` include:
     - `globalHeader` for the top-level header/navigation
     - `zglToolbar` for action controls
   - These form the persistent desktop UI frame around the main content area.

8. **State and cross-cutting concerns**
   - `src/global/Global.ts`, `SettingsContext.tsx`, and `ThemeContext.tsx` indicate app-wide state management.
   - Settings and theme are treated as global concerns rather than per-page state.
   - This suggests the UI reacts to persisted preferences and possibly dynamic theme switching.

9. **Feature/page structure**
   - The app is organized into feature pages under `src/pages/`, including:
     - `login`
     - `overview`
     - `collect`
     - `recycle`
     - `selectType`
     - `todoList`
     - `statistics`
     - `settings`
     - `lv1Menu`
   - `todoList` is further split into subviews like `todoCenter` and `todoEditing`, plus a custom week picker component.
   - This indicates a task-management workflow with multiple entry points and a dedicated editing flow.

10. **Data flow from UI to storage**
    - User actions in renderer pages trigger UI state changes and IPC calls.
    - IPC routes requests to the main process.
    - Main-process controllers perform SQLite reads/writes.
    - Results return back to the renderer for display, keeping persistence logic outside the UI.

11. **Styling and UI assets**
    - Styling is modular and page-scoped through `.module.less` files, with shared global styles in `src/styles/`.
    - The app also includes asset and icon generation support, suggesting packaged desktop distribution rather than just local development.

12. **Build, packaging, and release**
    - `vite.config.ts` and `electron-builder.config.js` show a dual build setup: Vite for the renderer and Electron Builder for packaging.
    - `build/` contains installer resources such as `installer.nsh` and app icons.
    - `scripts/publish.js` and `scripts/generate-icons.js` support release packaging and branding.

13. **Key architectural boundary to diagram**
    - The most important boundary is:
      **React renderer UI** → **preload/IPC bridge** → **Electron main process** → **SQLite controllers**
    - That separation is the core of the system and explains how the desktop UI stays decoupled from local data storage.

14. **What to emphasize in a diagram**
    - Show the renderer as a multi-page React app with shared layout and global context.
    - Show IPC as the only path from UI to persistence.
    - Show SQLite as the local system of record, with controllers as the domain/data access layer.
    - Show packaging/build tooling as a separate support lane around the runtime app, not part of the runtime request flow.

Main entry points: [`electron/ipc/ipc.js`](https://github.com/zhao-gl/zgl-todo/blob/main/electron/ipc/ipc.js) (IPC layer), [`electron/db/db.js`](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/db.js) (DB init), [`src/App.tsx`](https://github.com/zhao-gl/zgl-todo/blob/main/src/App.tsx) (App shell), [`vite.config.ts`](https://github.com/zhao-gl/zgl-todo/blob/main/vite.config.ts) (Build config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_electron_main["Main process<br/>electron entry<br/>[main.js]"]
  node_electron_preload["Preload bridge<br/>ipc bridge<br/>[preload.js]"]
  node_electron_ipc["IPC layer<br/>message routing<br/>[ipc.js]"]
end

subgraph group_data["Data"]
  node_db_init[("DB init<br/>sqlite setup<br/>[db.js]")]
  node_todo_ctrl["Todo data<br/>todo controller<br/>[todo.js]"]
  node_type_ctrl["Type data<br/>type controller<br/>[type.js]"]
  node_user_ctrl["User data<br/>user controller<br/>[user.js]"]
  node_settings_ctrl["Settings data<br/>settings controller<br/>[settings.js]"]
end

subgraph group_ui["UI"]
  node_renderer_boot["Renderer boot<br/>react entry<br/>[main.tsx]"]
  node_app_shell["App shell<br/>react root<br/>[App.tsx]"]
  node_router["Router<br/>navigation<br/>[index.tsx]"]
  node_global_layout["Global layout<br/>ui shell<br/>[GlobalLayout.tsx]"]
  node_global_state["Global state<br/>app state<br/>[Global.ts]"]
  node_settings_ctx["Settings ctx<br/>react context"]
  node_theme_ctx["Theme ctx<br/>react context<br/>[ThemeContext.tsx]"]
  node_pages["Pages"]
  node_todo_views["Todo views<br/>todo screens<br/>[Index.tsx]"]
end

subgraph group_tooling["Tooling"]
  node_build_tooling["Build config<br/>build pipeline<br/>[vite.config.ts]"]
  node_release_assets["Release assets<br/>packaging assets<br/>[installer.nsh]"]
end

node_renderer_boot -->|"mounts"| node_app_shell
node_app_shell -->|"uses"| node_router
node_app_shell -->|"wraps"| node_global_layout
node_app_shell -->|"shares"| node_global_state
node_global_state -->|"provides"| node_settings_ctx
node_global_state -->|"provides"| node_theme_ctx
node_router -->|"navigates"| node_pages
node_pages -->|"specializes"| node_todo_views
node_renderer_boot -->|"calls"| node_electron_preload
node_electron_preload -->|"forwards"| node_electron_ipc
node_electron_ipc -->|"routes to"| node_electron_main
node_electron_main -->|"opens"| node_db_init
node_db_init -->|"serves"| node_todo_ctrl
node_db_init -->|"serves"| node_type_ctrl
node_db_init -->|"serves"| node_user_ctrl
node_db_init -->|"serves"| node_settings_ctrl
node_electron_ipc -->|"queries"| node_todo_ctrl
node_electron_ipc -->|"queries"| node_type_ctrl
node_electron_ipc -->|"queries"| node_user_ctrl
node_electron_ipc -->|"queries"| node_settings_ctrl
node_build_tooling -.->|"builds"| node_renderer_boot
node_build_tooling -.->|"packages"| node_electron_main
node_build_tooling -.->|"includes"| node_release_assets

click node_electron_main "https://github.com/zhao-gl/zgl-todo/blob/main/electron/main.js"
click node_electron_preload "https://github.com/zhao-gl/zgl-todo/blob/main/electron/preload.js"
click node_electron_ipc "https://github.com/zhao-gl/zgl-todo/blob/main/electron/ipc/ipc.js"
click node_db_init "https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/db.js"
click node_todo_ctrl "https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/todo.js"
click node_type_ctrl "https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/type.js"
click node_user_ctrl "https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/user.js"
click node_settings_ctrl "https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/settings.js"
click node_renderer_boot "https://github.com/zhao-gl/zgl-todo/blob/main/src/main.tsx"
click node_app_shell "https://github.com/zhao-gl/zgl-todo/blob/main/src/App.tsx"
click node_router "https://github.com/zhao-gl/zgl-todo/blob/main/src/router/index.tsx"
click node_global_layout "https://github.com/zhao-gl/zgl-todo/blob/main/src/layout/GlobalLayout.tsx"
click node_global_state "https://github.com/zhao-gl/zgl-todo/blob/main/src/global/Global.ts"
click node_settings_ctx "https://github.com/zhao-gl/zgl-todo/blob/main/src/global/SettingsContext.tsx"
click node_theme_ctx "https://github.com/zhao-gl/zgl-todo/blob/main/src/global/ThemeContext.tsx"
click node_todo_views "https://github.com/zhao-gl/zgl-todo/blob/main/src/pages/todoList/Index.tsx"
click node_build_tooling "https://github.com/zhao-gl/zgl-todo/blob/main/vite.config.ts"
click node_release_assets "https://github.com/zhao-gl/zgl-todo/blob/main/build/installer.nsh"

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_electron_main,node_electron_preload,node_electron_ipc toneBlue
class node_db_init,node_todo_ctrl,node_type_ctrl,node_user_ctrl,node_settings_ctrl toneAmber
class node_renderer_boot,node_app_shell,node_router,node_global_layout,node_global_state,node_settings_ctx,node_theme_ctx,node_pages,node_todo_views toneMint
class node_build_tooling,node_release_assets toneRose
```

## Components

### Runtime

Electron app runtime and renderer UI

- [Main process](https://github.com/zhao-gl/zgl-todo/blob/main/electron/main.js): electron entry · App startup, window lifecycle, and native runtime coordination · `electron/main.js`
- [Preload bridge](https://github.com/zhao-gl/zgl-todo/blob/main/electron/preload.js): ipc bridge · Secure API surface exposed to the renderer · `electron/preload.js`
- [IPC layer](https://github.com/zhao-gl/zgl-todo/blob/main/electron/ipc/ipc.js): message routing · Routes renderer requests to main-process handlers · `electron/ipc/ipc.js`

### Data

Local persistence and domain controllers

- [DB init](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/db.js): sqlite setup · Opens and configures the local SQLite database · `electron/db/db.js`
- [Todo data](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/todo.js): todo controller · Task CRUD and status changes · `electron/db/controller/todo.js`
- [Type data](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/type.js): type controller · Category and type management · `electron/db/controller/type.js`
- [User data](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/user.js): user controller · User-related persistence operations · `electron/db/controller/user.js`
- [Settings data](https://github.com/zhao-gl/zgl-todo/blob/main/electron/db/controller/settings.js): settings controller · Application and user settings persistence · `electron/db/controller/settings.js`

### UI

React shell, pages, and shared components

- [Renderer boot](https://github.com/zhao-gl/zgl-todo/blob/main/src/main.tsx): react entry · Starts the React renderer application · `src/main.tsx`
- [App shell](https://github.com/zhao-gl/zgl-todo/blob/main/src/App.tsx): react root · Top-level composition for layout and routing · `src/App.tsx`
- [Router](https://github.com/zhao-gl/zgl-todo/blob/main/src/router/index.tsx): navigation · Defines application screens and navigation structure · `src/router/index.tsx`
- [Global layout](https://github.com/zhao-gl/zgl-todo/blob/main/src/layout/GlobalLayout.tsx): ui shell · Persistent desktop frame around page content · `src/layout/GlobalLayout.tsx`
- [Global state](https://github.com/zhao-gl/zgl-todo/blob/main/src/global/Global.ts): app state · Shared app-wide state and preferences · `src/global/Global.ts`
- [Settings ctx](https://github.com/zhao-gl/zgl-todo/blob/main/src/global/SettingsContext.tsx): react context · Provides settings state to the UI · `src/global/SettingsContext.tsx`
- [Theme ctx](https://github.com/zhao-gl/zgl-todo/blob/main/src/global/ThemeContext.tsx): react context · Provides theme state and switching · `src/global/ThemeContext.tsx`
- **Pages**: feature pages · Login, overview, collect, recycle, type selection, todo list, statistics, and settings
- [Todo views](https://github.com/zhao-gl/zgl-todo/blob/main/src/pages/todoList/Index.tsx): todo screens · Task center, editing flow, and week picker UI · `src/pages/todoList/Index.tsx`

### Tooling

Build, packaging, and release support

- [Build config](https://github.com/zhao-gl/zgl-todo/blob/main/vite.config.ts): build pipeline · Vite renderer build and Electron packaging configuration · `vite.config.ts`
- [Release assets](https://github.com/zhao-gl/zgl-todo/blob/main/build/installer.nsh): packaging assets · Installer resources, icons, and publish helpers · `build/installer.nsh`

## Connections

- Renderer boot → App shell: mounts · Bootstraps the React application
- App shell → Router: uses · Hands off screen structure to routing
- App shell → Global layout: wraps · Provides the persistent app frame
- App shell → Global state: shares · Connects application-wide state
- Global state → Settings ctx: provides · Exposes settings to descendants
- Global state → Theme ctx: provides · Exposes theme state to descendants
- Router → Pages: navigates · Routes between top-level feature pages
- Pages → Todo views: specializes · Todo workflow includes centered list and editing views
- Renderer boot → Preload bridge: calls · Renderer reaches native APIs through the preload boundary
- Preload bridge → IPC layer: forwards · Exposes controlled messaging to the main process
- IPC layer → Main process: routes to · Main process receives IPC-driven requests
- Main process → DB init: opens · Initializes local persistence
- DB init → Todo data: serves · Controllers use the shared database connection
- DB init → Type data: serves · Controllers use the shared database connection
- DB init → User data: serves · Controllers use the shared database connection
- DB init → Settings data: serves · Controllers use the shared database connection
- IPC layer → Todo data: queries · Task operations are handled in the main process
- IPC layer → Type data: queries · Type operations are handled in the main process
- IPC layer → User data: queries · User operations are handled in the main process
- IPC layer → Settings data: queries · Settings operations are handled in the main process
- Build config → Renderer boot: builds · Vite compiles the renderer application
- Build config → Main process: packages · Electron Builder packages the desktop app
- Build config → Release assets: includes · Installer and branding assets support release output
