Frontend / Mystique UI Scenarios
Use Case
Author:
Fluent Commerce
Changed on:
31 Mar 2026
Problem
New UI Page Generation Problems:- No clear starting point for new pages: Knowing which components to use, how to nest them, and how to structure the accompanying data query requires deep framework knowledge that newer developers are still building up.
- Manual manifest authoring is slow and error-prone: Writing manifest JSON by hand is precise work, and small mistakes in component aliases or composition structure cause pages to break in ways that can be hard to trace back to the source.
- Inconsistent page structure across the application: Without a guided build process, developers make independent structural decisions that lead to an application that becomes harder to maintain and extend over time.
- No automatic quality check after building: Pages built without a validation step often only reveal structural problems after deployment, when they are already visible to users.
- Structural issues only discovered after deployment: Without a validation step, broken component references, missing required props, and schema violations reach production before anyone is aware they exist.
- GraphQL errors embedded silently in manifests: Queries that reference incorrect fields or types cause pages to fail loading data, often without a clear or descriptive error message to help identify the source.
- No way to prioritise what actually needs fixing: When a list of errors is returned with no severity context, it is difficult for any developer to judge which issues will break the page entirely and which can safely wait.
- Cross-manifest dependencies breaking without warning: When one manifest references a component or route defined in another, changes on either side can silently sever the connection in a way that manual review rarely catches in time.
- No structured way to decide when custom development is the right call: Without a clear evaluation step, less experienced developers may jump to custom work too early, while experienced developers may spend time trying to make out-of-the-box components do things they were never designed for.
- Setting up a custom component project from scratch is time-consuming: Configuring a build system, TypeScript, component boilerplate, and test infrastructure manually produces inconsistent results and takes time away from the actual component logic.
- Custom components built without tests or documentation: Components developed under delivery pressure rarely include Storybook stories or unit tests, making them fragile and difficult for other team members to work with confidently.
- Manifest not updated to load the custom bundle: A correctly built custom component will not appear in the application if the manifest is not updated to reference it, and this wiring step is easy to overlook in a fast-moving project.
- No consolidated view of what an existing manifest contains: Manifests built up across multiple developers and releases are difficult to reason about without a structured inventory of what components and routes actually exist.
- Complexity accumulating unnoticed over time: Certain pages or sections become disproportionately complex as a manifest grows, increasing the risk of breakage when changes are made, but this is invisible without a scored analysis to surface it.
- Unused components adding noise and confusion: Components that were added but are no longer referenced anywhere remain in the manifest silently, creating confusion for developers trying to understand the application and adding unnecessary maintenance overhead.
- Incomplete internationalisation going undetected: Missing translation coverage is rarely caught during development and typically surfaces only when the application is used in a non-default language by a real user.
- Backend and frontend developed without a shared plan: When workflow logic and UI pages are planned separately, misalignments in data structure and event handling create integration problems that are expensive to resolve close to a delivery deadline.
- Frontend work starting before the backend is stable: Building UI pages against workflow rules and data structures that are still changing leads to rework that could have been avoided with a sequenced approach.
- No automated verification across both layers: End-to-end tests that exercise backend logic and frontend rendering together are rarely in place, leaving the integration between the two unverified until a real user encounters a problem.
- Scope gaps between backend and frontend deliverables: Without a unified plan, requirements can be addressed on one side but inadvertently missed on the other, producing a feature that is technically deployed but incomplete from the user's perspective.
- No automated check after a manifest is deployed: Confirming that a deployed manifest renders correctly in a real browser is typically done manually, inconsistently, and often skipped entirely under time pressure regardless of experience level.
- Console errors going unnoticed after deployment: JavaScript and GraphQL errors that occur on page load are not visible in the rendered UI but can indicate serious problems, and they are easy to miss during a manual walkthrough.
- No visual record of the post-deployment state: Without a screenshot taken at the point of verification, there is nothing to compare against if the page looks different later and no shared evidence to reference when reporting issues to the team.
- Repetitive manual steps slowing down verification: Logging in, navigating to the correct route, and methodically checking multiple aspects of a page across different environments is time-consuming and prone to human error.
- Reaching a specific context manually is slow and inconsistent: Without deep-linking, getting the application into the right location or retailer context requires navigating through switchers every time, which is repetitive and introduces the risk of inadvertently testing in the wrong context.
- Context resolution behaviour is not intuitive: The priority order in which the application resolves context from URL parameters, local storage, and user defaults is not obvious, and misunderstanding it leads to confusing behaviour that is difficult to diagnose without knowing the underlying mechanism.
- URL parameters placed incorrectly cause silent failures: Positioning a context parameter before the hash path rather than after it causes the deep-link to appear to work while silently resolving to an unintended context, which is a subtle mistake that affects developers at all experience levels.
- Context not persisting reliably across page navigation: Without understanding how context is stored and carried between routes, developers encounter inconsistent application behaviour during testing that is difficult to reproduce or explain to others.
Example
New UI Page: "Build an order detail page showing order summary, customer info, items, and fulfilments"Pre-Deployment Manifest Validation: "Validate the admin manifest before I deploy it"Custom UI Component Scaffolding: "I need a drag-and-drop pick list interface for warehouse staff"Analyzing What's Built in an App: "What components are used in the admin manifest? Any complexity issues?"Full-Stack Feature Delivery: "Build order tracking with a customer-facing status page"Live Browser-Based Manifest Verification: "Test the OMS orders page in the browser"Context-Specific Deep-Link Testing: "Test the Store app waves page for location LOC_SYD_001"
Solution Overview
New UI Pages:- Building a new UI page starts with a plain-language description of what the page needs to show. The tool evaluates that description against the available out-of-the-box components and presents a plan covering the route structure, component hierarchy, data query, and composition pattern before any output is generated. This review step is valuable for developers at both ends of the experience spectrum: newer developers get a clear picture of how the framework thinks about the problem, while experienced developers can catch anything that needs adjusting before committing to the build.
- Once the plan is approved, the manifest JSON definition is generated automatically, with components assembled in the correct structure. A validation step runs immediately after to confirm the output is sound before it is used.
- The result is a complete, deployment-ready page definition produced without manual JSON authoring and without needing to know from memory which components to use or how to arrange them.
- Validating a manifest before deployment starts with a single instruction pointing the tool at the manifest to be checked. The tool runs approximately fifty validation rules across six distinct phases, examining schema compliance, component alias correctness, GraphQL query structure, template string formatting, required prop completeness, and references between manifests.
- Every issue is assigned a severity level, from critical findings that would prevent the page from working at all, through to lower-priority observations that are worth noting but not blocking. This tiered view helps developers at any experience level make a confident, informed decision about whether the manifest is ready to deploy.
- The output is a report with a specific, actionable fix suggestion for every issue found, so developers are not left investigating problems from scratch. The path from a flagged issue to a resolved one is as direct as possible.
- When a UI requirement cannot be met by available out-of-the-box components, the process begins with a structured evaluation of whether custom development is genuinely needed. This decision point is explicit and consistent, giving developers at any level a shared framework for making the call rather than relying on individual judgment or assumptions about what the framework can and cannot handle.
- Once custom development is confirmed as the right path, a complete SDK project is generated. This covers build configuration, TypeScript setup, component boilerplate, Storybook stories for visual development and review, and Jest tests for unit coverage. The developer receives a ready-to-build project structure rather than having to assemble it themselves.
- At the same time, the manifest is updated to reference the custom component bundle, ensuring the application is wired to load the new component correctly from the moment it is deployed. No separate manual step is needed to connect the component project to the manifest.
- Analysing an existing application manifest starts with a single request that triggers a seven-dimension assessment across the full manifest. The tool examines component usage and frequency, route structure and coverage, a weighted complexity score for every section of the manifest, data query patterns, internationalisation coverage, and the overall structural patterns applied across the application. Visual diagrams are produced to make the relationships and structure easier to interpret, regardless of how familiar a developer is with the codebase.
- The output gives developers at both experience levels something useful. Experienced developers can identify optimisation opportunities, complexity hotspots, and areas of technical debt. Newer developers can use the analysis to build an accurate mental model of how the application is structured before making changes, reducing the risk of unintended consequences.
- Running this analysis before significant manifest work begins is the most effective use: it ensures that decisions are grounded in an objective view of the current implementation rather than assumptions or partial knowledge.
- Delivering a feature that spans backend logic and a user-facing interface begins with a single unified plan that addresses both layers together. Rather than treating workflow rules and UI pages as separate workstreams owned by different people with different plans, the approach sequences them explicitly, with backend work completed first so the frontend has stable data and events to build against.
- With the plan approved, the backend rules, workflows, and configuration are built first. Once that foundation is in place, the frontend work begins, generating the manifest pages and components that surface the backend behaviour to users. The manifest is validated before deployment to catch structural issues before they reach the live environment.
- With both layers deployed, a cross-cutting end-to-end test confirms that the full feature works as intended, from the backend processing events correctly through to the frontend reflecting the right state at each stage. This is a useful pattern for developers of any experience level, since it makes the sequencing and dependencies between backend and frontend explicit and removes the ambiguity about what needs to be in place before the next step can begin.
- Verifying a deployed manifest in the browser starts with specifying the page or route to be tested. The tool navigates to the application, handles the login process, and reaches the correct route without any manual steps from the developer.
- Once on the page, the tool checks that it loaded without errors, that the expected components rendered with real data, that navigation and pagination controls are present, and that interactive elements such as search and filters are functional. The browser console is checked at the same time for JavaScript or GraphQL errors that would not be visible in the rendered page but could indicate underlying issues.
- A screenshot is captured as a visual record at the point of verification. The result is a structured pass or fail report with each check clearly listed and any issues rated by severity, giving developers at any level an immediate, unambiguous view of what is working and what needs attention.
- Testing the application in a specific location or retailer context begins with the tool constructing a correctly formatted deep-link URL that includes the target context as a parameter. The positioning of that parameter is handled precisely, avoiding the common mistake of placing it on the wrong side of the hash path, which would cause the context selection to be silently ignored.
- When the application loads from this URL, it reads the context parameter at the highest priority level, overriding anything stored in local storage or resolved from the user's default access. This guarantees the session starts in the intended context from the first page load, with no manual switcher interaction required.
- As the developer navigates through the application, the selected context is persisted automatically so it does not reset between pages. The same approach applies to both the Store and OMS applications, with the correct parameter and storage key used for each. This gives developers at any experience level a reliable, repeatable way to test context-specific behaviour without having to understand the full resolution mechanism from first principles.
