GenUI Boilerplate & Strangler Fig Migration — Frontend (P7)

This is the conclusion of the series. The best architectural theories remain merely on paper if we lack a clear execution path.

In this part, we will define a Reference Repository structure and a Migration Strategy to bring Generative UI into actively running systems.

7.1. Boilerplate Directory Structure (Astro + Svelte)

To maximize the power of the Framework-Agnostic architecture, we choose Astro as the Orchestrator. Svelte is chosen as the UI framework because it compiles to extremely lightweight Vanilla JS, without the Virtual DOM overhead like React—perfect for highly dynamic UI Components.

Here is the recommended directory structure:

my-genui-app/
├── src/
│   ├── components/
│   │   ├── static/           # Normal static components (Header, Footer)
│   │   ├── registry/         # 🟢 ALL COMPONENTS CALLABLE BY AI LIVE HERE
│   │   │   ├── flight/FlightWidget.svelte
│   │   │   ├── ecom/OrderCancelForm.svelte
│   │   │   └── _registry.ts  # Map file converting strings to Components
│   │   └── DynamicRenderer.svelte # The core component rendering based on JSON
│   ├── lib/
│   │   ├── agent-client.ts   # Manages WebSocket connections & State Recovery
│   │   ├── schema-validators.ts # Zod schemas protecting Component Props
│   │   └── telemetry.ts      # 📊 Logs/Metrics collection for GenUI
│   ├── pages/
│   │   └── index.astro       # Where the entire app is assembled
│   └── stores/
│       └── aiState.ts        # Global State management (e.g., using Nano Stores)

The Importance of Telemetry: In a GenUI system, the telemetry.ts file plays a vital role. You need to fire events to the Analytics Server to answer questions like: How many users clicked Reject on an AI-generated Form? What is the rate of the system being forced to Fallback to static UI due to WebSocket drops? This gives Product Managers the data needed to improve UX.

The Golden Rule: Any developer wanting to add a new AI feature simply takes 2 steps:

1. Create a .svelte Component inside the registry/ folder.
2. Define a Zod Schema in schema-validators.ts. Absolutely do not touch the core logic of the WebSocket system.

7.2. A2UI Contract Schema (Backend ↔ Frontend Communication Standard)

This is a critical agreement that must be finalized between the Backend Lead and the Frontend Lead before any developer starts coding. Without this document, the Backend and Frontend will interpret JSON differently, spawning Non-reproducible bugs.

// Standard structure of an A2UI Message (Agent-to-User Interface)
type A2UIMessage = {
  tool: string;         // (Required) Component name in Registry. Ex: "RenderOrderCancel"
  args: Record<string, unknown>; // (Required) JSON Payload matching Zod Schema
  session_id: string;   // (Required) So Frontend knows which session to assign State to
  action_type: "render" | "dismiss" | "update"; // (Required) Distinguishes:
                        //   "render" = Spawn new Component on screen
                        //   "update" = Update Props of an existing Component
                        //   "dismiss" = Remove Component from screen
  trace_id?: string;    // (Optional) For debugging and Telemetry integration
};

Crucial Note: session_id is generated at the API Gateway layer (e.g., Cloudflare Worker) when the user first connects. It is passed down to the Frontend via the WebSocket handshake, and Backend Agents use it to namespace all messages. This resolves Race Conditions when multiple Agents run in parallel.

7.3. Architecture Decision Records (ADR)

The reasons why we chose these technologies must be documented and protected to prevent new developers from arbitrarily changing the stack, causing Hydration mismatches or bloated bundle sizes.

7.4. Migration Strategy: Strangler Fig Pattern

There is a massive trap that many CTOs/Tech Leads fall into: Deciding to tear down the legacy app and “rewrite from scratch” with AI. The failure rate of Rewrite projects often exceeds 70%.

Instead, use the Strangler Fig Pattern — a strategy that slowly strangles the old application with the new one.

Phased Rollout

Suppose you have an old E-commerce system (like Shopee) or an internal ERP.

1. Phase 1: Coexist: You spin up an entirely independent new GenUI service (using the Astro Boilerplate above).
2. Phase 2: API Gateway Routing: Place an API Gateway/Proxy (like Nginx or Cloudflare) in front. All normal traffic still routes to the legacy App.
3. Phase 3: Strangling: Pick a small, isolated but problematic feature, e.g., the “Return/Refund Process”. Redirect users clicking the “Refund” button to the new Astro page. Here, users interact with the GenUI Component.
4. Phase 4: Eliminate: Once the “Refund” feature using GenUI is running stably, delete the old code in the Legacy App.

Repeat this process until the entire Legacy App is completely replaced by GenUI Modules.

Sprint Rollout Table (Weekly Execution Plan)

The list below helps Team Leads instantly answer the question: “What are we doing this week?”. A standard Sprint is 1-2 weeks.

7.5. Series Conclusion

We have come a long way from recognizing the weaknesses of Chatbots (Part 1), designing an independent Framework-Agnostic architecture (Part 2), building a secure Component Registry (Part 3 & Part 4), optimizing UX with Human-in-the-loop (Part 5), and finally Testing & Caching (Part 6).

Generative UI is not just a technological hype. It is the next evolutionary form of Frontend Architecture in the AI era. By bridging an MCP Server to Astro’s Component Registry, you have granted your Agentic system the ability to output visual interfaces, while maintaining absolute control over security and user experience.

Thank you for following along with this series!