# Polyglot architecture

Distinguish the CLI, host, runtime, applications, and visual library before connecting frameworks.

<span id="cinco-responsabilidades-distintas"></span>

<span class="section-anchor" id="section-1"></span>

## Five distinct responsibilities

A **shell** is the page that brings applications together; a **microfrontend** is each application it can mount. The WU runtime connects the two. The CLI prepares the files and tools you use to develop them.

The table uses this portal's architecture as an example. You can choose another shell and other visual components: Astro and Lit are not requirements of the WU runtime.

| Piece | What it owns | What it delivers |
| --- | --- | --- |
| WU CLI | Workspace generation, development, and builds | Files, configuration, processes, and build output |
| Astro shell | Global URLs, navigation, and page composition | Documentation HTML and application slots |
| WU Framework | Registration, loading, and lifecycle; communication services | A common contract for independent applications |
| Microfrontend | A functional capability and its resources | A mount/unmount implementation and its own state |
| Lit library | Controls and visual contracts | Custom Elements usable from different frameworks |

The CLI runs during development and builds. The runtime runs in the browser. Astro can produce pages without framework JavaScript; interactive parts load through client modules.

<span id="la-url-pertenece-al-shell"></span>

<span class="section-anchor" id="section-2"></span>

## The URL belongs to the shell

A shell must decide which URL displays which content, how back/forward navigation works, and where focus moves. WU does not include a public router you can call as `wu.router` or `wu.routes`. Route metadata does not implement navigation by itself.

In this portal, Astro generates `/docs/.../`, `/labs/`, and `/sources/`. Navigation uses ordinary HTML links. Switching documents unloads the previous page and creates a new page context. There is no hidden SPA or promise of preserving state between documents.

A product with a persistent shell can use the History API and its own router. It must serialize transitions: unmount the previous app, mount the next one, update the title/focus, and handle failures. This is an additional host responsibility.

<span id="una-capacidad-por-microfrontend"></span>

<span class="section-anchor" id="section-3"></span>

## One capability per microfrontend

The laboratory contains two deliberately small capabilities:

- **Command builder**: turns the reader's configuration choices into a CLI recipe. React owns the state and adapts DOM events.
- **Runtime inspector**: displays and updates shared state, receives events, and lets you observe cleanup. Vue owns that logic.

Each button or card does not become a WU application. Buttons, forms, and panels live in Lit components; they do not need their own deployment or MFE lifecycle.

<span id="el-contrato-de-montaje"></span>

<span class="section-anchor" id="section-4"></span>

## The mounting contract

An explicit lifecycle makes it clear which resources the app creates and who destroys them:

```js
import { wu } from 'wu-framework';

wu.define('saludo', {
  mount(container) {
    const message = document.createElement('p');
    message.textContent = 'Aplicación montada por WU';
    container.append(message);
  },
  unmount(container) {
    container.replaceChildren();
  }
});
```

This defines the implementation. The host must initialize the application's registration/configuration and call `mount`; a definition does not mean it is already visible. See the framework manual for the exact manifest format and `wu.init()` usage.

<span id="estado-local-dom-y-comunicación-entre-apps"></span>

<span class="section-anchor" id="section-5"></span>

## Local state, DOM, and communication between apps

Use the mechanism closest to the relationship you want to express:

| Relationship | Mechanism |
| --- | --- |
| Internal React or Vue state | Local framework state |
| Data from an app to a Lit control | Custom Element properties |
| Intent from a control to its app | Typed DOM event |
| A fact relevant to other apps | WU event bus |
| Observable shared data | WU store |
| A versioned service between providers/consumers | WU contracts |

Do not publish mutable store objects as a visual API. Pass data and events, and cancel subscriptions when the app unmounts.

<span id="aislamiento-y-confianza"></span>

<span class="section-anchor" id="section-6"></span>

## Isolation and trust

The portal uses `sandbox: 'module'`. Modules run in the same JavaScript context; this is not a boundary for hostile code. Lit components use Shadow DOM for their styles, but Shadow DOM does not prevent access to the global context.

This project's applications are trusted local code. Facade capabilities limit the operations performed through it; they do not automatically make an arbitrary module safe. The `strict`, `eval`, `proxy`, and `none` modes have different contracts and are documented with their limits in the manual.

<span id="una-interfaz-coherente"></span>

<span class="section-anchor" id="section-7"></span>

## A consistent interface

The portal's visual system uses a black background, bone-colored text, red signals, lime status indicators, and thin dividers. Reading pages retain sufficiently large text, visible focus, and scrollable tables.

Static document composition belongs to Astro. Interactive controls are implemented in Lit. React and Vue do not introduce a second family of buttons and forms.

<span id="referencias"></span>

<span class="section-anchor" id="section-8"></span>

## References

- Code: `wu-framework/src/core/wu-core.js`, `wu-store.js`, `wu-event-bus.js`, `wu-contracts.js`, and `src/index.js`.
- [Astro: client-side scripts and Custom Elements](https://v5.docs.astro.build/en/guides/client-side-scripts/).
- [Lit: lifecycle and resource cleanup](https://lit.dev/docs/components/lifecycle/).