Skip to content

Feat/background jobs satellite #263

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Lasim merged 2 commits into from
Oct 13, 2025
Merged

Feat/background jobs satellite #263

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e19a89d
docs: add background jobs system documentation and integrate into arc…
Oct 12, 2025
11d88ed
Add Satellite Event System documentation and event emission details
Oct 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/development/backend/events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
8 changes: 8 additions & 0 deletions docs/development/backend/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 21 additions & 0 deletions docs/development/backend/satellite-communication.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Loading