Component hierarchy and structure

React tree from main.jsx / App.jsx down through BulkMailer, sidebar, top bar, and the three service forms.

Electron main process and React renderer stay apart. The UI is React + Tailwind. The main process owns Gmail, SMTP, and WhatsApp Web automation.

graph TB
subgraph "Electron Renderer (React)"
M["main.jsx<br/>Entry Point"]
A["App.jsx<br/>Root Component"]
BM["BulkMailer.jsx<br/>Central Orchestrator"]
SB["Sidebar.jsx<br/>Navigation"]
TB["TopBar.jsx<br/>Header"]
WF["WhatsAppForm.jsx<br/>WhatsApp UI"]
GF["GmailForm.jsx<br/>Gmail UI"]
SF["SMTPForm.jsx<br/>SMTP UI"]
IC["Icons.jsx<br/>SVG Icons"]
end
subgraph "Electron Main Process"
MJ["main.js<br/>IPC Handlers"]
PL["preload.js<br/>Context Bridge"]
end
M --> A
A --> BM
BM --> SB
BM --> TB
BM --> WF
BM --> GF
BM --> SF
WF --> IC
GF --> IC
SF --> IC
BM --> MJ
PL --> MJ

• Application entry point: main.jsx creates the root React element and renders the App component.
• Root component: App.jsx wraps the central orchestrator component BulkMailer.
• Central orchestrator: BulkMailer manages state for all messaging services, coordinates UI tabs, and integrates with Electron APIs for Gmail, SMTP, and WhatsApp.
• Navigation and header: Sidebar.jsx provides tab navigation; TopBar.jsx displays contextual header information.
• Feature forms: WhatsAppForm.jsx, GmailForm.jsx, and SMTPForm.jsx encapsulate UI and logic for each messaging service.
• Shared icons: Icons.jsx provides reusable SVG icons used across forms.

Key orchestration responsibilities in BulkMailer:

• Tab-based routing (activeTab) to render the appropriate form.
• State for each service (Gmail, SMTP, WhatsApp) including credentials, recipients, messages, and results.
• Electron API integration via window.electronAPI exposed by preload.js.
• Real-time status updates for WhatsApp (QR, authentication, send progress).

The UI layer follows a unidirectional data flow pattern:

• State is centralized in BulkMailer.
• Props are passed down to child components (Sidebar, TopBar, Forms).
• Callbacks are passed down to update state in BulkMailer.
• Side effects (API calls) are invoked via window.electronAPI, which bridges to Electron IPC handlers.

sequenceDiagram
participant U as "User"
participant SB as "Sidebar"
participant TB as "TopBar"
participant BM as "BulkMailer"
participant WF as "WhatsAppForm"
participant GF as "GmailForm"
participant SF as "SMTPForm"
participant PL as "preload.js"
participant MJ as "main.js"
U->>SB : Click tab
SB->>BM : setActiveTab(activeTab)
BM->>TB : Render with activeTab
BM->>WF : Render when activeTab==="whatsapp"
BM->>GF : Render when activeTab==="gmail"
BM->>SF : Render when activeTab==="smtp"
U->>WF : Start WhatsApp client
WF->>BM : startWhatsAppClient()
BM->>PL : window.electronAPI.startWhatsAppClient()
PL->>MJ : ipcRenderer.invoke('whatsapp-start-client')
MJ-->>PL : Promise resolves
PL-->>BM : Promise resolves
BM-->>WF : Update status/QR/results
U->>WF : Logout
WF->>BM : logoutWhatsApp()
BM->>PL : window.electronAPI.logoutWhatsApp()
PL->>MJ : ipcRenderer.invoke('whatsapp-logout')
MJ-->>PL : Promise resolves
PL-->>BM : Promise resolves
BM-->>WF : Reset state

Component tree and composition#

The component tree starts at the entry point and flows through the root component to the central orchestrator and its children.

graph TB
M["main.jsx"]
A["App.jsx"]
BM["BulkMailer.jsx"]
SB["Sidebar.jsx"]
TB["TopBar.jsx"]
WF["WhatsAppForm.jsx"]
GF["GmailForm.jsx"]
SF["SMTPForm.jsx"]
M --> A
A --> BM
BM --> SB
BM --> TB
BM --> WF
BM --> GF
BM --> SF

BulkMailer: central orchestrator#

Responsibilities:

• Manages active tab state and renders the appropriate form.
• Maintains state for Gmail, SMTP, and WhatsApp services.
• Integrates with Electron APIs for authentication, sending, and file operations.
• Subscribes to real-time events for WhatsApp status, QR, and send progress.
• Provides callbacks to child components for actions like starting clients, importing contacts, and sending messages.

Communication patterns:

• Props down: activeTab, service states, callbacks.
• Events up: Electron IPC callbacks update state and trigger re-renders.

Lifecycle management:

• useEffect initializes listeners for WhatsApp status and cleans them up on unmount.

Rendering optimization:

• Uses conditional rendering to show only the active tab.
• Child components manage their own local state for UI feedback (e.g., logs in WhatsAppForm).

Sidebar and TopBar integration#

• Sidebar.jsx receives activeTab and a setter to switch tabs. It renders icons for Gmail, SMTP, and WhatsApp and applies active state styling based on activeTab.
• TopBar.jsx receives activeTab and displays the current service name and description.

Integration pattern:

• Controlled components: BulkMailer controls activeTab and passes it down as props.
• Event-driven updates: Clicking a sidebar item triggers setActiveTab, causing BulkMailer to re-render the appropriate form.

Form components: composition and prop drilling#

Each form component is a controlled component receiving props from BulkMailer:

• WhatsAppForm.jsx: Receives contact list, message, status, QR, sending state, and results. Provides callbacks for starting client, importing contacts, logging out, and sending messages.
• GmailForm.jsx: Receives authentication state, email list, subject, message, delay, sending state, and results. Provides callbacks for importing email lists, authenticating, and sending emails.
• SMTPForm.jsx: Receives SMTP configuration, email list, subject, message, delay, sending state, and results. Provides callbacks for importing email lists and sending emails.

Prop drilling pattern:

• BulkMailer drills state and callbacks down to each form component.
• Benefits: Predictable data flow, easy testing, and clear ownership of state.
• Drawbacks: Potential verbosity; consider context or state libraries for larger apps.

Electron API integration#

BulkMailer interacts with Electron APIs via window.electronAPI:

• Gmail: authenticateGmail, getGmailToken, sendEmail.
• SMTP: sendSMTPEmail.
• File operations: importEmailList, readEmailListFile.
• WhatsApp: startWhatsAppClient, logoutWhatsApp, sendWhatsAppMessages, importWhatsAppContacts, and event listeners for status, QR, and send progress.

Preload bridge:

• preload.js exposes window.electronAPI using contextBridge and ipcRenderer, mapping to main.js IPC handlers.

Icons component#

Icons.jsx exports reusable SVG components used across forms for consistent UI.

External dependencies relevant to UI and architecture:

• React and ReactDOM for rendering.
• TailwindCSS for styling and responsive design.
• whatsapp-web.js for WhatsApp automation.
• googleapis for Gmail API integration.
• nodemailer for SMTP integration.
• qrcode for QR code generation.
• qrcode-terminal for terminal QR display.

graph TB
P["package.json"]
R["react"]
RD["react-dom"]
TW["tailwindcss"]
WWEB["whatsapp-web.js"]
GA["googleapis"]
NM["nodemailer"]
QC["qrcode"]
QCT["qrcode-terminal"]
P --> R
P --> RD
P --> TW
P --> WWEB
P --> GA
P --> NM
P --> QC
P --> QCT

• Conditional rendering: Only the active tab is rendered, reducing unnecessary component creation.
• Local UI state: Child components maintain small, focused state (e.g., logs, manual inputs) to minimize re-renders.
• Event cleanup: BulkMailer removes event listeners in useEffect cleanup to prevent memory leaks.
• Debounced or throttled operations: Consider debouncing file import operations if needed.
• Virtualized lists: If contact lists grow large, consider virtualization for performance.
• CSS animations: Keep animations minimal to avoid layout thrashing.

Common issues and diagnostics:

• WhatsApp QR not appearing:
• Verify Electron environment and window.electronAPI availability.
• Check onWhatsAppQR and onWhatsAppStatus listeners in BulkMailer.
• Confirm main.js QR code generation and IPC emission.
• Authentication failures:
• Ensure preload.js exposes authenticateGmail/getGmailToken and main.js handlers are registered.
• Validate Gmail scopes and credentials.
• SMTP errors:
• Verify SMTP configuration fields and network connectivity.
• Check main.js SMTP handler for errors.
• File import issues:
• Confirm dialog permissions and file parsing logic in main.js.
• Ensure preload.js exposes importEmailList/readEmailListFile.

New feature UI usually means a form under BulkMailer plus an IPC method, not a second top-level app shell.