Node Feature Questionnaire

Purpose

This page defines the question set we should use when investigating the most precise nodes in the Pyle hierarchy.

Examples of target nodes:

• ProductType
• StockHistory
• ShippingService
• PromotionBenefit
• CustomerList

The goal is not to ask every question mechanically. The goal is to use one consistent framework so that every node investigation produces comparable documentation:

• what the node is
• what users can do with it
• how it is configured
• where it appears
• how it integrates with the rest of the platform

How To Use This Questionnaire

1. Pick one precise node from the hierarchy.
2. Answer the questions below using framework code as the primary source of truth.
3. Use admin, storefront, ERP bridge, imports/exports, and configuration as corroborating sources.
4. Mark questions as:
   • Confirmed
   • Partial
   • Not found
   • Ambiguous
5. Produce one reusable node dossier per node.

Minimum completeness checks

A node dossier is incomplete if it does not answer all of these:

• Which channels can manage the node directly, and which only use it indirectly?
• Which channels manage the node itself, which manage a parent record that later creates or mutates it, and which only influence it upstream?
• Which fields are actually editable in each channel?
• If an API route exists, which controller actions and resource serializers actually define its create, update, list, and detail payloads?
• Which fields are user-editable versus merely passed through unchanged during an update?
• Which model fields exist but are not exposed in admin or storefront UX?
• Where does the node appear indirectly inside other resources, forms, or workflows?
• What recalculates, reindexes, syncs, or gets queued when the node changes?
• If a side-effect action exists, what observer, listener, provider, or job actually invokes it?
• Which exact import/export sheets or ERP payloads include it?
• Are all cited file paths real inspected paths, not guessed namespace paths?

Expected Output For Each Node

Every node investigation should produce the same output shape:

1. Node summary
2. User-facing capabilities
3. Configuration and setup
4. Entry points and touchpoints
5. Relationships and dependencies
6. Rules, constraints, and calculations
7. Automations and integrations
8. Permissions and visibility
9. Reporting, search, and observability
10. Open questions and ambiguities

Question Set

1. Identity and Purpose

• What is this node, in plain business language?
• What problem does it solve for the business or for the user?
• Is it primarily a business concept, a supporting record, or a technical helper?
• Who is the main user of this node:
  • admin operator
  • storefront customer
  • internal automation
  • ERP or external system
  • developer only
• What is the closest parent domain and subdomain in the hierarchy?
• Does the code name match the business name used in the UI, or is there a naming mismatch?

2. User-Facing Capabilities

• What can a user do with this node?
• Can a user create it?
• Can a user edit it?
• Can a user delete or archive it?
• Can a user view a list of them?
• Can a user view a detail page or detail panel for it?
• Can a user attach or detach related records from it?
• Can a user trigger special actions on it:
  • calculate
  • duplicate
  • approve
  • confirm
  • cancel
  • sync
  • export
  • import
  • send by email
  • download PDF
• Can a user manage its relationships from another screen even when the node itself is not open?
• What business outcomes become possible because this node exists?

3. Lifecycle and State

• What is the lifecycle of this node from creation to completion or retirement?
• Does it have explicit statuses, states, flags, or stage transitions?
• Are there actions, jobs, or listeners that move it from one state to another?
• Does it support soft delete, hard delete, historical retention, or audit-only behavior?
• Is it manually managed, system-generated, or both?

4. Creation and Management Channels

• Where can this node be created or managed?
• Is it managed in the admin UI?
• Is it exposed in the storefront UI?
• Is it available through API routes?
• Is it created through ERP bridge ingestion?
• Is it created or updated through Excel import or export workflows?
• Is it seeded, generated, or created by background jobs?
• Is it influenced by config files or feature flags?
• Is it only manipulated indirectly through another node?
• Is it created or mutated through a parent node rather than owned directly?
• Which upstream workflows influence it without exposing it as their primary subject?
• For each channel, what exact operations are supported:
  • create
  • edit
  • delete
  • attach/detach
  • bulk import
  • bulk export
  • sync
• For each channel, which specific fields can actually be controlled there?
• If the channel is API-based, which fields are allowed by the controller and which fields are returned by the resource serializer?

5. Admin UX Questions

• Where does this node appear in the admin?
• Is it under a settings area, a transactional area, or a supporting tool area?
• Is there a dedicated screen, table, form, modal, drawer, or nested block for it?
• Which fields can an admin actually control through the UI?
• Which fields are persisted in the update action but are not actually editable because the UI never renders controls for them?
• Which model fields exist but are not currently exposed in the admin UI?
• Which actions are available from the UI but not obvious from the model alone?
• Does it appear in filters, search, dashboards, sidebars, or reports?

6. Storefront UX Questions

• Does this node appear in the storefront directly or indirectly?
• If it appears, where does a customer see it:
  • product page
  • cart
  • checkout
  • my account
  • search
  • category listing
  • order history
• Is it visible as a first-class concept, or only as a side effect of other behavior?
• Does it affect what the customer can do, see, select, or buy?
• Is it exposed directly, or only nested inside another resource or response payload?
• Are any fields hidden, removed, or transformed before reaching the storefront?

7. Configuration Questions

• How is this node configured?
• Are there framework config files that affect its behavior?
• Are there admin settings that affect its behavior?
• Are there env vars or project-level overrides that influence it?
• Are there feature flags or Pennant features gating it?
• Are there service-provider bindings or extension points tied to it?
• Does it rely on seeded reference data or manual setup before it becomes useful?
• Are there import-time defaults, computed defaults, or sentinel values that create special cases?

8. Data Model Questions

• What is the persistent model or models behind this node?
• What are the key fields that define its behavior?
• Which fields are required for it to be valid or useful?
• Which fields are business inputs versus computed outputs?
• Are there casts, accessors, mutators, traits, or derived properties that change its meaning?
• Are there migration clues that reveal deprecated or legacy behavior?
• Is it a standalone record, a pivot, or a helper around another primary record?

9. Relationship Questions

• What other nodes does it belong to?
• What other nodes belong to it?
• Which nodes depend on it to function?
• Which nodes are affected when it changes?
• Are there separate relationship-management workflows for this node:
  • pivot tables
  • attach/detach actions
  • import sheets
  • nested admin forms
• Is it used as:
  • a selector
  • a filter
  • a grouping mechanism
  • an eligibility rule
  • a pricing input
  • a fulfillment input
  • a reporting dimension
• Does it have parent-child or many-to-many structure?

10. Rules, Constraints, and Calculations

• What validations or business rules apply to this node?
• What calculations depend on it?
• Does it change availability, pricing, tax, shipping, permissions, or visibility?
• Are there date, geography, currency, quantity, or customer-specific constraints?
• Are there listeners, policies, or services enforcing hidden rules beyond the controller layer?
• Are there “cannot delete”, “must exist before”, or “only if feature enabled” constraints?
• What downstream side effects happen when it changes:
  • recalculation
  • reindexing
  • sync
  • listener-triggered cleanup
  • queued jobs
• Which observer, listener, event, or provider actually triggers those side effects automatically?

11. Permissions and Visibility

• Who can access this node?
• Are there admin-only capabilities tied to it?
• Are there storefront permissions tied to it?
• Are there policies, roles, or permission codes that govern it?
• Can some users see it but not edit it?
• Can its data be hidden or filtered by customer, region, location, or role?

12. Integrations and Automation

• Does this node participate in ERP bridge synchronization?
• Does it appear in data feeds, imports, or exports?
• Which exact sheets, templates, DTOs, or payloads include it?
• Does it trigger emails, notifications, webhooks, or background jobs?
• Does it integrate with Stripe, TaxJar, search, SFTP, filesystem disks, or another external service?
• Does it have batch jobs, scheduled behavior, or command-line tooling?

13. Search, Reporting, and Observability

• Is this node searchable?
• Does it appear in activity logs, comments, flags, or analytics?
• Does it contribute to dashboards, reports, exports, or audit history?
• Does it have search traits, logging traits, or resource-layer visibility rules that change what operators or customers see?
• Is there operational telemetry around it:
  • run logs
  • sync logs
  • import logs
  • error logs
• If the node changes, where would an operator notice?

14. Entry Points In Code

• Which models define it?
• Which actions manipulate it?
• Which controllers or routes expose it?
• Which resources or serializers expose it, nest it, or hide parts of it?
• Which Livewire components render or manage it?
• Which services, listeners, jobs, or policies contain its real behavior?
• Which migrations reveal the original intended shape of the node?
• Which config files or feature classes affect it?

15. Documentation-Specific Questions

• What are the top 3 things a product person or operator needs to know about this node?
• What are the top 3 things an implementer or integrator needs to know about this node?
• What parts of this node are stable and foundational?
• What parts look legacy, incomplete, project-specific, or overridden downstream?
• What screenshots, tables, or examples would be most useful later?
• What follow-up nodes should be investigated next because they are tightly coupled to this one?

Minimal Node Dossier Template

Use this template when documenting a single node:

# <Node Name>

## What It Is
- Plain-language definition
- Parent domain and subdomain
- Primary users

## What Users Can Do With It
- Create / edit / delete / attach / trigger / export / import
- Main user-visible outcomes

## Where It Is Managed
- Admin
- Storefront
- API
- Excel
- ERP bridge
- Background jobs

## Configuration
- Config files
- Feature flags
- Required setup

## Relationships
- Parent records
- Child records
- Nodes affected by changes

## Rules and Constraints
- Validation
- Calculation rules
- Visibility / eligibility rules

## Integrations and Automation
- ERP bridge
- Imports/exports
- Notifications / jobs / webhooks

## Permissions and Visibility
- Roles
- Policies
- UI visibility

## Evidence
- Models
- Actions
- Routes/controllers
- Livewire/UI
- Services/listeners/jobs
- Migrations/config

## Open Questions
- Unknowns
- Ambiguous or legacy behavior

Agent Prompt Template

Use this prompt shape when sending an agent to explore one node:

Investigate the Pyle node `<NODE_NAME>`.

Goal:
- Produce a feature-oriented node dossier focused on what users can do with this node, how it is configured, where it appears, and how it is used across admin, storefront, API, imports/exports, ERP bridge, and automation.
- Explicitly capture direct management, indirect usage, field-level channel differences, nested resource exposure, and downstream side effects when the node changes.
- Separate direct node ownership from parent-owned workflows and upstream influences; do not collapse all indirect paths into one bucket.
- If API routes exist, inspect the controller and resource classes before treating API payloads as unknown.
- Do not treat fields as UI-editable unless you find an actual rendered form control or explicit writable property for them.
- If a downstream action exists, trace the observer, listener, event, provider, or job that invokes it.

Primary sources:
- packages/framework/src/Models
- packages/framework/src/Actions
- packages/framework/src/Services
- packages/framework/database/migrations
- packages/framework/routes

Corroborating sources:
- packages/admin/src/Livewire/Admin
- packages/admin/config/admin.php
- packages/storefront/src/Livewire/Storefront
- packages/storefront/src/View/Components
- packages/erp-bridge/src/Requests

Answer the questionnaire categories:
- identity and purpose
- user-facing capabilities
- lifecycle and state
- creation and management channels
- admin UX
- storefront UX
- configuration
- data model
- relationships
- rules, constraints, and calculations
- permissions and visibility
- integrations and automation
- search, reporting, and observability
- code entry points
- documentation-specific takeaways

Output format:
- What it is
- What users can do with it
- Where it is managed
- Configuration
- Relationships
- Rules and constraints
- Integrations and automation
- Permissions and visibility
- Evidence
- Open questions

For each claim, cite concrete file paths or route/component clusters.
Only cite file paths you actually inspected. Do not invent paths from namespaces or naming patterns.
Mark each conclusion as Confirmed, Partial, Not found, or Ambiguous.
Do not modify files.

Recommended Order For Future Node Investigations

Start with nodes that are both business-important and highly connected:

1. ProductType
2. ProductOffer
3. ShippingService
4. CustomerGroup
5. FulfillmentRequest
6. OrderItem
7. TaxRate
8. StockHistory

These nodes are good first candidates because they sit at the intersection of data model, user operations, and downstream behavior.