> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Sequence statuses design spec

# Sequence Status Workflow - Design Specification

## Executive Summary

This document specifies a redesigned workflow diagram for sequence statuses. The goal is to create a **compact, scannable visualization** that can be understood in under 5 seconds.

***

## Current Problems (Analysis)

| Problem                   | Root Cause                                                                    |
| ------------------------- | ----------------------------------------------------------------------------- |
| **Too tall (720px)**      | Vertical stacking of every state; wastes horizontal space                     |
| **Arrows pointing wrong** | Rejected arrow goes to `completed` (line 99-100) instead of `rework_required` |
| **Complex branching**     | 4D/2D split shown as equal-weight paths; cognitive overload                   |
| **Rework loop unclear**   | Loop-back arrow is tiny text on rotated label; hard to parse                  |

***

## Recommended Approach: **Two-Track Horizontal Layout**

### Why This Approach?

1. **Horizontal flow matches reading direction** - Left-to-right progression is intuitive
2. **Parallel tracks show branching clearly** - 4D track above, 2D track below, visually distinct
3. **Compact width** - Fits in typical doc/readme viewport (800px)
4. **Rework as annotation** - Not a full path; shown as a simple return arrow with clear label

Other approaches considered:

| Approach          | Rejected Because                                |
| ----------------- | ----------------------------------------------- |
| Compact Grid      | Hard to show flow direction; looks like a table |
| Simplified Linear | Loses important 4D/2D branch information        |
| Swimlane          | Adds visual complexity for minimal benefit      |

***

## Dimensions

```
viewBox: "0 0 800 280"
```

* **Width: 800px** - Fits in most markdown viewers, GitHub, docs
* **Height: 280px** - Compact; no scrolling required
* **Padding: 20px** on all sides

***

## Layout Grid

The diagram uses a **5-column horizontal grid**:

| Column | X Position | Content                   | Width |
| ------ | ---------- | ------------------------- | ----- |
| 1      | 20-140     | Initial states (stacked)  | 120px |
| 2      | 180-300    | Labeling states (stacked) | 120px |
| 3      | 340-460    | Review states (stacked)   | 120px |
| 4      | 500-620    | Final states (stacked)    | 120px |
| 5      | 660-780    | End state                 | 120px |

**Row positions:**

* **Track labels**: y=20 (small text)
* **4D track**: y=60 (center of state boxes)
* **2D track**: y=140 (center of state boxes)
* **Shared path**: y=100 (center, for converged flow)
* **Legend**: y=250

***

## State Positions (Exact Coordinates)

### Column 1: Initial (Stacked Vertically, Centered)

All three initial states share one column, shown as a compact vertical stack:

| State                  | x           | y   | Notes                |
| ---------------------- | ----------- | --- | -------------------- |
| `unattempted`          | 80 (center) | 60  | Top of stack         |
| `pending`              | 80 (center) | 100 | Middle               |
| `ready_for_annotation` | 80 (center) | 140 | Bottom; branch point |

**Box dimensions:** 130x28 each (compact)

### Column 2: Labeling (Two Tracks)

| State         | x            | y   | Track    |
| ------------- | ------------ | --- | -------- |
| `labeling_4d` | 240 (center) | 60  | 4D track |
| `labeling_2d` | 240 (center) | 140 | 2D track |

**Box dimensions:** 110x28 each

### Column 3: Review (Two Tracks + Transition)

| State          | x            | y   | Track                       |
| -------------- | ------------ | --- | --------------------------- |
| `review_4d`    | 400 (center) | 60  | 4D track                    |
| `ready_for_2d` | 400 (center) | 100 | Transition (between tracks) |
| `review_2d`    | 400 (center) | 140 | 2D track                    |

**Box dimensions:** 100x28 (review\_4d, review\_2d), 95x24 (ready\_for\_2d - smaller, transitional)

### Column 4: Final Review

| State             | x            | y   | Notes                               |
| ----------------- | ------------ | --- | ----------------------------------- |
| `final_review`    | 560 (center) | 100 | Centered vertically                 |
| `rework_required` | 560 (center) | 180 | Below, connected by rejection arrow |

**Box dimensions:** 110x28 (final\_review), 120x24 (rework\_required - red accent)

### Column 5: Completion

| State               | x            | y   | Notes              |
| ------------------- | ------------ | --- | ------------------ |
| `completed`         | 720 (center) | 80  | Upper              |
| `customer_approved` | 720 (center) | 120 | Lower; final state |

**Box dimensions:** 100x28 each

***

## Arrow Paths (Connections)

### Happy Path (Main Flow)

All arrows use **gray (#71717a)** with **arrowhead marker**.

| From                   | To                     | Path Type           | Notes                                 |
| ---------------------- | ---------------------- | ------------------- | ------------------------------------- |
| `unattempted`          | `pending`              | Short vertical      |                                       |
| `pending`              | `ready_for_annotation` | Short vertical      |                                       |
| `ready_for_annotation` | `labeling_4d`          | Diagonal up-right   | Branch to 4D                          |
| `ready_for_annotation` | `labeling_2d`          | Horizontal right    | Branch to 2D (or straight if 2D-only) |
| `labeling_4d`          | `review_4d`            | Horizontal right    |                                       |
| `review_4d`            | `ready_for_2d`         | Diagonal down-right |                                       |
| `ready_for_2d`         | `labeling_2d`          | Diagonal down-right | Dotted/dashed (joining 2D track)      |
| `labeling_2d`          | `review_2d`            | Horizontal right    |                                       |
| `review_2d`            | `final_review`         | Diagonal up-right   | Converge to center                    |
| `final_review`         | `completed`            | Horizontal right    |                                       |
| `completed`            | `customer_approved`    | Short vertical      |                                       |

### Rejection Path (Rework Loop)

Uses **red (#ef4444)** stroke and arrow.

| From              | To                | Path Type                                                            | Label                |
| ----------------- | ----------------- | -------------------------------------------------------------------- | -------------------- |
| `final_review`    | `rework_required` | Short vertical down                                                  | "rejected" label     |
| `rework_required` | `labeling_2d`     | Curved return arrow (goes left, under the diagram, back to column 2) | "rework" small label |

**Rework arrow implementation:**

* Start: right side of `rework_required`
* Curve: down and left, passing beneath the main flow
* End: bottom of `labeling_2d` or `labeling_4d` (depending on what type of rework)
* Use a **simple curved path** or **rounded corner path**, not complex bezier

**Simplified rework alternative:** Instead of a complex return arrow, show a simple annotation:

* Small red text below `rework_required`: "returns to labeling"
* This avoids arrow chaos while communicating the concept

***

## Color Scheme (Minimal)

Use the existing color scheme but simplified:

| Category                                                 | Fill    | Stroke           | Text    |
| -------------------------------------------------------- | ------- | ---------------- | ------- |
| **Queue** (unattempted, pending, ready\_for\_annotation) | #27272a | #3f3f46          | #e4e4e7 |
| **Labeling** (labeling\_4d, labeling\_2d)                | #1e1b4b | #6366f1          | #e4e4e7 |
| **Review** (review\_4d, review\_2d, final\_review)       | #422006 | #f59e0b          | #e4e4e7 |
| **Transition** (ready\_for\_2d)                          | #27272a | #3f3f46 (dashed) | #a1a1aa |
| **Complete** (completed, customer\_approved)             | #052e16 | #22c55e          | #e4e4e7 |
| **Rework** (rework\_required)                            | #450a0a | #ef4444          | #e4e4e7 |
| **Arrows** (normal)                                      | -       | #71717a          | -       |
| **Arrows** (rejection)                                   | -       | #ef4444          | -       |

***

## Typography

| Element                         | Font                  | Size | Color   |
| ------------------------------- | --------------------- | ---- | ------- |
| State labels                    | system-ui, sans-serif | 11px | #e4e4e7 |
| Track labels (4D, 2D)           | system-ui, sans-serif | 10px | #71717a |
| Arrow labels (rejected, rework) | system-ui, sans-serif | 9px  | #ef4444 |
| Legend text                     | system-ui, sans-serif | 9px  | #a1a1aa |

***

## Visual Hierarchy

1. **Primary:** State boxes and their labels (most prominent)
2. **Secondary:** Main flow arrows (gray, moderate weight)
3. **Tertiary:** Track labels "4D path" / "2D path" (faded)
4. **Accent:** Rejection/rework path (red, draws attention to exception flow)
5. **Reference:** Legend (bottom, small)

***

## Rework Loop Design Decision

**Recommendation: Use annotation, not complex arrow**

Instead of drawing a complex curved arrow that loops back:

```svg theme={null}
<!-- Below rework_required box -->
<text x="560" y="210" text-anchor="middle" fill="#ef4444" font-size="9">
  returns to labeling
</text>
```

This is cleaner and avoids:

* Arrow crossing other arrows
* Visual clutter
* Ambiguity about which labeling state it returns to

**If the implementer wants the arrow version:**

* Draw a red dashed path from `rework_required` going DOWN, then LEFT under the diagram, then UP to `labeling_2d`
* Keep stroke thin (1px) and dashed to differentiate from main flow

***

## Legend (Compact, Horizontal)

Position: Bottom of diagram (y=250), centered horizontally

```
[Queue] [Labeling] [Review] [Complete] [Rework]
```

Each legend item: 12x12 square + label text, spaced 60px apart.

***

## Implementation Notes for the Implementing Agent

1. **Start with the grid** - Lay out columns first, then place boxes
2. **Draw happy path first** - All the gray arrows for normal flow
3. **Add rejection/rework last** - So it overlays correctly
4. **Test readability** - View at 100% zoom in browser; all text must be legible
5. **Keep stroke widths consistent** - 1.5px for arrows, 1.5-2px for box borders
6. **Rounded corners** - rx="5" for all state boxes (friendly, modern look)

***

## Expected Result

A **compact horizontal workflow** that:

* Shows the complete sequence status flow at a glance
* Clearly distinguishes 4D and 2D tracks
* Makes the happy path obvious (left-to-right)
* Shows rework as an exception path without cluttering the main flow
* Fits in 800x280 pixels

***

## Comparison: Before vs After

| Metric               | Current                    | New Design                    |
| -------------------- | -------------------------- | ----------------------------- |
| Dimensions           | 400x720                    | 800x280                       |
| Aspect ratio         | Portrait (0.56)            | Landscape (2.86)              |
| Scannable in 5 sec   | No                         | Yes                           |
| Branch logic clear   | No                         | Yes (stacked tracks)          |
| Rework arrow correct | No (points to wrong state) | Yes (or uses text annotation) |
| Legend included      | Yes                        | Yes (compact)                 |

***

## File Output

The implementing agent should save the new SVG to:

```
docs/images/workflows/sequence-statuses.svg
```

(Overwrites the existing file)