@bluealba/platform-cli 1.0.1 → 1.1.0

package/docs/architecture/scheduler.mdx

@@ -0,0 +1,818 @@
+---
+title: Scheduler Module
+description: The PAE Scheduler Module for managing and executing recurring tasks and scheduled jobs within the Gateway Service
+---
+
+import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components';
+
+The **PAE Scheduler Module** provides a robust mechanism for scheduling and executing recurring tasks within the Blue Alba Platform. It is an integrated module of the Gateway Service, inheriting its authentication, authorization, and multi-tenancy capabilities.
+
+## Overview
+
+The Scheduler Module allows you to:
+
+<CardGrid stagger>
+  <Card title="Schedule Recurring Tasks" icon="seti:clock">
+    Define jobs that execute periodically using standard cron expressions
+  </Card>
+
+  <Card title="HTTP Job Execution" icon="random">
+    Make HTTP calls to any service endpoint on a schedule
+  </Card>
+
+  <Card title="Full REST API" icon="seti:config">
+    Complete CRUD operations, enable/disable, manual trigger, and execution history
+  </Card>
+
+  <Card title="Persistent Storage" icon="seti:db">
+    Job configurations and execution history are persisted in the platform database
+  </Card>
+
+  <Card title="Dynamic Parameters" icon="seti:text">
+    Use dynamic date/time parameters that resolve at execution time
+  </Card>
+
+  <Card title="Execution Tracking" icon="approve-check">
+    Track job execution history with detailed status, results, and error information
+  </Card>
+</CardGrid>
+
+---
+
+## Authentication
+
+<Aside type="caution" title="Authentication Required">
+  All Scheduler API endpoints require authentication. The module inherits the Gateway's authentication mechanisms.
+</Aside>
+
+The Scheduler Module uses the Gateway's authentication system:
+
+- **JWT Token**: Include in the `Authorization` header as `Bearer <token>`
+- **Session Cookie**: Use the platform's session cookie for browser-based access
+
+```bash
+# Using JWT token
+curl -H "Authorization: Bearer <your-jwt-token>" \
+  http://localhost:3000/_/scheduler/jobs
+
+# Using cookie (from browser session)
+curl -b "session=<session-cookie>" \
+  http://localhost:3000/_/scheduler/jobs
+```
+
+---
+
+## Supported Job Types
+
+<Aside type="note" title="Current Limitation">
+  Although the Job model is designed to be generic and extensible, the only currently supported job type is **HttpInvokerTask**. Future versions may support additional job types such as database operations, message queue publishing, or custom function execution.
+</Aside>
+
+### HTTP Invoker Task
+
+HTTP jobs make web requests to specified endpoints on a schedule:
+
+**Capabilities**:
+- GET, POST, HEAD, PUT, DELETE, PATCH methods
+- Custom request headers
+- Request body for POST/PUT/PATCH (objects are automatically converted to JSON)
+- Dynamic parameter resolution at execution time
+- Scheduling via cron pattern expressions
+
+**Use Cases**:
+- Data synchronization between services
+- Periodic data cleanup or archival
+- Report generation and email delivery
+- Health checks and monitoring
+- Cache invalidation
+- Batch processing triggers
+
+---
+
+## Job Configuration
+
+### Job Structure
+
+```typescript
+interface Job {
+  id: number;                    // Auto-generated on creation
+  application: {                 // Associated application info
+    id: number;
+    name: string;
+    displayName: string;
+  };
+  name: string;                  // Unique job name
+  description?: string;          // Optional description
+  enabled: boolean;              // Whether the job is active
+  pattern: string;               // Cron expression (e.g., "0 2 * * *")
+  taskType: 'HttpInvokerTask';   // Type of task to execute
+  taskConfig: {
+    endpoint: string;            // Base URL of the service
+    method: string;              // HTTP method: GET, POST, PUT, DELETE, etc.
+    path: string;                // URL path to invoke
+    body?: object;               // Request body (converted to JSON)
+    headers?: object;            // Custom HTTP headers
+  };
+  createdAt: string;             // ISO timestamp
+  createdBy?: string;            // User who created the job
+  updatedAt: string;             // ISO timestamp
+  updatedBy?: string;            // User who last updated the job
+}
+```
+
+### Example Job
+
+```json
+{
+  "applicationId": 5,
+  "name": "daily-data-sync",
+  "description": "Synchronizes data from external API every day at 2 AM",
+  "enabled": true,
+  "pattern": "0 2 * * *",
+  "taskType": "HttpInvokerTask",
+  "taskConfig": {
+    "endpoint": "http://integration-service:4005",
+    "method": "POST",
+    "path": "/api/sync",
+    "body": {
+      "fromDate": "${T-1:YYYY-MM-DD}",
+      "toDate": "${T:YYYY-MM-DD}"
+    },
+    "headers": {
+      "X-Custom-Header": "value"
+    }
+  }
+}
+```
+
+---
+
+## Bootstrap Configuration
+
+Jobs can be defined declaratively as part of the platform bootstrap process, alongside other application resources such as roles, operations, and modules. This approach is recommended for jobs that should exist consistently across all environments.
+
+### `jobs.json` Format
+
+Create a `jobs.json` file inside the application's bootstrap folder. The structure uses a simplified `url` field rather than the separate `endpoint` + `path` fields used by the REST API:
+
+```json
+[
+  {
+    "name": "crm-health-check",
+    "description": "Periodic health check of the CRM service",
+    "enabled": true,
+    "pattern": "*/5 * * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "url": "http://crm-service/health",
+      "method": "GET",
+      "timeout": 5000
+    }
+  },
+  {
+    "name": "crm-daily-sync",
+    "description": "Synchronizes CRM data with the external source every day at 2 AM",
+    "enabled": true,
+    "pattern": "0 2 * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "url": "http://crm-service/api/sync",
+      "method": "POST",
+      "body": { "type": "full" },
+      "headers": { "Content-Type": "application/json" },
+      "auth": { "authMethod": "bearer", "token": "example-token" },
+      "timeout": 30000
+    }
+  }
+]
+```
+
+### Sync Lifecycle
+
+The bootstrap engine manages the complete lifecycle of jobs defined in `jobs.json`:
+
+| Scenario | Behavior |
+|----------|----------|
+| Job in `jobs.json`, not in DB | Created automatically |
+| Job in `jobs.json`, in DB, owned by bootstrap | Updated to match latest definition |
+| Job in `jobs.json`, in DB, created by bootstrap but manually modified (`updatedBy` ≠ bootstrap) | Skipped — **WARNING** logged ("manually modified") |
+| Job in `jobs.json`, in DB, created by a different source entirely (`createdBy` ≠ bootstrap) | Skipped silently (debug log) |
+| Job not in `jobs.json`, in DB, owned by bootstrap | Deleted automatically |
+| Job not in `jobs.json`, in DB, owned by another source | Left untouched |
+
+### Ownership Model
+
+Bootstrap tracks ownership using the `updatedBy` field. When bootstrap creates or updates a job it sets both `createdBy` and `updatedBy` to its `scopedTo` value. On each subsequent sync, bootstrap checks whether `updatedBy` still matches its own `scopedTo` value:
+
+- If `updatedBy` matches — the job is considered bootstrap-owned and is updated or deleted as needed.
+- If `updatedBy` does not match — the job was manually edited after bootstrap created it (for example, through the Admin UI, which changes `updatedBy` to the user's username). Bootstrap skips the job and logs a **WARNING** indicating the record was manually modified.
+- If `createdBy` does not match bootstrap's `scopedTo` at all — the job was created by a completely different source and is skipped silently.
+
+This distinction means that editing a job in the Admin UI effectively transfers ownership away from bootstrap. Bootstrap will no longer overwrite those manual changes on subsequent runs.
+
+<Aside type="tip">
+  Use bootstrap configuration (`jobs.json`) for jobs that must exist consistently across development, staging, and production. For one-off or environment-specific jobs, use the Admin UI or REST API instead.
+</Aside>
+
+See the [Bootstrap documentation](/_/docs/architecture/bootstrap/) for the full bootstrap service structure and how `jobs.json` fits alongside other definition files.
+
+---
+
+## Dynamic Parameters
+
+The Scheduler supports dynamic date/time parameters that are resolved at execution time. Use these in `task_config` fields (path, body, headers).
+
+### Parameter Syntax
+
+```
+${T:FORMAT}           → Current date/time
+${T-N:FORMAT}         → N days ago
+${T+N:FORMAT}         → N days from now
+```
+
+### Supported Formats
+
+| Format | Example Output | Description |
+|--------|----------------|-------------|
+| `YYYY-MM-DD` | `2026-02-04` | ISO date |
+| `YYYY-MM-DDTHH:mm:ss` | `2026-02-04T14:30:00` | ISO datetime |
+| `HH:mm:ss` | `14:30:00` | Time only |
+| `YYYY` | `2026` | Year only |
+| `MM` | `02` | Month (zero-padded) |
+| `DD` | `04` | Day (zero-padded) |
+
+### Examples
+
+```json
+{
+  "taskConfig": {
+    "endpoint": "http://reports-service:4004",
+    "method": "POST",
+    "path": "/api/reports/generate",
+    "body": {
+      "date": "${T:YYYY-MM-DD}",
+      "startDate": "${T-7:YYYY-MM-DD}",
+      "endDate": "${T:YYYY-MM-DD}",
+      "timestamp": "${T:YYYY-MM-DDTHH:mm:ss}"
+    }
+  }
+}
+```
+
+At execution on February 4, 2026 at 14:30:00, this resolves to:
+
+```json
+{
+  "date": "2026-02-04",
+  "startDate": "2026-01-28",
+  "endDate": "2026-02-04",
+  "timestamp": "2026-02-04T14:30:00"
+}
+```
+
+---
+
+## Security
+
+### URL Validation
+
+All HTTP jobs have their `taskConfig.url` validated to prevent Server-Side Request Forgery (SSRF) attacks. For jobs with static URLs, validation runs at creation and update time. For jobs that use dynamic parameters (e.g., `https://${HOST}/api`), validation runs at execution time after parameters are resolved.
+
+**Blocked targets**:
+
+- Private IP ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`
+- Loopback addresses: `127.0.0.1`, `::1`
+- Cloud metadata endpoints: `169.254.169.254`, `metadata.google.internal`, and equivalent provider-specific addresses
+- Internal catalog services (these must be called through the gateway instead)
+- Hostnames that resolve via DNS to any of the above private ranges (DNS rebinding protection)
+- Non-HTTP/HTTPS protocols (`file://`, `ftp://`, etc.)
+
+**Allowed targets**:
+
+- Public HTTPS and HTTP URLs that resolve to public IP addresses
+- The gateway's own host — requests sent to the gateway pass through its full authentication and authorization pipeline
+
+<Aside type="caution" title="Internal services must go through the gateway">
+  To invoke an internal microservice on a schedule, target the gateway's public URL (e.g., `https://platform.example.com/api/my-service/endpoint`) rather than the service's internal hostname directly. This ensures the request is subject to the platform's auth and authz controls.
+</Aside>
+
+---
+
+## Scheduling Syntax
+
+### Cron Expressions
+
+Use standard cron syntax for precise scheduling:
+
+```
+┌───────────── minute (0 - 59)
+│ ┌───────────── hour (0 - 23)
+│ │ ┌───────────── day of month (1 - 31)
+│ │ │ ┌───────────── month (1 - 12)
+│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
+│ │ │ │ │
+│ │ │ │ │
+* * * * *
+```
+
+**Common Examples**:
+
+<Tabs>
+  <TabItem label="Every Minute">
+    ```
+    * * * * *
+    ```
+    Runs every minute
+  </TabItem>
+
+  <TabItem label="Every Hour">
+    ```
+    0 * * * *
+    ```
+    Runs at the start of every hour
+  </TabItem>
+
+  <TabItem label="Daily at Midnight">
+    ```
+    0 0 * * *
+    ```
+    Runs daily at 12:00 AM
+  </TabItem>
+
+  <TabItem label="Weekdays at 9 AM">
+    ```
+    0 9 * * 1-5
+    ```
+    Runs Monday through Friday at 9:00 AM
+  </TabItem>
+
+  <TabItem label="First of Month">
+    ```
+    0 0 1 * *
+    ```
+    Runs at midnight on the first day of every month
+  </TabItem>
+
+  <TabItem label="Every 15 Minutes">
+    ```
+    */15 * * * *
+    ```
+    Runs every 15 minutes
+  </TabItem>
+</Tabs>
+
+---
+
+## API Endpoints
+
+All endpoints are prefixed with `/_/scheduler` and require authentication.
+
+### Jobs Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/_/scheduler/jobs` | List all jobs (paginated) |
+| `GET` | `/_/scheduler/jobs/:id` | Get job by ID |
+| `POST` | `/_/scheduler/jobs` | Create a new job |
+| `PUT` | `/_/scheduler/jobs/:id` | Update an existing job |
+| `DELETE` | `/_/scheduler/jobs/:id` | Delete a job |
+| `POST` | `/_/scheduler/jobs/:id/enable` | Enable a job |
+| `POST` | `/_/scheduler/jobs/:id/disable` | Disable a job |
+| `POST` | `/_/scheduler/jobs/:id/trigger` | Manually trigger a job execution |
+
+### Executions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/_/scheduler/jobs/:id/executions` | Get execution history for a job |
+| `GET` | `/_/scheduler/executions/:id` | Get execution details by ID |
+| `GET` | `/_/scheduler/executions` | List recent executions across all jobs |
+
+### Statistics
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/_/scheduler/stats` | Get scheduler engine statistics |
+
+---
+
+## API Examples
+
+### Create a Job
+
+```bash
+curl -X POST http://localhost:3000/_/scheduler/jobs \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "applicationId": 1,
+    "name": "health-check",
+    "description": "Check external service health every 5 minutes",
+    "enabled": true,
+    "pattern": "*/5 * * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "endpoint": "https://external-service.com",
+      "method": "GET",
+      "path": "/health"
+    }
+  }'
+```
+
+### List All Jobs
+
+```bash
+curl http://localhost:3000/_/scheduler/jobs \
+  -H "Authorization: Bearer <token>"
+```
+
+**Response**:
+```json
+[
+  {
+    "id": 1,
+    "application": {
+      "id": 1,
+      "name": "my-app",
+      "displayName": "My Application"
+    },
+    "name": "health-check",
+    "description": "Check external service health every 5 minutes",
+    "enabled": true,
+    "pattern": "*/5 * * * *",
+    "taskType": "HttpInvokerTask",
+    "taskConfig": {
+      "endpoint": "https://external-service.com",
+      "method": "GET",
+      "path": "/health"
+    },
+    "createdAt": "2026-02-04T10:00:00.000Z",
+    "createdBy": "admin",
+    "updatedAt": "2026-02-04T10:00:00.000Z",
+    "updatedBy": "admin"
+  }
+]
+```
+
+### Update a Job
+
+```bash
+curl -X PUT http://localhost:3000/_/scheduler/jobs/1 \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "pattern": "*/10 * * * *",
+    "description": "Check every 10 minutes instead"
+  }'
+```
+
+### Enable/Disable a Job
+
+```bash
+# Disable
+curl -X POST http://localhost:3000/_/scheduler/jobs/1/disable \
+  -H "Authorization: Bearer <token>"
+
+# Enable
+curl -X POST http://localhost:3000/_/scheduler/jobs/1/enable \
+  -H "Authorization: Bearer <token>"
+```
+
+### Manually Trigger a Job
+
+```bash
+curl -X POST http://localhost:3000/_/scheduler/jobs/1/trigger \
+  -H "Authorization: Bearer <token>"
+```
+
+### Get Job Execution History
+
+```bash
+curl http://localhost:3000/_/scheduler/jobs/1/executions \
+  -H "Authorization: Bearer <token>"
+```
+
+**Response**:
+```json
+[
+  {
+    "id": 42,
+    "jobId": 1,
+    "status": "succeeded",
+    "startedAt": "2026-02-04T14:30:00.000Z",
+    "finishedAt": "2026-02-04T14:30:01.234Z",
+    "result": {
+      "status": 200,
+      "data": {"healthy": true}
+    }
+  },
+  {
+    "id": 41,
+    "jobId": 1,
+    "status": "failed",
+    "startedAt": "2026-02-04T14:25:00.000Z",
+    "finishedAt": "2026-02-04T14:25:05.000Z",
+    "error": {
+      "message": "Connection timeout",
+      "code": "ETIMEDOUT"
+    }
+  }
+]
+```
+
+---
+
+## Job Executions
+
+### Execution Status
+
+Each job execution has one of the following statuses:
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Execution has been queued but not yet started |
+| `running` | Execution is currently in progress |
+| `succeeded` | Execution completed successfully |
+| `failed` | Execution failed with an error |
+
+### Execution Record
+
+```typescript
+interface JobExecution {
+  id: number;
+  jobId: number;
+  status: 'pending' | 'running' | 'succeeded' | 'failed';
+  startedAt: string;            // ISO timestamp
+  finishedAt?: string;          // ISO timestamp (null if still running)
+  jobSnapshot: object;          // Job configuration at execution time (sensitive data obfuscated)
+  result?: object;              // Success response data
+  error?: {
+    message: string;
+    stack?: string;
+    code?: string;
+  };
+  createdAt: string;
+  createdBy?: string;
+}
+```
+
+### Job Snapshot
+
+The `jobSnapshot` field captures the job configuration at the moment of execution, with sensitive data (like headers and body) obfuscated. This allows auditing what configuration was used even if the job has been modified since.
+
+---
+
+## Job Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ 1. Cron Trigger                                         │
+│    • SchedulerEngineService monitors cron patterns      │
+│    • Triggers when pattern matches current time         │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 2. Create Execution Record                              │
+│    • JobExecutionService creates pending execution      │
+│    • Captures job snapshot                              │
+│    • Emits JOB_EXECUTION_STARTED event                  │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 3. Resolve Dynamic Parameters                           │
+│    • ParametersResolver processes taskConfig            │
+│    • Replaces ${T...} patterns with actual values       │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 4. Execute Task                                         │
+│    • TaskFactory creates HttpInvokerTask instance       │
+│    • Makes HTTP request to configured endpoint          │
+│    • Captures response or error                         │
+└────────────────────┬────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────┐
+│ 5. Update Execution Record                              │
+│    • Sets status to succeeded or failed                 │
+│    • Records result or error details                    │
+│    • Emits JOB_EXECUTION_SUCCEEDED or _FAILED event     │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Use Cases
+
+### Data Synchronization
+
+Synchronize data between services or external systems:
+
+```json
+{
+  "applicationId": 3,
+  "name": "sync-orders-from-external-api",
+  "description": "Sync orders every 15 minutes",
+  "enabled": true,
+  "pattern": "*/15 * * * *",
+  "taskType": "HttpInvokerTask",
+  "taskConfig": {
+    "endpoint": "http://integration-service:4005",
+    "method": "POST",
+    "path": "/api/sync-orders",
+    "body": {
+      "since": "${T-1:YYYY-MM-DDTHH:mm:ss}"
+    }
+  }
+}
+```
+
+### Data Cleanup
+
+Periodically clean up old or temporary data:
+
+```json
+{
+  "applicationId": 2,
+  "name": "delete-old-audit-logs",
+  "description": "Clean up audit logs older than 90 days every Sunday at 1 AM",
+  "enabled": true,
+  "pattern": "0 1 * * 0",
+  "taskType": "HttpInvokerTask",
+  "taskConfig": {
+    "endpoint": "http://audit-service:4003",
+    "method": "POST",
+    "path": "/api/cleanup",
+    "body": {
+      "retentionDays": 90,
+      "beforeDate": "${T-90:YYYY-MM-DD}"
+    }
+  }
+}
+```
+
+### Report Generation
+
+Generate and send reports on a schedule:
+
+```json
+{
+  "applicationId": 4,
+  "name": "weekly-sales-report",
+  "description": "Generate weekly sales report every Monday at 9 AM",
+  "enabled": true,
+  "pattern": "0 9 * * 1",
+  "taskType": "HttpInvokerTask",
+  "taskConfig": {
+    "endpoint": "http://reports-service:4004",
+    "method": "POST",
+    "path": "/api/generate",
+    "body": {
+      "reportType": "weekly-sales",
+      "startDate": "${T-7:YYYY-MM-DD}",
+      "endDate": "${T-1:YYYY-MM-DD}",
+      "emailTo": ["sales@company.com"]
+    }
+  }
+}
+```
+
+### Health Checks
+
+Monitor service health:
+
+```json
+{
+  "applicationId": 1,
+  "name": "monitor-external-service",
+  "description": "Check external service health every 5 minutes",
+  "enabled": true,
+  "pattern": "*/5 * * * *",
+  "taskType": "HttpInvokerTask",
+  "taskConfig": {
+    "endpoint": "https://external-service.com",
+    "method": "GET",
+    "path": "/health"
+  }
+}
+```
+
+---
+
+## Common Issues
+
+<Tabs>
+  <TabItem label="Job Not Running">
+    **Possible Causes**:
+    - `enabled` is set to `false`
+    - Gateway service is down
+    - Invalid cron pattern
+
+    **Solution**:
+    ```bash
+    # Check job configuration
+    curl http://localhost:3000/_/scheduler/jobs \
+      -H "Authorization: Bearer <token>"
+
+    # Verify gateway service is running
+    docker ps | grep gateway
+
+    # Check gateway logs for scheduler errors
+    docker logs pae-nestjs-gateway-service | grep -i scheduler
+    ```
+  </TabItem>
+
+  <TabItem label="Job Failing">
+    **Possible Causes**:
+    - Target service is down
+    - Invalid endpoint URL or path
+    - Network issues
+    - Authentication issues on target service
+
+    **Solution**:
+    ```bash
+    # Check execution history for error details
+    curl http://localhost:3000/_/scheduler/jobs/1/executions \
+      -H "Authorization: Bearer <token>"
+
+    # Test the HTTP endpoint manually
+    curl -X POST http://target-service:4005/api/endpoint
+
+    # Check gateway logs
+    docker logs pae-nestjs-gateway-service | grep -i "job execution"
+    ```
+  </TabItem>
+
+  <TabItem label="Pattern Not Working">
+    **Possible Causes**:
+    - Invalid cron pattern syntax
+    - Job is disabled
+
+    **Solution**:
+    - Validate cron expression at [crontab.guru](https://crontab.guru/)
+    - Verify `enabled: true` in job configuration
+    - Check the pattern field matches standard cron format (5 fields)
+  </TabItem>
+
+  <TabItem label="Dynamic Parameters Not Resolving">
+    **Possible Causes**:
+    - Incorrect parameter syntax
+    - Invalid date format
+
+    **Solution**:
+    - Use correct syntax: `${T:FORMAT}`, `${T-N:FORMAT}`, `${T+N:FORMAT}`
+    - Check supported formats: `YYYY-MM-DD`, `HH:mm:ss`, etc.
+    - Review execution's `jobSnapshot` to see resolved values
+  </TabItem>
+</Tabs>
+
+---
+
+## Best Practices
+
+<CardGrid>
+  <Card title="Use Descriptive Names" icon="pencil">
+    Give jobs clear, descriptive names that indicate what they do (e.g., `daily-order-sync`, `weekly-report-generation`)
+  </Card>
+
+  <Card title="Add Descriptions" icon="document">
+    Include detailed descriptions explaining the job's purpose and any important notes
+  </Card>
+
+  <Card title="Implement Idempotency" icon="approve-check">
+    Ensure job endpoints can handle duplicate executions safely in case of retries
+  </Card>
+
+  <Card title="Monitor Execution History" icon="seti:graphql">
+    Regularly review execution history to detect patterns, failures, or issues
+  </Card>
+
+  <Card title="Use Dynamic Parameters" icon="seti:clock">
+    Leverage `${T...}` parameters for date-based operations instead of hardcoding values
+  </Card>
+
+  <Card title="Test Before Enabling" icon="seti:config">
+    Create jobs with `enabled: false`, test with manual trigger, then enable for production
+  </Card>
+</CardGrid>
+
+---
+
+## Events
+
+The Scheduler Module emits events through NestJS EventEmitter for integration with other modules:
+
+| Event | Description |
+|-------|-------------|
+| `scheduler.job.created` | A new job was created |
+| `scheduler.job.updated` | A job was updated |
+| `scheduler.job.deleted` | A job was deleted |
+| `scheduler.job.execution.started` | A job execution started |
+| `scheduler.job.execution.succeeded` | A job execution completed successfully |
+| `scheduler.job.execution.failed` | A job execution failed |
+
+---
+