@hailer/mcp 1.3.21 → 1.3.32

package/.claude/skills/hailer-design-patterns/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: hailer-design-patterns
+description: Hailer workspace structural design patterns — when to split into two workflows vs keep flat, parent/child lifecycle shapes, row progression vs row generation, phase rationalization, approval gates, conditional fields, and dashboard composition. Load before planning workspace structure or writing a PRD.
+---
+
+# Hailer Design Patterns
+
+Reference patterns for structuring Hailer workspaces. Apply when planning workflows, writing PRDs, or reviewing workspace architecture.
+
+## Workflow Structure
+
+**Two Workflows: Parent + Children**
+Common pattern for any entity that groups operational sub-records. Two flavors:
+
+- **Header + Rows** — transactional entities with totals: orders/order rows, invoices/invoice rows, quotes/quote lines. Lines aggregate to header (totals via function fields).
+- **Parent + Children via ActivityLink** — entities that contain related records without strict line-item semantics: Customer/Contacts, Project/Tasks, Customer/Sites, Equipment/Maintenance entries.
+
+Use either flavor when one record needs to contain or group multiple sub-records. Don't apply to genuinely flat records (weather logs, daily reports, observations, attendance, sensor readings) — those are single-workflow.
+
+| Header/Parent | Rows/Children | Links To |
+|--------|------|----------|
+| Sales Orders | Order Rows | Products, Services |
+| Purchase Orders | PO Rows | Products, Suppliers |
+| Invoices | Invoice Rows | (or linked Order Rows) |
+| Quotes | Quote Lines | Products, Services |
+| Projects | Tasks | - |
+| Customers | Contacts | - |
+| Equipment | Maintenance Entries | - |
+
+**Why two workflows:** Separate workflows for parent and children enable independent phases, unlimited count, per-record state, aggregation via function fields, and cleaner reporting.
+
+**Naming convention (Finnish):** Base + "rivit" suffix
+- Tilaukset -> Tilausrivit
+- Myyntitilaukset -> Myyntitilausrivit
+- Laskut -> Laskurivit
+
+**Row Source Flexibility:** Rows don't have to be one workflow. A Sales Order might link to Product Rows + Service Rows + Production Rows if types have different fields or processes.
+
+---
+
+**Dataset vs Workflow**
+
+| Type | When to Use | Examples | Phase Behavior |
+|------|-------------|----------|----------------|
+| **Dataset** | Static/reference data | Products, Customers, Suppliers | Categories (activities don't transition) |
+| **Workflow** | Lifecycle/state data | Orders, Invoices, Tasks | Phases (activities progress through stages) |
+
+- **Dataset:** Activities are categorized but don't "move" - a Product stays in "Electronics" category
+- **Workflow:** Activities progress through phases - an Order moves from "Draft" -> "Confirmed" -> "Shipped"
+
+This affects phase design:
+- Datasets: phases = categories (no transitions expected)
+- Workflows: phases = lifecycle stages (transitions matter)
+
+---
+
+**Master Data vs Transactional**
+
+| Type | enableUnlinkedMode | Examples |
+|------|-------------------|----------|
+| Master data | `true` (independent) | Customers, Products, Suppliers, Employees |
+| Transactional | `false` (requires context) | Orders, Invoices, Quotes, their Rows |
+
+---
+
+**Domain Prefixes (Large Workspaces)**
+For 30+ workflows, use prefixes to organize:
+- `INV-` Invoicing (INV-Laskut, INV-Laskurivit)
+- `VH-` Warehouse (VH-Varastopaikat, VH-Nimikkeet)
+- `MYY-` Sales (MYY-Tilaukset, MYY-Tilausrivit)
+- `OST-` Purchasing (OST-Tilaukset, OST-Tilausrivit)
+
+---
+
+**Phase-Specific Field Visibility**
+
+Different phases can show different fields. Plan this during design:
+
+**Workflow example (Orders):**
+| Phase | Fields Shown |
+|-------|--------------|
+| Draft | Customer, Items, Notes |
+| Confirmed | + Confirmed Date, Confirmed By |
+| Shipped | + Ship Date, Tracking Number |
+| Invoiced | + Invoice Number, Invoice Date |
+
+**Dataset example (Products):**
+| Category | Fields Shown |
+|----------|--------------|
+| Physical Products | Name, Price, + Dimensions, Weight, Stock |
+| Services | Name, Price, + Hourly Rate, Duration |
+| Both | Name, Description, Price (shared) |
+
+Document in the design plan which fields appear in which phases.
+
+---
+
+**Phase Rationalization for Apps**
+
+When building apps, document which phases to show per user role:
+
+| View | Phases Fetched | Rationale |
+|------|----------------|-----------|
+| Sales Dashboard | Active only | Hide internal WIP from sales team |
+| Manager View | Draft + Active | Managers need WIP visibility |
+| Admin Panel | All phases | Full access for admin |
+| Public Portal | Active only | No internal data exposed |
+| Insights/Reports | Active only | Accurate counts, no draft duplicates |
+
+---
+
+## Row Lifecycle Patterns
+
+**Pattern A: Rows progress through phases (simpler)**
+```
+Order Row -> "Ordered" -> "Shipped" -> "Invoiced"
+```
+- Same activity, phase changes
+- Invoice workflow links to the rows
+- Works when 1:1 (ordered = shipped = invoiced)
+- Good for simple processes without integrations
+
+**Pattern B: Rows generate new activities (complex)**
+```
+Order Row -> creates -> Invoice Row
+           -> creates -> Delivery Row
+```
+- Separate workflows for each document type
+- Use when:
+  - Partial invoicing (invoice 3 of 5 rows now)
+  - Consolidated invoicing (multiple orders -> one invoice)
+  - Accounting integration needs clean invoice data
+  - Different pricing (order price != invoice price)
+
+**Decision Guide**
+
+| Scenario | Approach |
+|----------|----------|
+| Simple tracking, no integrations | Rows progress through phases |
+| 1:1 order-to-invoice | Rows progress through phases |
+| Partial deliveries/invoices | Separate row workflows |
+| Accounting integration (Netvisor, etc.) | Separate invoice rows |
+| Multiple orders -> one invoice | Separate invoice rows |
+
+---
+
+## Integration Patterns
+
+| Need | Solution |
+|------|----------|
+| Phase cascades (parent -> children, child phase load-bearing) | External automation reading function-field JSON payload (monolith webhook or microservice) |
+| Child reflects parent phase (display only) | Function field on child reading parent's phase via `>` link variable |
+| Simple notifications/external tasks | Zapier webhooks |
+| Complex automations, scheduled jobs | Project Monolith |
+| Accounting sync (Netvisor, Procountor) | Monolith integration |
+| No integration (manual export) | Export insight (CSV) |
+
+**Export insight fallback:** When no direct integration, create an insight that formats data for CSV download. User imports manually to accounting.
+
+---
+
+## Document Templates
+
+Used for: Invoices, Quotes, Order Confirmations, Delivery Notes, Reports.
+Templates pull data from header workflow + linked rows. Typically PDF format with company branding. See `sdk-document-templates` skill for push format and field reference shapes.
+
+---
+
+## Single Workflow Pattern
+
+Not everything needs two workflows. Single workflows work for flat records — entities without sub-items, totals, or per-line state:
+- Simple task tracking (no line items), daily reports
+- Suppliers, inventory items
+- Weather logs, sensor data, observations
+- Attendance records, event logs, meeting notes
+
+---
+
+## "Unit of Listing" Pattern for Outbound Marketplace Integrations
+
+When a product needs to be listed on an external marketplace, model each listing as its own activity in a dedicated workflow (e.g. `Tavararahaksi myynnit`), linked via ActivityLink back to the source product. Phases map 1:1 to remote endpoint actions: Luonnos → upsert:draft, Myynnissä → upsert:published, Myyty/Peruttu → deactivate.
+
+Benefits: enables relisting, per-listing overrides (price, mode, publish timing), keeps the product workflow clean, lifecycle is visible in Hailer UI.
+
+Anti-pattern: adding marketplace-specific phases directly to the source product workflow — it pollutes the product schema and prevents multiple concurrent listings.
+
+---
+
+## Feature Composition Patterns
+
+How common product patterns from tools like Windmill, n8n, Retool, NocoBase, and Budibase map onto Hailer-native primitives.
+
+---
+
+### Approval-Step UIs
+
+**Hailer-native recipe — phases + ball tracking:**
+
+Model the approval gate as two terminal `possibleNextPhase` targets (e.g. Approved, Rejected) branching from a single decision phase (e.g. Pending Approval). Ball tracking hands the active holder — the approver — the activity at that phase:
+
+```typescript
+// phases.ts — auto-assign ball to the approver field on phase enter
+{
+  name: 'Pending Approval',
+  ballAction: MyWorkflow_FieldIds.approver_user_9f2,  // users-type field
+}
+```
+
+When the activity enters Pending Approval, the `ball.auto_assigned` signal fires and the ball holder (approver) receives it as a discussion participant. They then move the activity to Approved or Rejected via the Hailer UI (or a custom app button calling `activity.update([{_id, phaseId}], {})`). The binary decision is the phase transition itself — no external webhook URL required.
+
+The relevant workflow archetype is **Approval Flow** (`hailer-workflow-archetypes`): intake phase → decision phase with two terminal targets.
+
+**Availability:** Ball tracking requires the network-level `ballTracking` license restriction (enabled manually in the database by Hailer staff — no self-serve toggle) plus `enableBallTracking: true` on the workflow. Verify the customer's deployment surfaces the UI before promising an interactive approval button.
+
+Implementation skills: `sdk-ws-config-skill` (phase config, `ballAction`), `hailer-workflow-archetypes` (Approval Flow archetype skeleton).
+
+---
+
+### Multi-Step Wizards
+
+Two complementary approaches, depending on whether the wizard persists state in Hailer or is purely UI-side:
+
+**Option A — phase-as-step (state persisted):** Map each wizard step to a workflow phase. The activity advances one phase per completed step via `activity.update([{_id, phaseId: nextPhaseId}], {})`. This is the **Pipeline** archetype (`hailer-workflow-archetypes`): each phase is a named lifecycle stage. Phase-specific field visibility lets each step surface only the relevant fields.
+
+**Option B — in-app multi-screen (state in React):** In a custom app, manage wizard state with a `currentStep` variable and render step components conditionally:
+
+```typescript
+// In-app wizard — step state lives in React
+const [step, setStep] = useState<'details' | 'review' | 'confirm'>('details');
+
+{step === 'details' && <DetailsStep onNext={() => setStep('review')} />}
+{step === 'review'  && <ReviewStep  onNext={() => setStep('confirm')} />}
+{step === 'confirm' && <ConfirmStep onSubmit={handleCreate} />}
+```
+
+Push suggestions straight into the same staged state the commit action reads — avoid a separate review zone that a user can skip.
+
+A single-activity final `hailer.activity.create()` call fires when the user confirms, carrying all field values collected across steps.
+
+Implementation skills: `hailer-workflow-archetypes` (Pipeline archetype, phase transitions), `hailer-app-builder` (wizard pattern, `activity.create` format).
+
+---
+
+### Conditional Field Visibility
+
+Hailer's core workflow UI does not have a native no-code field-level show/hide rule editor. Two available approaches differ by where the logic lives:
+
+**App-side conditional render (recommended for form/display logic):** In a custom app, render fields conditionally based on other field values read from the activity or from local form state:
+
+```tsx
+// Show a follow-up field only when a condition is met
+const fieldValue = activity.fields?.[FIELD_IDS.category] as string;
+
+{fieldValue === 'premium' && (
+  <FormField label="Premium tier" fieldId={FIELD_IDS.premiumTier} />
+)}
+```
+
+This requires building a custom app; it does not affect the built-in Hailer activity sidebar.
+
+**Function fields (compute / derive, not hide/show):** A `function`-type field can derive a value from other fields synchronously in isolated-vm. Useful for display-only computed values (e.g. show a risk score when a linked field exceeds a threshold), but it does not hide or show other fields — it produces a new computed value.
+
+```typescript
+// Computed display field — derives a label from another field's value
+functionVariables: { category: { type: '>', data: [LINK_FIELD_ID, CATEGORY_FIELD_ID] } }
+// body:
+return dep.category === 'premium' ? 'High priority' : 'Standard';
+```
+
+For a no-code conditional-show experience without a custom app, the closest option is phase-specific field visibility (phase-level field sets are configurable per workflow phase in the core UI).
+
+Implementation skills: `hailer-app-builder` (conditional render, field value reading), `sdk-function-fields` (`>` forward-link variable shape, isolated-vm constraints).
+
+---
+
+### Computed Dashboards
+
+Define an insight with aggregation SQL. Insights run against the live Hailer SQLite engine:
+
+```sql
+-- Pipeline value by phase with CASE bucketing
+SELECT
+  CASE
+    WHEN d.value < 10000  THEN '1_small'
+    WHEN d.value < 100000 THEN '2_mid'
+    ELSE                       '3_large'
+  END AS bucket,
+  COUNT(*) AS "Kauppoja",
+  COALESCE(SUM(d.value), 0) AS "Yhteensä"
+FROM deals d
+GROUP BY bucket
+ORDER BY bucket
+```
+
+In a custom app, load the insight via `hailer.insight.data(insightId, {})` and render the result rows as charts or stats cards:
+
+```typescript
+const data = await hailer.insight.data(insightId, { update: true });
+// data.headers: string[]
+// data.rows: (string | number | null)[][]
+```
+
+Implementation skills: `sdk-insight-calculations` (aggregation recipes, CASE patterns), `hailer-app-builder` (insight API in apps, `hailer.insight.data()`, response shape).
+
+---
+
+## Anti-Patterns
+
+### "Draft entity for staging" when resource bindings are write-once-at-creation
+
+Creating an entity early (draft) and planning to attach resources to it later only works if the platform supports post-creation attachment. Verify the "fill later" half before designing the flow.
+
+**Hailer example:** File IDs bind at `activity.create`. A draft activity + later file attach does not work — files uploaded before activity creation can't be retroactively bound. Instead, defer the activity creation until all uploads complete, then pass the file IDs in the create call.
+
+**General rule:** If an entity's resource bindings are write-once-at-creation, don't model staging via that entity. Defer creation, not data. This applies to any platform where attachments, links, or sub-resources can only be set at creation time.
+
+Design check: before specifying a "create early, fill later" flow, confirm the API has a working "fill later" endpoint and test it. If it doesn't exist or doesn't work, redesign to collect all data first.