ENES

Architecture Overview

Micro Frontends Platform — React + TypeScript, Module Federation v2, Cloudflare Workers

Table of Contents

System Architecture Diagram

System Architecture Diagram — Browser, Shell App, MFEs, Cloudflare Edge BROWSER Shell App (Host) MFE A MFE B MFE C MFE D MFE E Design System Remote (shared UI components) ◄ CustomEvents bus (inter-MFE communication) ► HTTP / WebSocket Module Federation Runtime (CDN) CLOUDFLARE EDGE API Gateway Worker • CORS • Rate limiting • JWT verification • Request routing BFF Workers BFF A BFF B BFF C BFF D CDN / R2 MFE bundles Version Config KV + D1 Durable Objects Real-time sessions service bindings WebSocket

Technology Stack

LayerTechnologyVersionPurpose
Frontend FrameworkReact + TypeScript^19.2.4 / ^5.9.3UI rendering, CSR-only
MFE CompositionModule Federation v2 (@module-federation/enhanced)^2.0.1Runtime remote loading
BundlerRsbuild (@rsbuild/core) / Rspack^1.7.3Fast builds with native MF v2 support
Design SystemCustom (npm + MF remote) + Storybook^10.2.10 (Storybook)Shared UI component library
StylingCSS Modules / Tailwind CSS—Scoped styles per MFE
Routingreact-router (consolidated from react-router-dom)^7.13.1Client-side routing
State Managementzustand^5.0.11Lightweight stores per MFE
Validationzod^4.3.6Runtime schema validation
JWT Handlingjose^6.1.3Token signing/verification in Workers
Package Managerpnpm10.30.3Content-addressable store, strict deps
Monorepo ToolTurborepo (turbo)^2.8.10Task orchestration, remote caching
LintingESLint (flat config only)^10.0.2Static analysis
TestingVitest^4.0.18Unit / integration tests
RuntimeNode.js22 (Maintenance LTS), 24 (Active LTS) — Node 20 EOL April 2026Build & CI runtime
Edge RuntimeCloudflare Workers (Wrangler v4)—API gateway, BFFs, Workers Static Assets (Pages deprecated Apr 2025)
Object StorageCloudflare R2—Versioned MFE bundle storage
KV StoreCloudflare KV—Version config (fast edge reads)
SQL DatabaseCloudflare D1 (GA since April 2024)—Audit trail, version history
Real-timeDurable Objects (Hibernatable WebSockets)—WebSocket coordination; Workers CPU time configurable up to 5 min
Compatibility DateCloudflare Workers2026-02-25Baseline compatibility date for all Workers
AuthenticationWorkOS AuthKit—OAuth, enterprise SSO, RBAC
CI/CDGitHub Actions—Build, test, deploy pipelines
VersioningChangesets—Independent semantic versioning
Cross-repo UpdatesRenovate—Automated dependency updates
Local Dev (cross-repo)yalc + Verdaccio—Local package linking and registry

Data Flow

Page Load Sequence

Page Load Sequence — Steps 1 through 7 1User navigates to app.example.com 2Cloudflare CDN serves Shell App (index.html + shell bundle) 3Shell App bootstrap 3a. Fetch version config from KV → { "mfe-a": "…/mf-manifest.json" } 3b. Initialize Module Federation runtime → registerRemotes([…]) 3c. WorkOS AuthKit checks session / redirects to login 4User navigates to route owned by MFE A 5Shell App calls loadRemote("mfe_a/App") 5a. MF runtime fetches mf-manifest.json from CDN/R2 5b. Downloads MFE A chunks (shared deps already loaded → skipped) 5c. MFE A component mounts in Shell's <React.Suspense> boundary 6MFE A calls its BFF Worker via API Gateway 6a. API Gateway validates JWT (from HttpOnly cookie) 6b. Routes request to BFF-A Worker (service binding) 6c. BFF-A processes request, returns data 7MFE A renders with data ✓

API Request Flow

API Request Flow — Browser through API Gateway and BFF Worker to backend services Browser API Gateway Worker JWT · CORS · Rate limit · Routing BFF Worker Domain logic · Transform · Cache External / D1 KV / R2 Service Bindings (RPC)

Real-time Flow

Real-time Flow — Browser through Durable Object to Hibernatable WebSocket Browser Durable Object (via Worker) State coordination · Broadcast · Alarm cleanup Hibernatable WebSocket WS stays open during hibernation ($0)

Repository Map

Repository Map — Monorepo hub with polyrepo and infrastructure spokes MONOREPO — platform-core 📦 design-system 📦 shared-types 📦 shared-utils 📦 eslint-config 📦 tsconfig 📦 prettier-config 📦 event-contracts turbo.json pnpm-workspace.yaml .changeset/ Changesets → npm publish → Renovate updates POLYREPOS shell-app (Host) mfe-dashboard (Alpha) mfe-settings (Beta) mfe-analytics (Gamma) mfe-messaging (Delta) mfe-admin (Platform) INFRASTRUCTURE api-gateway bff-workers version-service realtime-service Cloudflare Workers

Team Ownership Model

TeamOwnsReposResponsibilities
PlatformShell App, API Gateway, Version Service, CI/CD, Design Systemshell-app, api-gateway, version-service, platform-coreInfrastructure, shared tooling, MFE onboarding, release coordination
Team AlphaDashboard MFE, Dashboard BFFmfe-dashboard, BFF in bff-workersDashboard features, data visualization
Team BetaSettings MFE, Settings BFFmfe-settings, BFF in bff-workersUser/org settings, preferences
Team GammaAnalytics MFE, Analytics BFFmfe-analytics, BFF in bff-workersReporting, charts, data export
Team DeltaMessaging MFE, Real-time Servicemfe-messaging, realtime-serviceChat, notifications, WebSocket features

Ownership Principles

  1. Vertical ownership: Each team owns their MFE end-to-end (UI → BFF → data).
  2. Shared libs are platform-owned: The monorepo is maintained by the Platform team with contributions from all teams via PRs.
  3. Autonomous deployments: Each MFE can be deployed independently without coordinating with other teams.
  4. Contract-based integration: Teams agree on event contracts (CustomEvents) and API schemas, not implementation details.
  5. Design system governance: Platform team reviews and merges design system changes; feature teams propose via PR.

Key Architectural Decisions

DecisionChoiceADR
MFE compositionModule Federation v2ADR-001
Edge platformCloudflare WorkersADR-002
Repository strategyHybrid mono + polyADR-003
Package managerpnpmADR-004
AuthenticationWorkOS AuthKitADR-005
Monorepo orchestrationTurborepoADR-006
Inter-MFE communicationBrowser CustomEventsADR-007
BundlerRsbuild / RspackADR-008
DocumentDescription
Module FederationMF v2 configuration, shared deps, dynamic remotes
Cloudflare InfrastructureWorkers, R2, KV, D1, service bindings
Design SystemDual distribution, theming, Storybook
Local DevelopmentDev workflow, yalc, Verdaccio, Miniflare
Repository StrategyMonorepo/polyrepo structure, Turborepo, pnpm
Real-time CommunicationDurable Objects, WebSockets, hibernation
Version ManagementAdmin UI, version pinning, rollback
AuthenticationWorkOS, JWT validation, session management
CI/CD & DeploymentGitHub Actions, Changesets, preview envs
Inter-MFE CommunicationCustomEvents, typed payloads, patterns
PreviousADR 008: Rsbuild/Rspack as BundlerNextModule Federation v2