# hector-rubio-tabares/dem-astro architecture

> Architecture diagram of the GitHub repository hector-rubio-tabares/dem-astro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hector-rubio-tabares/dem-astro
- Repository: https://github.com/hector-rubio-tabares/dem-astro

## Overview

1. This is a pnpm monorepo for a microfrontend demo, centered on three apps: an Astro shell, a React microfrontend, and an Angular microfrontend. The repo also contains a shared TypeScript package for cross-app primitives, plus a small script for syncing built remote assets into the shell.

2. The architectural boundary is clear: `apps/portfolio-shell-astro` is the host/orchestrator, while `apps/portfolio-react-mf` and `apps/portfolio-angular-mf` are independently built remotes. The shell is the only user entrypoint; the remotes are loaded into it at runtime rather than navigated to directly in the intended flow.

3. The shell is the control plane. Its `src/pages/*.astro` pages define the shell routes, and `src/scripts/demo-hot.ts` appears to be the main runtime orchestrator for loading and coordinating remotes. Supporting scripts include `mf-loader.ts` for remote loading, `mf-runtime.ts` for runtime helpers, and `message-validator.ts` / `event-bus.ts` for communication and safety.

4. The React microfrontend is a Vite-based app with a dedicated federation entrypoint at `src/mf-entry.tsx`. That entrypoint suggests it can be exposed both as a normal standalone app and as a remote module. `src/ErrorBoundary.tsx` indicates local error isolation inside the MF boundary.

5. The Angular microfrontend is a standalone Angular app configured through `angular.json`, `federation.config.js`, and the standard `src/main.ts` / `src/app/*` structure. Its presence alongside a federation config indicates it is also prepared to be consumed as a remote, even if the federation support is more experimental than React’s.

6. The shared package `packages/mf-shared` is the main cross-cutting dependency layer. It contains `event-bus.ts`, `message-validator.ts`, `context.ts`, `strategies.ts`, `types.ts`, and an `index.ts` barrel export. This is the repo’s type-safe contract layer for message shapes, event routing, and shared runtime behavior across shell and remotes.

7. Communication is the second major subsystem after loading. The README and file names point to two channels: same-tab messaging through an in-memory EventBus, and multi-tab messaging through browser-native BroadcastChannel. The shell owns the coordination logic, while the remotes publish events into the shared communication layer.

8. Security and resilience are built into the architecture rather than left to the UI layer. Message validation lives in dedicated validator modules, and the repo includes an `error-handler.ts` in Angular plus `ErrorBoundary.tsx` in React to prevent one remote from taking down the whole shell. The README also emphasizes origin validation and sanitization, which implies the loader/runtime boundary is treated as an attack surface.

9. Build and deploy flow is split between source apps and static remote artifacts. `apps/portfolio-shell-astro/public/mf/...` contains built JavaScript/CSS assets for the remotes, which means the shell can serve remote bundles locally or in a packaged form. The root `scripts/sync-remotes.mjs` likely copies built remote outputs into that public directory so the shell can load them consistently.

10. The runtime topology in dev is three local servers: Astro on one port for the host, React on another for its MF build, and Angular on a third. The shell then dynamically loads the remote bundles from those origins or from synced static assets, making the browser the integration point where the independent apps are composed.

11. Testing is concentrated around the shared runtime and messaging layer rather than UI snapshots. The shell has test files for `event-bus` and `message-validator`, which suggests the highest-value correctness boundary is the cross-app protocol, not the individual visual components.

12. For an architecture diagram, the important boxes are: monorepo/workspace at the top; shell host in the center; React and Angular remotes as separate runtime producers; `mf-shared` as the contract library; and browser-native channels (EventBus and BroadcastChannel) as the communication paths. The most important arrows are shell-to-remote loading, remote-to-shared-contract imports, and bidirectional event flow between all three apps.

Main entry points: [`apps/portfolio-shell-astro/src/scripts/demo-hot.ts`](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/demo-hot.ts) (Demo runtime), [`apps/portfolio-react-mf`](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-react-mf) (React MF), [`apps/portfolio-angular-mf`](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-angular-mf) (Angular MF), [`packages/mf-shared`](https://github.com/hector-rubio-tabares/dem-astro/tree/main/packages/mf-shared) (mf-shared)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace"]
  node_repo["Monorepo<br/>pnpm workspace"]
end

subgraph group_apps["Apps"]
  node_shell["Astro shell<br/>host/orchestrator"]
  node_shell_pages["Shell pages<br/>astro routes"]
  node_shell_runtime{{"Demo runtime<br/>orchestration<br/>[demo-hot.ts]"}}
  node_mf_loader["MF loader<br/>runtime loader<br/>[mf-loader.ts]"]
  node_mf_runtime["MF runtime<br/>runtime helpers<br/>[mf-runtime.ts]"]
  node_shell_bus(("Shell bus<br/>communication<br/>[event-bus.test.ts]"))
  node_remote_assets[("Synced remotes<br/>static bundles")]
  node_react_mf["React MF<br/>remote app"]
  node_react_entry{{"MF entry<br/>federation entrypoint<br/>[mf-entry.tsx]"}}
  node_react_boundary(("React boundary<br/>error isolation<br/>[ErrorBoundary.tsx]"))
  node_angular_mf["Angular MF<br/>remote app"]
  node_angular_app["Angular app<br/>app shell"]
  node_angular_error(("Error handler<br/>resilience<br/>[error-handler.ts]"))
end

subgraph group_shared["Shared"]
  node_shared_pkg[("mf-shared<br/>shared package")]
  node_shared_types["Contracts<br/>types and context<br/>[types.ts]"]
  node_shared_comm{{"Bus + validation<br/>message layer<br/>[event-bus.ts]"}}
end

subgraph group_scripts["Scripts"]
  node_sync_remotes["Sync remotes<br/>build script<br/>[sync-remotes.mjs]"]
end

node_repo -->|"contains"| node_shell
node_repo -->|"contains"| node_react_mf
node_repo -->|"contains"| node_angular_mf
node_repo -->|"contains"| node_shared_pkg
node_repo -->|"contains"| node_sync_remotes
node_shell -->|"routes"| node_shell_pages
node_shell_pages -->|"boots"| node_shell_runtime
node_shell_runtime -->|"loads"| node_mf_loader
node_shell_runtime -->|"uses"| node_mf_runtime
node_mf_loader -->|"serves"| node_remote_assets
node_sync_remotes -->|"copies"| node_remote_assets
node_shell_runtime -->|"mounts"| node_react_mf
node_shell_runtime -->|"mounts"| node_angular_mf
node_react_mf -->|"exposes"| node_react_entry
node_react_mf -->|"isolates"| node_react_boundary
node_angular_mf -->|"bootstraps"| node_angular_app
node_angular_mf -->|"handles"| node_angular_error
node_shell -->|"imports"| node_shared_pkg
node_react_mf -->|"imports"| node_shared_pkg
node_angular_mf -->|"imports"| node_shared_pkg
node_shared_pkg -->|"defines"| node_shared_types
node_shared_pkg -->|"implements"| node_shared_comm
node_shell_runtime -->|"coordinates"| node_shared_comm
node_react_mf -->|"publishes"| node_shared_comm
node_angular_mf -->|"publishes"| node_shared_comm

click node_shell "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro"
click node_shell_pages "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro/src/pages"
click node_shell_runtime "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/demo-hot.ts"
click node_mf_loader "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/mf-loader.ts"
click node_mf_runtime "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/mf-runtime.ts"
click node_shell_bus "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/event-bus.test.ts"
click node_remote_assets "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro/public/mf"
click node_react_mf "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-react-mf"
click node_react_entry "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-react-mf/src/mf-entry.tsx"
click node_react_boundary "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-react-mf/src/ErrorBoundary.tsx"
click node_angular_mf "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-angular-mf"
click node_angular_app "https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-angular-mf/src/app"
click node_angular_error "https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-angular-mf/src/app/error-handler.ts"
click node_shared_pkg "https://github.com/hector-rubio-tabares/dem-astro/tree/main/packages/mf-shared"
click node_shared_types "https://github.com/hector-rubio-tabares/dem-astro/blob/main/packages/mf-shared/src/types.ts"
click node_shared_comm "https://github.com/hector-rubio-tabares/dem-astro/blob/main/packages/mf-shared/src/event-bus.ts"
click node_sync_remotes "https://github.com/hector-rubio-tabares/dem-astro/blob/main/scripts/sync-remotes.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_repo toneBlue
class node_shell,node_shell_pages,node_shell_runtime,node_mf_loader,node_mf_runtime,node_shell_bus,node_remote_assets,node_react_mf,node_react_entry,node_react_boundary,node_angular_mf,node_angular_app,node_angular_error toneAmber
class node_shared_pkg,node_shared_types,node_shared_comm toneMint
class node_sync_remotes toneRose
```

## Components

### Workspace

pnpm monorepo boundary

- **Monorepo**: pnpm workspace · Root workspace and dependency graph

### Apps

Host and microfrontends

- [Astro shell](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro): host/orchestrator · Single user entrypoint and runtime control plane · `apps/portfolio-shell-astro`
- [Shell pages](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro/src/pages): astro routes · Route-level pages that mount the microfrontend demo · `apps/portfolio-shell-astro/src/pages`
- [Demo runtime](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/demo-hot.ts): orchestration · Coordinates remote loading and demo flow · `apps/portfolio-shell-astro/src/scripts/demo-hot.ts`
- [MF loader](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/mf-loader.ts): runtime loader · Loads remote bundles into the shell · `apps/portfolio-shell-astro/src/scripts/mf-loader.ts`
- [MF runtime](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/mf-runtime.ts): runtime helpers · Shared shell-side helpers for remote composition · `apps/portfolio-shell-astro/src/scripts/mf-runtime.ts`
- [Shell bus](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-shell-astro/src/scripts/event-bus.test.ts): communication · Message validation and in-memory event routing · `apps/portfolio-shell-astro/src/scripts/event-bus.test.ts`
- [Synced remotes](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-shell-astro/public/mf): static bundles · Built remote artifacts served by the shell · `apps/portfolio-shell-astro/public/mf`
- [React MF](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-react-mf): remote app · Vite-based remote microfrontend · `apps/portfolio-react-mf`
- [MF entry](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-react-mf/src/mf-entry.tsx): federation entrypoint · Remote exposure entry used by the shell · `apps/portfolio-react-mf/src/mf-entry.tsx`
- [React boundary](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-react-mf/src/ErrorBoundary.tsx): error isolation · Local error boundary for remote resilience · `apps/portfolio-react-mf/src/ErrorBoundary.tsx`
- [Angular MF](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-angular-mf): remote app · Standalone Angular microfrontend prepared for federation · `apps/portfolio-angular-mf`
- [Angular app](https://github.com/hector-rubio-tabares/dem-astro/tree/main/apps/portfolio-angular-mf/src/app): app shell · Angular app bootstrap and component layer · `apps/portfolio-angular-mf/src/app`
- [Error handler](https://github.com/hector-rubio-tabares/dem-astro/blob/main/apps/portfolio-angular-mf/src/app/error-handler.ts): resilience · Angular-side error handling boundary · `apps/portfolio-angular-mf/src/app/error-handler.ts`

### Shared

Cross-app contract layer

- [mf-shared](https://github.com/hector-rubio-tabares/dem-astro/tree/main/packages/mf-shared): shared package · Cross-app contract and runtime primitives · `packages/mf-shared`
- [Contracts](https://github.com/hector-rubio-tabares/dem-astro/blob/main/packages/mf-shared/src/types.ts): types and context · Message shapes, context, and strategy definitions · `packages/mf-shared/src/types.ts`
- [Bus + validation](https://github.com/hector-rubio-tabares/dem-astro/blob/main/packages/mf-shared/src/event-bus.ts): message layer · Event bus and message validation shared across apps · `packages/mf-shared/src/event-bus.ts`

### Scripts

Repo automation

- [Sync remotes](https://github.com/hector-rubio-tabares/dem-astro/blob/main/scripts/sync-remotes.mjs): build script · Copies built remote outputs into the shell · `scripts/sync-remotes.mjs`

## Connections

- Monorepo → Astro shell: contains · Workspace includes the Astro host
- Monorepo → React MF: contains · Workspace includes the React remote
- Monorepo → Angular MF: contains · Workspace includes the Angular remote
- Monorepo → mf-shared: contains · Workspace includes the shared package
- Monorepo → Sync remotes: contains · Workspace includes remote sync automation
- Astro shell → Shell pages: routes · Shell pages define entry routes
- Shell pages → Demo runtime: boots · Pages initialize the demo runtime
- Demo runtime → MF loader: loads · Runtime delegates remote loading
- Demo runtime → MF runtime: uses · Runtime uses helper utilities
- MF loader → Synced remotes: serves · Loads synced remote bundles from shell public assets
- Sync remotes → Synced remotes: copies · Build script syncs remote outputs into the shell
- Demo runtime → React MF: mounts · Shell composes the React remote at runtime
- Demo runtime → Angular MF: mounts · Shell composes the Angular remote at runtime
- React MF → MF entry: exposes · Federation entrypoint for remote consumption
- React MF → React boundary: isolates · React remote wraps local failures
- Angular MF → Angular app: bootstraps · Angular app structure provides the remote UI
- Angular MF → Error handler: handles · Angular remote adds local error handling
- Astro shell → mf-shared: imports · Host consumes shared contracts and helpers
- React MF → mf-shared: imports · React remote depends on shared primitives
- Angular MF → mf-shared: imports · Angular remote depends on shared primitives
- mf-shared → Contracts: defines · Shared package publishes message and context types
- mf-shared → Bus + validation: implements · Shared package provides bus and validation logic
- Demo runtime → Bus + validation: coordinates · Shell centralizes event routing and validation
- React MF → Bus + validation: publishes · React remote emits events into the shared layer
- Angular MF → Bus + validation: publishes · Angular remote emits events into the shared layer
