Node Documentation Guidelines

Purpose

This page defines the authoring standard for node-level documentation in Pyle.

Use it when writing one page for one precise node such as:

• ProductType
• StockHistory
• ShippingService
• CustomerGroup
• FulfillmentRequestItem

The goal is to make node pages comparable, reviewable, and reusable across the whole hierarchy.

Scope

Node pages are not full architecture documents and they are not generic model references.

Each node page should answer a practical product and operations question:

• what this node is
• what a user can do with it
• where it is managed
• what fields matter
• how it affects the rest of the platform

Evidence Standard

Use sources in this order:

1. packages/framework/src/Models
2. packages/framework/src/Actions
3. packages/framework/src/Http
4. packages/framework/database/migrations
5. packages/framework/routes
6. packages/storefront/src
7. packages/erp-bridge/src
8. config files, tests, and docs as supporting evidence only

When a route exists, inspect the controller and the resource serializer before describing the channel.

When a side effect exists, trace the observer, listener, event, service provider, or job that actually invokes it.

Writing Rules

Every page must:

• use plain business language first, then technical detail
• separate direct node ownership from parent-owned workflows and upstream influences
• separate user-editable fields from pass-through persisted fields
• call out fields that exist in the model but are hidden from admin or storefront UX
• identify exact import/export sheets, DTOs, or ERP payloads when they exist
• keep speculation out of the main sections and move uncertainty into Open Questions
• cite only real inspected repo-relative paths

Avoid:

• guessing from class names without opening the file
• treating every upstream workflow as a direct management channel
• equating API write validation with actual UI editability
• dumping raw code structure without explaining the business meaning

Required Page Structure

Every node page should use this structure:

# <Node Name>

::: info First-Pass Node Dossier
This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.
:::

## What It Is

## What Users Can Do With It

## Where It Is Managed

## Channel-Level Field Coverage

## Configuration And Data Model

## Relationships

## Rules And Downstream Effects

## Integrations And Automation

## Where It Appears To End Users

## Current Documentation Takeaways

## Open Questions

Allowed Structural Variants

If the node is mostly system-generated or read-only, replace ## Channel-Level Field Coverage with:

• ## Creation Model

This is appropriate for nodes like:

• audit records
• log records
• generated pivot helpers
• queue-driven technical artifacts

Section Expectations

What It Is

Must include:

• a plain-language definition
• the parent hierarchy
• the primary implementation paths

What Users Can Do With It

Must separate:

• direct capabilities
• indirect capabilities
• things users cannot do directly when that matters

Where It Is Managed

Prefer a channel table with:

• channel
• role
• notes

Use the following role vocabulary:

• Direct
• Direct read-only
• Parent-owned
• Indirect
• Indirect upstream input

Channel-Level Field Coverage

Only for directly managed nodes.

Must identify:

• fields exposed in each actual UI or API channel
• fields present in the model but not exposed in inspected UI
• storefront filtering or resource-level hiding when relevant

Creation Model

Only for system-generated or read-only nodes.

Must explain:

• what actually creates or mutates the node
• the triggering path
• whether creation is synchronous, queued, imported, or observer-driven

Configuration And Data Model

Must cover:

• key fields
• validation or defaults
• casts, traits, or lifecycle behaviors that change meaning
• whether the node is a primary record, helper record, or pivot-like artifact

Relationships

Must distinguish:

• direct model relationships
• practical ownership
• other nodes that depend on it

Rules And Downstream Effects

Must describe:

• delete or validity constraints
• calculations or eligibility rules
• automatic side effects
• the exact trigger path when known

Integrations And Automation

Must call out:

• ERP bridge behavior
• Excel import/export behavior
• feeds, jobs, or scheduled processes
• whether the node itself is synced versus only affected indirectly

Where It Appears To End Users

Must explain whether the node is:

• first-class in admin or storefront
• nested in another resource
• mostly invisible and only represented through other UI elements

Current Documentation Takeaways

End with three short, high-signal points for operators or implementers.

Open Questions

Use this section for:

• unresolved fields
• missing generated config
• legacy behavior
• routes or channels that exist but appear unused

Source Formatting

Within the markdown page, cite repo-relative paths in simple lists such as:

Sources:

- `packages/framework/src/Models/ProductType.php`
- `packages/framework/src/Observers/ProductTypeObserver.php`

Do not use absolute local filesystem paths in published docs content.

Authoring Workflow

1. Start from the node questionnaire.
2. Gather evidence from framework code first.
3. Confirm channel behavior in admin, storefront, import/export, and ERP bridge.
4. Draft the node page using the required structure.
5. Review for the known failure modes:
   • direct versus indirect channel confusion
   • editable versus pass-through field confusion
   • untraced side effects
   • guessed citations
6. Add the page to apps/docs/core/reference/.

Agent Prompt Standard

When delegating a node page to a sub-agent, require the agent to:

• follow this guideline exactly
• own one node page file
• use the questionnaire as research input, not as final output
• cite only inspected repo-relative paths
• avoid editing unrelated files