Background Task Scheduler (Cron)

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/background-task-scheduler/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

Core free module that enables background job scheduling (cron-like). Merchants can schedule events: ‘flash sale starts at midnight UTC’, ‘inventory reconciliation weekly’, ‘email reminder 3 days after purchase’. The system provides a declarative scheduler API; merchant defines cron expression and callback hook; core invokes the hook at specified time.

The problem

Currently, merchants cannot schedule events to trigger automatically. A flash sale must be manually activated by logging in at midnight. With a scheduler, sales start automatically, promotional pricing applies without manual intervention, and inventory reconciliation runs weekly without staff involvement.

What it does

• Cron-based scheduling: support standard cron expressions (0 0 * * * for daily at UTC 00:00)
• Scheduled hooks: merchants define hook ‘schedule:flash-sale-start’ → callback receives { event_name, scheduled_at, shop_id }
• Built-in scheduled tasks: price promotions, gift card expiration checks, loyalty point expiration
• Task visibility in admin: ‘Scheduled Tasks’ dashboard shows upcoming jobs (flash sale starts in 2h, reconciliation runs weekly)
• Manual trigger: admin can run a scheduled task immediately (skip waiting until cron fires)
• Error handling: if scheduled task fails (network error, payment processor down), retry with exponential backoff, log error to audit trail
• Timezone support: merchant’s shop timezone (e.g., EST, CET) is used for cron expressions, not server timezone

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Complex workflow orchestration (job chains, conditionals); use a paid workflow automation module for that
• Scheduled customer communications (email/SMS campaigns; see future marketing module)

Data model

Add scheduled_tasks table: { id, shop_id, task_name, cron_expression, hook_name, last_run_at, next_run_at, is_active }. Add task_run_log table: { id, task_id, run_at, status (‘success’, ‘failed’), error_message, duration_ms }. No migration needed; new tables only.

API

• POST /admin/scheduled-tasks — create new scheduled task with cron and hook name
• GET /admin/scheduled-tasks — list all scheduled tasks with next run time
• PUT /admin/scheduled-tasks/:id — edit cron or hook
• POST /admin/scheduled-tasks/:id/run-now — manually trigger task immediately
• GET /admin/scheduled-tasks/:id/logs — view run history and errors

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Add ‘Scheduled Tasks’ in Settings > Advanced. List: task name, cron expression, hook name, status (active/paused), next run time. Create task form: name, cron builder (UI calendar + time picker, or raw cron input), hook dropdown (list available hooks like ‘price:apply-promotion’). View logs: table of run_at, status, duration, error message.

The seam — why this is core

Core owns the scheduler infrastructure and cron evaluation. Merchants define which hooks to trigger and when. Paid modules (like scheduled-promotions-manager) add UI for defining complex schedules without cron syntax.

Currently documented as a limitation (derive-on-WRITE). Scheduled events are table stakes. Enables scheduled sales, inventory reconciliation, and pricing tiers.

Dependencies

• Hook system (must exist to allow plugins to register scheduled-task hooks)
• Audit log system (to record task runs and errors)

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• Cron ‘0 0 * * *’ (daily at UTC 00:00) triggers hook ‘price:apply-promotion’ at specified time
• Admin can input raw cron or use calendar UI: select ‘every day’, time ‘08:00 CET’ → converts to cron relative to shop timezone
• Scheduled task fails (API error); system retries after 5 minutes, then 10 minutes, then 20 minutes; after 3 failures, sends alert email
• Admin clicks ‘Run Now’ for a scheduled task; task executes immediately and logs success/failure
• Multiple shops can have independent scheduled tasks (task_id is scoped to shop_id)

Risks

If cron expression is not validated (always use cron parser library to verify syntax before saving). If next_run_at is computed once and never recalculated, scheduler drifts over time (recalculate on every run). If task runs in the same process as the web server, long-running tasks block checkout requests (use a separate worker process/queue).

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.