Inter-Process Communication
Relevant source files
The following files were used as context for generating this wiki page:
The Inter-Process Communication (IPC) system in this project facilitates coordination between the Node.js/Express backend and various Python automation subprocesses. This mechanism is critical for executing Instagram automation tasks, managing workflows, and handling login sessions while providing real-time feedback to the frontend interface.
The system uses a multi-layered approach to IPC: stdin for passing initialization configuration and credentials, stdout/stderr for capturing structured logs and events, and WebSockets for broadcasting these updates to client applications.
Architecture and Data Flow
The architecture follows a controller-worker pattern where the Node.js server acts as the controller, spawning Python "workers" for specific tasks.
Subprocess Management
Subprocesses are managed through a centralized ProcessService that handles spawning, tracking PIDs, and graceful termination. When a process is started, the server wires up event listeners to its standard I/O streams to monitor execution and capture data.
The diagram above shows the unidirectional flow of configuration data into the subprocess and the event stream flowing back to the user interface.
Sources: server/automation/routes.ts:88-105, server/shared/ProcessService.ts
Communication Channels
Input via Stdin
Configuration data, settings, and user credentials are passed to Python subprocesses immediately after spawning using stdin. This data is serialized as a JSON payload to ensure structured communication.
| Input Type | Triggering Endpoint | Data Transmitted |
|---|---|---|
| Automation Settings | POST /api/automation/start | Global automation settings and parameters. |
| Login Credentials | POST /api/automation/login | Username, password, and 2FA secrets. |
| Workflow Definition | POST /api/workflows/run | Node/edge graph, parallel profile limits, and current states. |
Sources: server/automation/routes.ts:187-192, server/workflows/service.ts:85-101
Output via Stdout/Stderr
Subprocesses communicate back to the server by printing stringified JSON or plain text to stdout and stderr. The server uses a log parser to differentiate between standard logs and structured lifecycle events.
- Stdout: Used for structured logs, status updates (e.g.,
profile_started,task_completed), and specialized triggers like__LOGIN_SUCCESS__. - Stderr: Primarily used for error reporting and traceback captures.
Sources: server/automation/routes.ts:110-120, server/automation/routes.ts:203-210, server/logs/parser.ts
Event Parsing and Real-time Broadcasting
The server processes the raw output from subprocesses and transforms it into a standardized event format before broadcasting via WebSockets.
Event Types
The following event types are commonly extracted from the subprocess output stream:
| Event Type | Description | Source File |
|---|---|---|
session_started | Indicates the start of an automation batch. | frontend/src/hooks/useWebSocket.ts:20 |
profile_started | Triggered when a specific Instagram profile begins execution. | server/automation/routes.ts:114 |
display_allocated | Sent when a VNC display is assigned to a profile. | server/workflows/service.ts:157 |
workflow_status | Updates the status of a long-running workflow. | server/workflows/service.ts:192 |
log | Standard informational or error message. | server/automation/routes.ts:122 |
Sequence of a Workflow Execution
This sequence diagram illustrates the IPC interaction during a workflow run.
The sequence shows the transition from initialization to lifecycle event reporting via the IPC bridge.
Sources: server/workflows/service.ts:103-146, frontend/src/hooks/useWebSocket.ts:133-155
Process Lifecycle Monitoring
The server monitors the health and exit status of subprocesses to ensure system stability.
- PID Tracking: The server saves the PID of active automation processes to prevent orphaned runs and allow for manual termination.
- Close Events: When a process exits, the
closeevent is captured. An exit code of0typically indicates success, while non-zero codes trigger "warn" or "error" level logs to the frontend. - Graceful Shutdown: During server shutdown, the
registerShutdownHandlersutility ensures all active Python subprocesses are sent termination signals to prevent background leaks.
Sources: server/automation/routes.ts:133-145, server/index.ts:147-152, server/workflows/service.ts:187-205
Summary
The Inter-Process Communication system provides the essential bridge between the high-level management capabilities of the Node.js backend and the low-level automation execution of the Python workers. By utilizing standard I/O streams for data exchange and WebSockets for real-time propagation, the system maintains a responsive and synchronized state across the entire software stack.