Feature Specification: Scheduling & Execution

1. Overview & Vision

Scheduling & Execution is the operational engine of the Auto Report module. It manages the lifecycle of report generation, from time-based cron triggers to manual "Run Now" requests, ensuring that reports are produced reliably and that every run is documented for auditability.

2. Personas & Stakeholders

Persona	Goal
Admin	Set up recurring reports and monitor their success.
DevOps	Ensure background workers are healthy and processing jobs.

3. User Stories

• As an admin, I want to set a report to run every Friday at 5 PM so I have a summary ready for the weekend.
• As an admin, I want to manually trigger a report run to capture a snapshot of current data before a big meeting.
• As an admin, I want to see why a scheduled report failed so I can fix the data source.

4. Functional Requirements (FR)

• REQ-SCH-001: Cron-based automated scheduling (Daily, Weekly, Monthly).
• REQ-SCH-002: Manual "Run Now" trigger for any active template.
• REQ-SCH-003: Persistence of generation history (execution_logs).
• REQ-SCH-004: Real-time status tracking (Pending, Running, Success, Error).

5. Non-Functional Requirements (NFR)

• Reliability: Failed runs MUST capture a detailed stack trace or error message.
• Concurrency: Support for parallel execution of multiple report templates.

6. Business Logic & Rules

• Cron Precision: Precision within 1 minute of the scheduled time.
• Retry Logic: Automated retry (up to 3 times) for transient network errors.
• Snapshotting: Every successful run MUST save a snapshot of the input context used.

7. User Interface (UI/UX)

• Run History: Table view with chronological logs and status icons.
• Schedule Editor: Simple dropdowns for common frequencies + custom Cron input.
• Execution Monitor: Toast notifications when a manual run completes.

8. Information Architecture

• "Run History" tab in the module dashboard.
• Link to execution details from the template list.

9. Data Model & Persistence

• Table: execution_logs.
• Fields: templateId, status, startedAt, completedAt, errorMessage.

10. API & Service Layer

• POST /templates/:id/run
• GET /executions
• GET /executions/:id

11. Integration Patterns

• Mastra: Uses the Mastra workflow engine for task queuing and cron management.
• Shell Events: (Future) Triggers a platform-wide event on generation success.

12. Security & Permissions

• RBAC: reports:run required for manual triggers; reports:view for history.
• Isolation: History is strictly scoped to the user's organizationId.

13. Error Handling & Resilience

• Timeout: Hard timeout of 5 minutes for generation to prevent hung workers.
• Partial Failure: Log if some data sources failed but the AI still produced a report.

14. Performance & Scalability

• Distributed worker architecture to handle high-volume scheduling across tenants.
• Database indexing on startedAt for fast history retrieval.

15. Globalization & i18n

• Timezone-aware scheduling based on the organization's configured timezone.

16. Accessibility (a11y)

• Aria-live regions for status updates in the execution monitor.

17. Observability & Analytics

• Tracking of "Average Execution Time" per template.
• Monitoring of "Worker Queue Depth".

18. Testing & Quality

• Unit tests for the cron parsing logic.
• Integration tests for the Mastra worker lifecycle.

19. Constraints & Assumptions

• Assumes that the Mastra worker process is running and connected to the database.

20. Future Enhancements

• Webhook triggers (Run report when external event X occurs).
• Slack/Discord integration for status alerts.