Merge pull request #263 from deploystackio/feat/background-jobs-satellite

Feat/background jobs satellite

Author: Lasim

docs/development/backend/events.mdx

@@ -7,6 +7,8 @@ description: Type-safe event system for decoupled communication between core sys
 
 The Global Event Bus enables decoupled communication between core systems and plugins through a type-safe event system. Core systems emit events when important actions occur, and plugins can react without direct coupling to business logic.
 
+**Note**: This documentation covers the **internal backend event bus** for plugin communication. If you're looking for the **satellite events system** (incoming events from satellites), see [Satellite Events](/development/backend/satellite-events).
+
 ## Overview
 
 Key features:

docs/development/backend/index.mdx

@@ -112,6 +112,14 @@ The development server starts at `http://localhost:3000` with API documentation
   >
     Database-backed job processing system with persistent storage, automatic retries, and rate limiting for long-running background tasks.
   </Card>
+  
+  <Card 
+    icon={<Terminal />} 
+    href="/deploystack/development/backend/satellite-events" 
+    title="Satellite Events"
+  >
+    Real-time event processing from satellites with convention-based handlers routing to business tables for operational visibility.
+  </Card>
 </Cards>
 
 ## Project Structure

docs/development/backend/satellite-communication.mdx

@@ -71,6 +71,26 @@ Satellites use **outbound-only HTTPS polling** to communicate with the backend,
 └─────────────────┘    Command Response   └─────────────────┘
 ```
 
+### Communication Channels
+
+The system uses three distinct communication patterns:
+
+**Command Polling (Backend → Satellite)**:
+- Backend creates commands, satellites poll and execute
+- Adaptive intervals: 2-60 seconds based on priority
+- Used for: MCP server configuration, process management
+
+**Heartbeat (Satellite → Backend, Periodic)**:
+- Satellites report status every 30 seconds
+- Contains: System metrics, process counts, resource usage
+- Used for: Health monitoring, capacity planning
+
+**Events (Satellite → Backend, Immediate)**:
+- Satellites emit events when actions occur, batched every 3 seconds
+- Contains: Point-in-time occurrences with precise timestamps
+- Used for: Real-time UI updates, audit trails, user notifications
+- See [Satellite Events](/development/backend/satellite-events) for detailed implementation
+
 ### Dual Deployment Models
 
 **Global Satellites**: Cloud-hosted by DeployStack team
@@ -474,6 +494,7 @@ For detailed API endpoints, request/response formats, and authentication pattern
 
 For detailed satellite architecture and implementation:
 
+- [Satellite Events](/development/backend/satellite-events) - Real-time event processing system
 - [API Security](/development/backend/api-security) - Security patterns and authorization  
 - [Database Management](/development/backend/database) - Schema and data management
 - [OAuth2 Server](/development/backend/oauth2-server) - OAuth2 implementation details