refactor: modularize Electron main process architecture#6
Merged
Scofieldfree merged 15 commits intomainfrom Jan 26, 2026
Merged
refactor: modularize Electron main process architecture#6Scofieldfree merged 15 commits intomainfrom
Scofieldfree merged 15 commits intomainfrom
Conversation
Remove old agent-based system (.claude/agents/) and replace with modular skills-based architecture (.claude/skills/). Add AI tool configurations for Codex and OpenCode platforms. This change enables: - Reusable skill definitions across multiple AI tools - Consistent git-commit functionality across Claude, Cursor, Codex, and OpenCode - Enhanced branch management capabilities - Local code review automation - Skill creation utilities for extending the system
Remove deprecated skill documentation files from .codex/ and .opencode/ directories as part of the modularization refactoring. These files have been migrated to the centralized .claude/skills/ structure. Removed files: - branch-manager skill (README, SKILL.md, examples, scripts) - git-commit skill (SKILL.md) - pr-generator skill (SKILL.md) Also updates package-lock.json dependency metadata (peer flags).
…rate modules Extract environment configuration and window management logic from main.ts into dedicated modules for better separation of concerns and maintainability. New modules: - env.ts: Centralized runtime path configuration with initEnv() pattern - window/background.ts: Background window lifecycle management - window/index.ts: Barrel export for window module Changes in main.ts: - Replace inline environment setup with env.ts imports - Replace createMainWindow() with createBackgroundWindow() from window module - Use getBackgroundWindow() helper instead of direct variable access - Add initEnv() call at app.whenReady() entry point This refactoring aligns with the modularization effort to make the codebase more maintainable and testable.
…lay and settings Extract overlay and settings window management from main.ts into dedicated modules within the window/ directory. This completes the modularization refactoring started in the previous commit. Changes in main.ts: - Remove inline createSettingsWindow() function (140+ lines) - Remove inline overlay functions (showOverlay, hideOverlay, updateOverlay, etc.) - Import all window management functions from './window/index' - Remove unused imports (screen, fileURLToPath, OverlayState type) Changes in window/index.ts: - Add exports for overlay module functions - Add exports for settings module functions Changes in window/overlay.ts: - Implement overlay window lifecycle management - Export functions: showOverlay, hideOverlay, updateOverlay, showErrorAndHide, sendAudioLevel, setOverlayIgnoreMouseEvents Changes in window/settings.ts: - Implement settings window lifecycle management - Export functions: createSettingsWindow, getSettingsWindow, updateSettingsWindowTitle, focusSettingsWindow This refactoring improves code organization by encapsulating all window management logic in dedicated modules, making main.ts more focused on application orchestration.
Extract all IPC handler logic from main.ts into dedicated modules under electron/main/ipc/ for better separation of concerns and maintainability. New structure: - ipc/index.ts - Unified entry point with dependency injection - ipc/config-handlers.ts - Configuration management IPC (3 channels) - ipc/session-handlers.ts - Recording session IPC (5 channels) - ipc/history-handlers.ts - History management IPC (3 channels) - ipc/log-handlers.ts - Logging IPC (3 channels) - ipc/updater-handlers.ts - Update management IPC (4 channels) - ipc/overlay-handlers.ts - Overlay window IPC (3 channels) Benefits: - Type-safe dependency injection with explicit contracts - Each handler module is independently testable - Clear functional domain separation - Comprehensive JSDoc documentation for all modules - Preserves all 21 IPC channels with identical functionality
… modules Extract audio processing pipeline and system tray management from main.ts into dedicated modules for better separation of concerns and testability. Audio module (electron/main/audio/): - converter.ts - FFmpeg WebM to MP3 conversion with asar path handling - session-manager.ts - Recording session state management - processor.ts - Audio data processing pipeline (save → convert → ASR → inject) - index.ts - Unified module exports Tray module (electron/main/tray/): - index.ts - System tray creation, menu building, and localization refresh Benefits: - Reduces main.ts from ~814 to ~327 lines (~60% reduction) - Isolates audio processing logic for independent testing - Centralizes tray management with proper lifecycle handling - Preserves all functionality with detailed logging - Clean dependency injection via initProcessor()
…ed module Extract hotkey parsing, key code mapping, and PTT (push-to-talk) handler from main.ts into electron/main/hotkey/ for better code organization. New structure: - hotkey/parser.ts - Electron Accelerator to uiohook code conversion - hotkey/ptt-handler.ts - PTT hotkey registration with debounce logic - hotkey/index.ts - Unified module exports Benefits: - Removes 208 lines from main.ts (further reduction to ~119 lines) - Isolates hotkey parsing logic (comprehensive key mapping) - Centralizes PTT registration with debouncing - Cleaner dependency: main.ts now imports registerGlobalHotkeys() - Preserves all functionality with logging
Extract system notification functionality from main.ts into electron/main/notification/ for better code organization. New structure: - notification/index.ts - System notification wrapper with support check Changes: - Move showNotification() function to dedicated module - Add showNotificationWithIcon() for future extensibility - Remove unused Notification import from main.ts - Reorganize imports in main.ts with descriptive section comments Benefits: - Centralizes notification logic - Easier to extend notification features - Cleaner import organization in main.ts
…tegy Enhance main.ts initialization logic with better comments and smarter window launch behavior for auto-start scenarios. Changes: - Add descriptive comments for each initialization step - Implement smart settings window launch strategy: * Dev environment: Always open settings window * Production: Only open if not launched as hidden (e.g., from auto-start) - Use app.getLoginItemSettings().wasOpenedAsHidden to detect launch mode Benefits: - Better code readability with clear section comments - Improved user experience for auto-start scenarios - Settings window doesn't appear when app starts hidden at login
Add language snapshot broadcast system to ensure language changes propagate immediately to all renderer windows without restart. Main process changes: - Add getMainLanguageSnapshot() to capture current language state - Add sendLanguageSnapshotToWindow() for per-window language updates - Add broadcastLanguageSnapshot() for global language synchronization - Register browser-window-created listener to auto-send snapshots - Add APP_LANGUAGE_GET IPC handler for renderer queries Renderer changes: - Use getAppLanguage() API instead of full config for initialization - Listen to APP_LANGUAGE_CHANGED IPC for real-time updates - Update document.documentElement.lang on language change - Simplify SettingsPage by removing duplicate resolveLanguage logic Type system: - Add LanguageSnapshot interface (setting, resolved, locale) - Add APP_LANGUAGE_GET and APP_LANGUAGE_CHANGED IPC channels - Type-safe language propagation across process boundary Benefits: - All windows stay in sync with language settings immediately - New windows receive current language on creation - No app restart required when changing language - Single source of truth for language state in main process
Add automatic system locale detection and sync to keep app language in sync with OS locale changes when using 'system' language setting. Changes: - Add syncSystemLocaleIfNeeded() to detect and sync system locale changes - Track lastSystemLocale and lastResolvedLanguage for change detection - Add browser-window-focus event listener to trigger locale checks - Broadcast language snapshot and refresh localized UI on sync Behavior: - Only syncs when currentSetting === 'system' - Checks for locale changes when any window gains focus - Automatically updates all windows when system locale changes - No-op when user has selected a specific language Benefits: - App language follows OS language automatically - Seamless experience when user changes system language - No manual language switching needed for system setting
Update all README files to document the new modular structure created during the refactor/modularization effort. Root documentation: - CLAUDE.md - Add new module directories to project structure - electron/README.md - Document new modularized components - electron/main/README.md - Update to reflect main.ts changes - src/README.md - Minor formatting update New module documentation: - audio/README.md - Audio pipeline (session, converter, processor) - hotkey/README.md - Hotkey parsing + PTT bindings - notification/README.md - System notification helpers - tray/README.md - Tray menu + localization refresh - window/README.md - Background/settings/overlay windows This documentation ensures developers can quickly understand the new modular architecture without reading source code.
Contributor
Author
Code reviewNo issues found. Checked for bugs and CLAUDE.md compliance. This is an excellent refactoring that achieves:
All modules follow consistent patterns with proper error handling, logging prefixes, and lifecycle management. The i18n enhancements (language snapshot broadcast and system locale sync) are well-designed with proper type safety. 🤖 Generated with Claude Code - If this code review was useful, please react with 👍. Otherwise, react with 👎. |
Add proper fallback chain for language resolution when getAppLanguage
fails or returns null in the renderer process.
Changes:
- Import resolveLanguage helper from shared i18n
- Add fallback to system language (navigator.language)
- Use resolveLanguage('system', systemLanguage) for consistent behavior
- Final fallback to DEFAULT_LANGUAGE if all else fails
This ensures the renderer always has a valid language even if
the main process IPC call fails during initialization.
Fixes potential undefined language issue on renderer startup.
Contributor
|
@Scofieldfree 第一个Medium的感觉需要处理一下，还是有比较大的可能会遇到问题，第二个medium我不确定，不是特别懂，你评估一下
|
yexia553
requested changes
Jan 26, 2026
|
|
||
| ## License | ||
|
|
||
| Same as the original code-review plugin. |
- Delete .claude/skills/local-code-review/ directory (no longer needed) - Add error handling for handleAudioData promise in session IPC handler
Replace manual __dirname calculation with centralized getMainDist() function for consistent preload path resolution across all window types (background, overlay, settings).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Overview
This PR implements a comprehensive modularization of the Electron main process, transforming a monolithic ~814-line
main.tsinto a clean, maintainable architecture with ~180 lines in the entry file.Changes Summary
Modular Architecture (78% code reduction in main.ts)
New Modules Created:
ipc/- IPC handlers split by domain (config, session, history, log, updater, overlay)audio/- Audio processing pipeline (session management, converter, processor)hotkey/- Hotkey parsing and PTT behavior bindingsnotification/- System notification helperstray/- Tray menu and localization refreshwindow/- Background/settings/overlay windows (already existed, documented)i18n Enhancements
Documentation Updates
Benefits
✅ Maintainability - Each module has a single, well-defined responsibility
✅ Testability - Isolated modules can be tested independently
✅ Code Clarity - Descriptive logging prefixes and JSDoc comments throughout
✅ Type Safety - Proper TypeScript types and dependency injection
✅ Documentation - Every module has comprehensive README and JSDoc
Testing
Manual testing performed:
Breaking Changes
None. All functionality preserved with identical behavior.
Checklist