How zhao-gl/zgl-todo works
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: ipc.js IPC layer · db.js DB init · App.tsx App shell · vite.config.ts Build config
Components 19
Runtime
Electron app runtime and renderer UI
- Main process · App startup, window lifecycle, and native runtime coordination
electron/main.js - Preload bridge · Secure API surface exposed to the renderer
electron/preload.js - IPC layer · Routes renderer requests to main-process handlers
electron/ipc/ipc.js
Data
Local persistence and domain controllers
- DB init · Opens and configures the local SQLite database
electron/db/db.js - Todo data · Task CRUD and status changes
electron/db/controller/todo.js - Type data · Category and type management
electron/db/controller/type.js - User data · User-related persistence operations
electron/db/controller/user.js - Settings data · Application and user settings persistence
electron/db/controller/settings.js
UI
React shell, pages, and shared components
- Renderer boot · Starts the React renderer application
src/main.tsx - App shell · Top-level composition for layout and routing
src/App.tsx - Router · Defines application screens and navigation structure
src/router/index.tsx - Global layout · Persistent desktop frame around page content
src/layout/GlobalLayout.tsx - Global state · Shared app-wide state and preferences
src/global/Global.ts - Settings ctx · Provides settings state to the UI
src/global/SettingsContext.tsx - Theme ctx · Provides theme state and switching
src/global/ThemeContext.tsx - Pages · Login, overview, collect, recycle, type selection, todo list, statistics, and settings
- Todo views · Task center, editing flow, and week picker UI
src/pages/todoList/Index.tsx
Tooling
Build, packaging, and release support
- Build config · Vite renderer build and Electron packaging configuration
vite.config.ts - Release assets · Installer resources, icons, and publish helpers
build/installer.nsh
Connections 23
- 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