Untitled

# Work Order Task Processing Flow

This document describes the **end-to-end process** of how tasks (e.g., work orders, CMM, etc.) are saved and processed asynchronously using **AWS SQS, Lambda, Postgres, and NAMS**.

It also outlines error handling, **retry logic (5 attempts)**, and how the architecture is designed to be **scalable and extensible**.

---

## 1) High-Level Flow

1. **UI (Frontend)**
   - User saves a task.
   - The backend saves the task into **Postgres** with status = `P` (**Processing**).
   - A message is published to **AWS SQS**, containing:
     - `type` (e.g., `save_work_order_tasks`)
     - Payload (work order number, task ID, etc.).

2. **SQS → Lambda**
   - The SQS message triggers a **Lambda function**.
   - Lambda inspects the `type` field and uses a **mapper** to select the correct handler/service.
   - Example: `type = save_work_order_tasks` → handled by the Work Order handler.

3. **Lambda Processing with Retries**
   - Lambda attempts to process the message (save to **NAMS** and **Postgres**).
   - If **processing succeeds**:
     - Postgres status is updated to **blank** (`""`) = Success.
   - If **processing fails**:
     - The message is returned to **SQS**.
     - SQS retries delivering the same message up to **five (5) times**.
     - After each retry, Lambda attempts processing again.

4. **Failure After Max Retries**
   - If all **5 retries fail**, then Postgres is updated with:
     - `status = E` (**Error**).
     - `lastErrorMessage` = the final error returned.

---

## 2) Sequence Diagram (with 5 retries)

> Note: Mermaid does not require explicit `break` to exit a loop; the diagram below simply shows that on success the loop ends, otherwise SQS re-delivers and Lambda retries up to 5 times.

```mermaid
sequenceDiagram
    participant UI as UI (Frontend)
    participant BE as Backend
    participant SQS as AWS SQS
    participant L as Lambda
    participant NAMS as NAMS DB
    participant PG as Postgres DB

    UI->>BE: Save Task
    BE->>PG: Save Task (status = P)
    BE->>SQS: Publish Message (type, payload)

    loop Up to 5 delivery attempts
        SQS-->>L: Trigger Lambda with message
        L->>L: Map type to handler
        L->>NAMS: Save to NAMS
        L->>PG: Save to Postgres

        alt Processing succeeded
            PG->>PG: Update status = "" (Success)
        else Processing failed
            Note over SQS,L: Return message to SQS for retry
        end
    end

    alt Exhausted retries (failed 5 times)
        PG->>PG: Update status = E and save lastErrorMessage
    end
```

---

## 3) System Architecture (Flowchart)

```mermaid
flowchart TD
    A[UI - User saves Task] --> B[Backend]
    B -->|Save with status = P| C[Postgres DB]
    B -->|Publish Message| D[AWS SQS]

    D --> E[Lambda Function]
    E -->|Check type and map handler| F[Handler: save_work_order_tasks]
    F --> G[NAMS DB]
    F --> H[Postgres DB]

    H -->|On Success| I[Update status = "" (Success)]
    H -->|On Failure| D

    D -.->|Retry up to 5 times| E
    E -->|If still failing after 5 retries| J[Update status = E and save lastErrorMessage]
```

---

## 4) Extensibility

- Each SQS message contains a `type` field.
- The Lambda function maps `type` → handler.
- To support a new workflow (e.g., **SaveCMM**):
  1. Define the new `type` (`SaveCMM`).
  2. Implement a new handler in the Lambda function.
  3. Publish messages with `type = SaveCMM`.
- This pattern keeps the pipeline stable and **plug‑and‑play** for new message types.

---

## 5) Error Tracking & Status Codes

**Postgres** is the tracking source of truth.

- `status`
  - `P` = Processing (set by backend before enqueueing to SQS)
  - `""` (blank) = Success (set by Lambda after successful saves)
  - `E` = Error (set by Lambda after 5 failed attempts)
- `lastErrorMessage`
  - Stores the last error message returned by the Lambda when retries are exhausted.

---

## Appendix: Example SQS Message Payload

```json
{
  "type": "save_work_order_tasks",
  "tasks": [
    {
      "workOrderNbr": "WO-123",
      "taskId": "task-456",
      "facility": "Nuclear Plant A",
      "discipline": "Maintenance",
      "crew": "Team Alpha",
      "workDate": "2025-01-01",
      "attributes": ["safety", "urgent"],
      "resources": ["technician", "tools"]
    }
  ]
}
```

```