Context

Use this skill when the task is to build a registration flow orchestrator — a Smart component that:

1. Renders a full-page shell with a static Header, a central Stepper body, and a Footer with a Continue button.
2. Injects three MFE forms as Stepper steps: PartySearch, PartyRegistration, and DocumentPicture.
3. Accumulates each step's payload as the user progresses through the flow.
4. On final step completion, runs a sequential backend orchestration chain and only emits onResultData when the entire chain succeeds.

Do not use this skill to modify the Stepper core files, the MFE remote components, or any shared service layer. This skill only concerns the orchestrator component itself.

The Stepper core is already available at skillsTESSL/stepper/. The orchestrator must import from it — never copy or duplicate its internals.

Inputs (placeholders)

Architecture Rule: Component Folder Pattern

This skill follows the same Component Folder Pattern defined in the react-component skill. Flat .tsx files are strictly forbidden.

The orchestrator must be generated inside its own PascalCase subfolder containing exactly:

1. COMPONENT_NAME.tsx — the orchestrator implementation.
2. COMPONENT_NAME.types.ts — props, result, and accumulated payload interfaces.
3. COMPONENT_NAME.steps.tsx — the step definitions builder (returns the StepConfig[] array).
4. COMPONENT_NAME.service.ts — the backend orchestration chain (no React imports allowed here).
5. index.ts — barrel export.
6. SDD_COMPONENT_NAME.md — Software Design Document.

Step 1 — Define the Component Contract

Create the types file first. It must declare three interfaces:

Props interface — the public API of the orchestrator. It receives two props:

• initSettings: an object containing partyId (integer), orderId (integer), and configId (string or integer). These values are passed down to each MFE step as initialization context.
• onResultData: a callback that the orchestrator calls once — and only once — after the full backend orchestration chain completes successfully. It emits a result object that includes at minimum partyId, orderId, a status field set to 'completed', and a completedAt ISO timestamp.

Accumulated payload interface — an internal shape that holds the data collected from each step as the user progresses. It has one optional key per step (partySearch, partyRegistration, documentPicture), each typed as a generic data record.

Result interface — the shape emitted via onResultData. It must include partyId, orderId, status: 'completed', and completedAt.

Step 2 — Build the Step Definitions

Create the steps file. Its only export is a builder function that receives initSettings and an onStepResult callback, and returns the StepConfig[] array consumed by the Stepper.

Each of the three steps must:

• Have a URL-safe key in kebab-case — this becomes the URL segment in the Stepper router.
• Have a human-readable label.
• Render its MFE child using the project's MFE service layer. See the module-federation skill for the correct consumption pattern.
• Pass initSettings down to the MFE child as its initialization context.
• Wire the MFE child's onResultData callback to call onStepResult(stepKey, data) so the orchestrator can accumulate the payload.
• Provide a loading fallback and an error fallback.

The three steps in order are:

The MFE remote URLs, mfe names, and component expose keys must be resolved at implementation time from the project's module-federation.config.ts files. Do not hardcode placeholder strings — look them up before generating the file.

Step 3 — Build the Orchestration Service

Create the service file. It must contain a single exported async function that receives initSettings and the accumulated payload, and executes the following four operations in strict sequential order:

1. Register the generated order — uses orderId and the payload from the last step.
2. Associate the order and fully update the Party / Individual object — uses both partyId and orderId plus the accumulated payload.
3. Update contact media and addresses — uses partyId and the relevant payload slice.
4. Start the backend process flow — uses partyId and orderId.

Each operation must be its own private async function inside the service file so it can be replaced with a real API call independently. Until real endpoints exist, each function logs its arguments via console.info and resolves successfully.

Hard rules for the service file:

• Operations are sequential — use await in order, never Promise.all or Promise.allSettled.
• The file must not import React or any UI primitives.
• Errors must propagate naturally — do not catch and swallow them. The orchestrator component handles the error state.

Step 4 — Build the Orchestrator Component

Create the main component file. It is a Smart component that owns the orchestration state and delegates all UI rendering to the Stepper and all form logic to the MFE children.

Layout structure

The component renders a full-page flex column with three regions:

• Header — static top bar showing MODULE_TITLE on the left and SESSION_EMAIL / SESSION_ROLE stacked on the right. Tailwind className only, no inline styles.
• Main body — scrollable area that renders the Stepper component with the steps array and the navigation control object. If a submission error occurred, an error banner is shown above the Stepper.
• Footer — bottom bar with a single Continue / Finish button aligned to the right. The button is disabled while the orchestration chain is running and shows a loading label (Processing…) during that time.

State management

Navigation control

The orchestrator builds a StepperNavigationControl object and passes it to the Stepper via the navigation prop. This object has three members:

• canAdvance — returns true for all steps. Step-level validation is owned by each MFE child, not by the orchestrator.
• onNext — for non-last steps, returns true to let the Stepper advance. For the last step, calls handleFinish and returns false to prevent the Stepper from advancing past the final step.
• onFinish — calls handleFinish directly.

Finish handler

handleFinish is an async function that:

1. Sets isSubmitting to true and clears any previous error.
2. Calls the orchestration service function with initSettings and the current payloadRef.current.
3. On success: calls onResultData with the result object and sets isSubmitting to false.
4. On failure: sets submitError with the error message, sets isSubmitting to false, and does not call onResultData.

Note on the Continue button

The Stepper's internal StepNavigation already renders a Continue/Finish button via StepperNavigationBridge. The Footer button is the visual shell affordance. At implementation time, decide whether to use the Stepper's built-in navigation or the Footer button — both must never coexist as two independent triggers for the same action.

Step 5 — Barrel Export

The index.ts file must re-export the component by its PascalCase name and all public types from the types file. Consumers must always import from this barrel — never from internal files.

Stepper Core — Import Reference

The orchestrator imports from the Stepper directory already present at skillsTESSL/stepper/. Resolve the relative path from the component file's location to that directory before generating any import statement.

Do not import useStepper, useFlowSteps, or any internal Stepper hook directly in the orchestrator. Navigation is controlled exclusively through the StepperNavigationControl object passed as the navigation prop.

For the MFE service layer, follow the import rules defined in the module-federation skill.

Data Flow

Host
 └─ <COMPONENT_NAME initSettings onResultData />
       │
       ├─ buildSteps()  →  StepConfig[]
       │     └─ each step: MFE child → onResultData → onStepResult(key, data) → payloadRef
       │
       ├─ <Stepper steps navigation />
       │     └─ StepperNavigationBridge → navigation.onNext(index, isLastStep)
       │
       └─ Last step → handleFinish()
             │
             ├─ 1. registerOrder()
             ├─ 2. associateOrderAndUpdateParty()
             ├─ 3. updateContactsAndAddresses()
             ├─ 4. startBackendProcessFlow()
             │
             └─ ✅ All succeed → onResultData({ status: 'completed', ... })
                ❌ Any fails   → submitError shown, onResultData NOT called

Hard Rules

1. Never call onResultData before the full orchestration chain resolves. Partial success is not success.
2. Orchestration steps are sequential. Use await in order — never Promise.all or Promise.allSettled.
3. The orchestrator does not own step validation. Each MFE child is responsible for its own form validation. The orchestrator only gates advancement via canAdvance.
4. No inline style={{ }} — Tailwind className with CSS custom properties (var(--color-*)) only.
5. Typed props everywhere — no any. All callbacks and data shapes must have explicit TypeScript interfaces.
6. payloadRef is the single source of truth for accumulated step data. Do not duplicate it in useState.
7. The service file must not import React or any UI primitives.
8. Resolve all relative import paths dynamically — calculate the ../-based path from the component file's location before generating any import statement. Never hardcode absolute paths.
9. Follow the Component Folder Pattern — flat .tsx files are forbidden. See the react-component skill for the full specification.
10. mfe field in LoadComponent must match exactly the name field in the remote's module-federation.config.ts. Look it up before generating the step definitions.

SDD Minimum Sections (SDD_COMPONENT_NAME.md)

The Software Design Document must include at minimum:

1. Propósito y Alcance — what the orchestrator does and what it must NOT do.
2. Estrategia del Componente — Smart component; owns orchestration state; delegates UI to Stepper and form logic to MFE children.
3. Contrato de Props — typed interface table with initSettings fields and onResultData signature.
4. Flujo de Orquestación — numbered sequence of the four backend calls and the success/failure conditions.
5. Diagrama de Flujo de Datos — from host input → step accumulation → orchestration chain → onResultData.
6. Checklist de Conformidad — verifiable items before marking the component as complete.

Goal

A fully wired, type-safe registration flow orchestrator: a Smart container that drives three MFE forms through the Stepper system, accumulates their payloads, executes a sequential backend chain on completion, and emits a single onResultData event only on full success — ready for composition in any host application.