Account Management & Task Runs

Relevant source files

The following files were used as context for generating this wiki page:

• app/accounts/[account_id]/page.tsx
• components/AccountDetail/AccountDetailPage.tsx
• components/AccountDetail/TaskRunsTable.tsx
• hooks/useAccountTaskRuns.ts
• types/sandbox.ts
• hooks/useAdminSandboxes.ts

The Account Management & Task Runs system provides administrators with a centralized interface to monitor and analyze background tasks associated with specific user accounts. It specifically focuses on tracking "Pulse" email tasks and general sandbox execution history, offering real-time updates and detailed execution metrics for every automated process triggered within the Recoup platform.

This module serves as a diagnostic and monitoring tool, allowing administrators to verify the status of task executions (such as send-pulse-task), inspect durations, and view specific execution tags. It bridges the gap between high-level account overview and granular task-level metadata.

Sources: components/AccountDetail/AccountDetailPage.tsx:1-5, app/accounts/[account_id]/page.tsx:1-20

Architecture and Data Flow

The system follows a reactive data-fetching pattern using TanStack Query to maintain up-to-date information about account activities. The architecture is composed of a dynamic page route that captures an accountId and passes it through a hierarchy of React components.

Data Acquisition Flow

The flow begins with the useAccountTaskRuns hook, which manages the state and lifecycle of the API request.

Component Hierarchy

Component	Responsibility
AccountDetailPage	Orchestrates the layout, filters "Pulse" runs, and manages modal state for detailed views.
TaskRunsTable	A presentational component that renders task metadata in a tabular format with status badges.
AccountBreadcrumb	Provides navigational context for the current account being viewed.
PulseEmailModal	Displays deep-dive information for a specific selected task run.

Sources: components/AccountDetail/AccountDetailPage.tsx:22-82, components/AccountDetail/TaskRunsTable.tsx:10-15

Task Run Data Model

Tasks are represented by a standardized TaskRun interface. This structure ensures consistency across different types of background processes, whether they are email triggers or sandbox operations.

TaskRun Interface Definition

export interface TaskRun {
  id: string;
  taskIdentifier: string;
  status: string;
  createdAt: string;
  startedAt?: string;
  finishedAt?: string;
  tags: string[];
}

Sources: types/sandbox.ts:41-49

API Interaction

The system interacts with the backend via a specialized fetcher. The endpoint requires administrative Bearer authentication obtained through Privy.

• Endpoint: GET /api/tasks/runs?account_id=<id>
• Authentication: Bearer Token (Privy)
• Polling Interval: 10,000ms (10 seconds)

Sources: hooks/useAccountTaskRuns.ts:10-24

Task Execution Monitoring

The interface distinguishes between specialized tasks and general execution history.

Pulse Run Filtering

The AccountDetailPage specifically filters for tasks where the taskIdentifier is exactly send-pulse-task. These are highlighted as "Pulse Runs" to give admins immediate visibility into the platform's primary automated communication tasks.

Status and Duration Formatting

The TaskRunsTable utilizes utility functions to enhance readability:

1. Status Badges: Uses getStatusBadgeColor to visually represent task states (e.g., success, failure, pending).
2. Duration: Uses formatRunDuration to calculate the delta between startedAt and finishedAt.
3. Timestamps: Displays startedAt if available, falling back to createdAt for pending tasks.

Sources: components/AccountDetail/TaskRunsTable.tsx:28-56

Summary

The Account Management & Task Runs module provides a robust administrative view into the lifecycle of background operations. By combining automated polling, type-safe data structures, and specialized filtering for Pulse email tasks, it ensures that platform administrators can monitor account health and troubleshoot execution failures in real-time.