# Decomposition Patterns

> **Library of proven vertical slice patterns** for `/fluent-feature-phase`.
> Select the pattern that best matches the feature's primary domain, then adapt.

---

## Pattern 1: ORDER Workflow Features

**Use when:** Feature is primarily about order processing — validation, routing, fulfilment dispatch.

**Entity progression:** ORDER → FULFILMENT_CHOICE → FULFILMENT

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Order Validation** | ORDER workflow: CREATED → VALIDATED statuses, fraud check rules, validation rules | Order reaches VALIDATED status |
| 2 | **Order Routing** | Fulfilment choice routing, sourcing rules, split logic | Order reaches ROUTED, fulfilment choices created |
| 3 | **Fulfilment Creation** | FULFILMENT workflow, creation rules, initial statuses | Fulfilments created from choices |
| 4 | **User Actions** | User action rulesets (cancel, modify, approve), manifest buttons | Buttons visible in OMS app, events dispatched |
| 5 | **Exception Handling** | Error states, compensation, retry logic, notifications | Graceful handling of edge cases |

### Key ordering rules

- Validation before routing (must know order is valid before sourcing)
- Routing before fulfilment creation (choices must exist)
- Backend before frontend (rulesets before user action buttons)
- Happy path before exceptions

---

## Pattern 2: Fulfilment Features

**Use when:** Feature is primarily about fulfilment processing — pick, pack, ship, complete.

**Entity progression:** FULFILMENT → CONSIGNMENT (articles are line items, not separate workflow entities)

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Fulfilment Lifecycle** | FULFILMENT workflow statuses, base state transitions, assignment | Fulfilment transitions through core statuses |
| 2 | **Pick & Pack** | Inventory allocation, article creation, wave management | Articles created, inventory reserved |
| 3 | **Shipping** | Carrier selection, consignment creation, label generation | Consignment created with tracking |
| 4 | **Completion & Sync** | Fulfilment completion, ORDER status cascade, notifications | Order status reflects fulfilment completion |
| 5 | **Store App UI** | Store app user actions (pick, pack, dispatch), manifest pages | Store app buttons functional |

### Key ordering rules

- Fulfilment statuses before pick/pack (need status graph first)
- Pick before ship (can't ship what isn't picked)
- Backend completion before ORDER sync (cascade needs stable fulfilment states)
- Store app UI last (needs all rulesets deployed)

---

## Pattern 3: Returns Features

**Use when:** Feature involves return order processing — initiation, refund, restock.

**Entity progression:** RETURN_ORDER → CREDIT_MEMO (+ inventory restock via rules)

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Return Initiation** | RETURN_ORDER workflow, creation rules, validation | Return order created and reaches initial status |
| 2 | **Refund Processing** | CREDIT_MEMO creation, amount calculation, approval flow | Credit memo created with correct amounts |
| 3 | **Inventory Restock** | Restock rules, inventory position updates (via INVENTORY_POSITION mutations) | Inventory quantities updated |
| 4 | **Notifications & UI** | Email/webhook notifications, OMS user actions, manifest pages | Customer notified, OMS buttons visible |

### Key ordering rules

- Return order before credit memo (return triggers refund)
- Refund calculation before approval (amounts must be correct)
- Restock after return accepted (don't restock rejected returns)
- Notifications at end (need stable states to report on)

---

## Pattern 4: UI/Manifest Features

**Use when:** Feature is primarily about Mystique UI — new pages, custom components, dashboards.

**Artifact progression:** Backend rules → Settings → Manifest fragments → SDK components → User actions

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Backend Foundation** | Any new rules, workflow rulesets, settings that the UI needs | APIs/data sources available |
| 2 | **Manifest Configuration** | Fragment creation/modification, route structure, page layouts | Pages render with OOTB components |
| 3 | **Custom Components** | SDK component development, FieldRegistry/ComponentRegistry | Custom components render in dev |
| 4 | **User Actions & Polish** | User action form fields, validation, i18n, final styling | End-to-end user interaction works |

### Key ordering rules

- Backend data before UI (pages need queries, forms need user actions)
- OOTB components before custom (validate layout first, then replace with custom)
- Manifest before SDK components (manifest loads the plugin bundle)
- User actions last (need both backend rulesets AND manifest pages)

### Special considerations

- Use `/fluent-mystique-preview` between phases to validate visual progress
- Custom SDK components may need a `/fluent-frontend-build` cycle within Phase 3
- Manifest fragments are independently deployable — good phase boundary

---

## Pattern 5: Integration Features

**Use when:** Feature connects Fluent to external systems — webhooks, APIs, batch imports.

**Flow:** Inbound data → Transform → Store → Outbound notification

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Inbound Pipeline** | Webhook receiver, data validation, entity creation/update rules | External data creates/updates entities |
| 2 | **Transform & Enrich** | Data mapping rules, attribute population, cross-entity lookups | Entities have correct enriched data |
| 3 | **Outbound Dispatch** | Notification rules, webhook sender, response handling | External system receives callbacks |
| 4 | **Error Handling & Retry** | Dead letter queues, retry logic, alerting, fallback paths | Graceful handling of API failures |

### Key ordering rules

- Inbound before transform (need data to transform)
- Transform before outbound (send correct data)
- Happy path before error handling
- Consider external system availability for testing

### Special considerations

- Phase 1 can often be tested with mock data / test events
- Phase 3 may require external system sandbox access
- Error handling phase is critical for production readiness — don't skip

---

## Pattern 6: Multi-Entity Features

**Use when:** Feature spans 3+ entity types with complex cross-entity coordination.

**Common:** ORDER::MULTI → FULFILMENT_CHOICE → FULFILMENT → CONSIGNMENT (+ line items like ARTICLE)

### Phase structure

| Phase | Name | Scope | Test milestone |
|-------|------|-------|----------------|
| 1 | **Primary Entity** | Main entity workflow (usually ORDER), core statuses, validation | Primary entity reaches stable state |
| 2 | **Child Entity Creation** | Rules that create child entities, child workflow base | Children created from parent events |
| 3 | **Child Entity Lifecycle** | Child entity processing (pick/pack/ship or equivalent) | Children progress through own workflow |
| 4 | **Cross-Entity Sync** | Status cascade rules, aggregation (all children done → parent done) | Parent reflects children's state |
| 5 | **Shipping & Consignment** | CONSIGNMENT creation, carrier integration, tracking | Full shipping flow operational |
| 6 | **UI & Actions** | User actions at each entity level, manifest pages per entity | All entity types have working UI |

### Key ordering rules

- Parent before child (parent dispatches child creation)
- Child lifecycle standalone before sync (ensure child works independently)
- Sync after children are stable (cascade rules need reliable child states)
- UI last (needs all entity workflows deployed)

### Merge guidance

- If child entity is simple (< 3 rules), merge Phases 2-3 into one
- If only 2 entity types, use Pattern 1 or 2 instead
- If shipping/consignment is simple, merge Phase 5 into Phase 3

---

## Choosing a Pattern

Use this decision tree:

```
Feature involves...
├── Primarily ORDER processing? → Pattern 1 (ORDER)
├── Primarily fulfilment/warehouse? → Pattern 2 (Fulfilment)
├── Returns or refunds? → Pattern 3 (Returns)
├── Primarily UI/manifest work? → Pattern 4 (UI/Manifest)
├── External system integration? → Pattern 5 (Integration)
├── 3+ entity types with separate workflows? → Pattern 6 (Multi-Entity)
└── Combination? → Start with the dominant pattern, borrow phases from others
```

### Hybrid features

Most real features are hybrids. Strategy:
1. Pick the **primary pattern** (the one covering the most artifacts)
2. **Borrow phases** from secondary patterns where they fill gaps
3. **Merge borrowed phases** with existing phases where artifacts are tightly coupled
4. **Never exceed 6 phases** — merge to consolidate if the hybrid produces more

### Pattern adaptation rules

- **Add phases** when a pattern section has > 10 artifacts → split into two phases
- **Merge phases** when two adjacent phases have < 3 artifacts combined
- **Reorder phases** when project knowledge reveals a non-standard dependency (e.g., integration must come first because all rules depend on external data)
- **Skip phases** when a pattern section doesn't apply (e.g., no returns in a pure order feature)
