chapter 1 · Building Arda
  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
page 5 of 7 · read 0%

Feb 2026 · Updated Oct 2026 · 11 min read · ARDA Labs · Architecture note

A Shell and Thirteen Remotes: Reading Arda's Module Federation Setup

An audit of arda-mfe as it stands: one Vite shell, thirteen remotes mapped by a 42-prefix route registry, twenty shared singletons with requiredVersion off, a per-route error boundary, and two deploy paths that disagree about how many remotes exist.

✎ arda-labs/arda-mfe · #Arda Labs #Module Federation #Micro-Frontend #React #Vite #Cloudflare Workers

At a glance

13

Remotes behind one shell

apps/ in arda-mfe, plus the shell

42

Route prefixes in the registry

federation.routes.ts

20 / 8

Shared singletons / packages kept per-remote

federation.shared.ts

7 of 13

Remotes copied by the Dockerfile

Dockerfile COPY lines

Problem Context

A single frontend for IAM, finance, loans, deposits, HRM, workflow, CRM and more would be one build and one release unit. The repo splits it into a shell and thirteen remotes so each domain has its own build and can be deployed on its own, and pays for that with a shared-dependency contract that has to stay consistent.

Arda System Architecture
Browser / ClientsReact Module FederationCloudflare TunnelDDoS · SSL · Zero Open PortsTraefik IngressForwardAuth Verificationauth-gateway (BFF)Session & Context ProxyOry Kratos + HydraIdentity & OAuth2 / OIDCiam-serviceRBAC, Roles & Tenant PoliciesGo services: 15 in the repo, 6 shown (gRPC & NATS JetStream)financeworkflowcrmhrmplatformnotification/media

A Shell and Thirteen Remotes: Reading Arda's Module Federation Setup

Architecture & Design

The shell (Vite 8.1.1, React 19.2.7, @module-federation/vite 1.21.5) resolves a URL through federation.routes.ts to one of thirteen remotes and imports its ./Routes expose lazily, checking a routes-contract version after load. Remotes are found at /mfes/<name>/remoteEntry.js on the same origin, or at an env-var override. A 20-entry singleton list in federation.shared.ts carries React, the router, and the auth, api, i18n, theme, notifications and format packages; eight packages are intentionally bundled per remote. Failures are contained by a per-route error boundary with retry. Deployment is either one Cloudflare Worker per app or one nginx image, and the two disagree on which remotes exist.

Key Technical Decisions

  1. 1One route registry owns URL-to-remote mapping: the shell render table and preload read the same file and check:federation verifies it, but the /admin/* space is partitioned by hand across iam, platform and mdm.
  2. 2Singleton with requiredVersion: false: no version-mismatch noise and no duplicate React, but a remote built from a different lockfile would load the shell's copy without any warning.
  3. 3Eight workspace packages are deliberately not shared, each with a written reason: remotes stay isolated (own QueryClient, own ui copy), at the cost of duplicated code and no cross-remote cache invalidation.
  4. 4A numeric routes-contract version plus N-1 chunk retention: a bad remote becomes a retryable error and old chunks survive a deploy, but the version is still 1 and mixed-version loads are untested.
  5. 5Same-origin /mfes/<name>/ paths with env overrides instead of a runtime manifest service: simple to serve and cache, but it ties every remote to the shell's origin.

Why the frontend is split into thirteen remotes

The old version of this article described one shell and seven remotes. arda-mfe now has fourteen apps under apps/: the shell plus thirteen remotes (account, ai, capital, crm, deposit, finance, hrm, iam, loan, mdm, platform, statistical, workflow). Next to them sit fourteen workspace packages under packages/. The remote names overlap with the backend's domain vocabulary, but I did not check them one-to-one against the Go services, so I won't claim a strict mirror.

The repo never says why micro-frontends were chosen over one app with lazy routes, so I can only describe what the setup buys. Each remote is its own Vite build with one required expose, ./Routes, and its own package.json. Six of them (capital, deposit, finance, hrm, loan, statistical) expose a second module such as ./taskForms, which the workflow workbench uses to render task forms by key. That means the "routes only" rule from the old copy is not quite true any more: a remote can also be loaded as a form host.

Ownership of URLs is a single table, federation.routes.ts, with 42 path prefixes across the thirteen remotes. The comment on its first line says the shell's render ownership and its code preloading must both read this same registry.

// federation.routes.ts
export const remoteRoutePrefixes = {
  iam: ["/admin/users", "/admin/groups", "/admin/roles", /* ... */],
  finance: ["/finance"],
  crm: ["/customers"],
  loan: ["/loans"],
  // ... 13 remotes, 42 prefixes in total
} as const

export function resolveRemoteRoute(pathname: string) {
  for (const [name, prefixes] of Object.entries(remoteRoutePrefixes)) {
    for (const prefix of prefixes) {
      if (pathname === prefix || pathname.startsWith(`${prefix}/`)) {
        return { name: name as RemoteName, prefix }
      }
    }
  }
  return undefined
}

Note that /admin/* is split by hand: iam, platform and mdm each own different /admin/... prefixes. The old snippet showing /iam/* and /finance/* routes was illustrative, not what the shell does.

How the shell finds and loads a remote

The toolchain, from bun.lock: Bun 1.3.14 (pinned in packageManager), Vite 8.1.1, @vitejs/plugin-react 6.0.3, @module-federation/vite 1.21.5 (the only dependency pinned without a caret), React 19.2.7, react-router-dom 7.18.2, TypeScript 6.0.3. Every app uses shareStrategy: "loaded-first".

The shell's vite.config.ts declares thirteen remotes through federationRemote(name, envVar, dev) from federation.shared.ts. The entry URL is process.env[envVar] if set (for example CRM_REMOTE_ENTRY), otherwise http://localhost:<port>/remoteEntry.js in dev, otherwise the same-origin path /mfes/<name>/remoteEntry.js. So production has no remote registry service and no per-environment manifest: the shell and remotes are expected to be served from one origin under fixed paths, and the env vars are the only override. Remote dev ports are fixed (5101 to 5110, then 8110 to 8112) with strictPort: true, because the shell hardcodes them; a comment says a port drift made first load look like a timeout and retry.

In apps/shell/src/remote-routes.ts each remote is lazyRemote(() => import("crm/Routes")), and the route table is generated from the registry above, one <prefix>/* entry per prefix. lazyRemote does two checks after the import resolves:

// apps/shell/src/lazy-remote.ts
const component = module.default
if (!component || (typeof component !== "function" && typeof component !== "object")) {
  throw new Error("Remote Routes must expose a default React component")
}
// Legacy v1 remotes did not publish metadata. Retain rolling-release compatibility.
if (component.federation && component.federation.version !== ROUTES_CONTRACT_VERSION) {
  throw new Error(`Incompatible remote contract ${component.federation.version}; expected ${ROUTES_CONTRACT_VERSION}`)
}

ROUTES_CONTRACT_VERSION is 1, with a comment saying to bump it only for an incompatible Routes, preload or provider change. Each build also carries a VITE_MFE_BUILD_ID (short git hash plus timestamp) that is attached to the route contract and recorded in a "remote-ready" performance mark.

On dev, bun run dev clears the dev ports and starts every app's dev script in parallel, and the shell proxies /api/* paths to the auth-gateway BFF at localhost:8082.

Shared singletons and what must stay in lockstep

federation.shared.ts is the single place that lists shared dependencies; its header says not to edit each remote's vite.config.ts. remoteSharedDeps has 20 entries: React and its runtimes, react-router-dom, react-toastify, exceljs, pdfjs-dist, and six workspace packages (i18n, api, theme, auth, notifications, format), several of them with a trailing-slash twin so subpath imports like @workspace/auth/store are also shared. Every entry is singleton: true with requiredVersion: false.

That second flag is the coupling cost. With requiredVersion: false, Module Federation will not compare version ranges, so a remote built against a different React minor still gets the shell's copy and nothing warns. What keeps this safe is not the runtime but the monorepo: all apps resolve one bun.lock, so a full build uses one React. It stops being safe the moment a remote is built from a different lockfile than the shell, which the per-app deploy path below makes possible.

The comments name the failure mode of a split singleton: two instances of the auth store, toast, theme or query client, so logout does not propagate and toasts vanish. They also record one real incident. @workspace/posting-flow was deliberately not shared because, per the comment, registering it on 2026-09-08 reshuffled the shell's pre-bundled share groups, @workspace/auth/loading-screen loaded asynchronously, and the first render mounted an undefined component (React error #130, a white screen on arda.io.vn).

// federation.shared.ts
export const sharedWorkspaceExemptions = {
  "@workspace/ui": "presentational-only; no cross-tree state",
  "@workspace/query": "per-remote cache isolation; retained across navigation, cleared on auth scope changes",
  "@workspace/ai": "shell-only until CRM tool-renderer integration lands",
  "@workspace/posting-flow": "presentational-only; sharing broke shell boot order (React #130)",
  // ... 8 exemptions in total
} as const

The other half of the policy is the exemption map: eight packages are deliberately bundled per remote, each with a written reason. @workspace/ui is the biggest of them, so every remote ships its own copy of the components, which is also why the old claim that @workspace/ui avoids duplicating bundles was wrong. Each remote keeps its own TanStack QueryClient, so there is no cross-remote cache invalidation by design.

bun run check:federation enforces this: it parses the shell config, route registry, type declarations and shared lists, requires a non-empty justification for each exemption, and fails when an unshared workspace package is imported by two or more deployment units without one. exceljs and pdfjs-dist are provided by the shell and consumed by remotes with import: false, so a remote cannot fall back to its own copy.

What happens when a remote fails to load

Every remote route is wrapped in RemoteRoute (apps/shell/src/components/RemoteRoute.tsx): a class RemoteErrorBoundary around a Suspense with a route-loading fallback. On error it reports through reportBrowserError({ kind: "remote-module" }) and renders a message with two buttons: retry, and full page reload. The boundary is keyed on the pathname, so navigating elsewhere resets it. Retry calls retryFailedLazyLoads(), and lazyRemote clears its cached promise on rejection, so a failed import is attempted again instead of being remembered as failed. That is what the old copy's "wrap remotes in an Error Boundary" advice looks like when it exists in code.

Failure is therefore per route subtree: one remote crashing leaves the shell chrome and the other remotes usable. The contract check above turns a mismatched Routes shape into the same error UI instead of a half-rendered page.

The more interesting failure is a deploy happening while a tab is open. The browser holds the old shell, requests remoteEntry.js, and may get a new remote whose hashed chunks differ. scripts/asset-release.mjs handles one version of this: at build time it fetches the previously deployed release manifest from https://arda.io.vn (in CI), validates each asset by path pattern and sha256, and copies the previous release's hashed assets into the new output, so N-1 chunks stay available. tests/federation/release.test.ts covers that old chunks survive, old remoteEntry.js pointers do not, and a tampered asset is rejected. The nginx config caches remoteEntry.js for 30 seconds and hashed assets as immutable for a year. Retention is best-effort in the script's own words: a network hiccup must not break a deploy, so a failed fetch means no retained chunks.

Deploy paths, ownership, and how the session reaches a remote

There are two deploy paths in the repo, and they do not agree. The Cloudflare path has one wrangler.<app>.jsonc per app (fourteen files). The shell Worker owns arda.io.vn/* with single-page-app fallback and passes /api/* through; each remote is an assets-only Worker bound to arda.io.vn/mfes/<name>/*. bun run cf:deploy <app> builds that app (stamping a build id) and runs wrangler deploy for it alone, so a remote can ship without rebuilding the others. The repo does not show who triggers it or from where; there is no workflow for it in .github/workflows.

The container path is Dockerfile: build everything with bun run build, then serve from nginx 1.29 with the shell at the root and remotes under /mfes/<name>. images.yml publishes it as ghcr.io/arda-labs/arda-mfe/web, and arda-infra runs that image as the web Deployment in an arda-web namespace, with /mfes routed by an ingress. Here the whole frontend is one image, so a "remote release" is a rebuild of everything.

The honest rough edge: the Dockerfile copies the shell and only seven remotes (iam, platform, finance, hrm, account, workflow, crm). The other six (ai, loan, mdm, deposit, capital, statistical) are built but not copied into the image, so on that path their remoteEntry.js would 404. The arda-infra README itself says to confirm which path serves arda.io.vn before changing either. I can't tell from the repos which one is live for the thirteen remotes.

Auth is not a federation concern. The remotes share @workspace/auth and @workspace/api as singletons, so there is one session store and one HTTP client in the page. The client uses credentials: "include", and scripts/check-credentialed-fetch.mjs fails the typecheck if any raw fetch( lacks it. In production the API origin is https://api.arda.io.vn when the page is on arda.io.vn, otherwise relative /api, which the dev server proxies to the BFF. The session itself is the opaque cookie covered in the authentication article; no remote ever sees a token. Remotes do not authenticate anyone: they render, and the gateway decides.

Gaps, and what I would check next

Verification in CI (verify.yml) is wider than I expected: typecheck chains i18n, package-boundary, credentialed-fetch, no-fail-open-fallback, federation, page-size and feature-structure checks before per-package tsc; then test:federation, test:features, a full app build with check:bundles, and Playwright against a static server with a mocked BFF. The repo has 32 test files under apps/ and packages/ plus 4 browser tests in a single spec, so the browser layer is thin for thirteen remotes. I have not run any of it.

Things I'd check, in order:

  1. Which deploy path serves arda.io.vn, and fix or delete the other. This decides whether independent remote release is real or only available on the Cloudflare path.
  2. Whether Cloudflare deploys of individual remotes build against the same lockfile commit as the live shell. requiredVersion: false hides a React or router mismatch; the only guard is that the workspace shares one bun.lock.
  3. The contract version is still 1 (the clone has a single commit, so I can't see its history), and legacy remotes without metadata are accepted. The rolling-release path (new shell, old remote, and the reverse) is only reasoned about in comments; I did not find a test that loads mismatched builds together.
  4. A test for the reverse of the 2026-09-08 incident: check:federation checks lists, not boot order. The code says to revisit sharing posting-flow only with a hard-repro harness, which doesn't exist yet.
  5. docs/federation-performance-review-2026-09-15.md lists first-load costs and proposes work such as moving ExcelJS out of the initial graph. I'm not repeating its measurements here, only noting that the shell now provides exceljs and pdfjs-dist as host-owned singletons, which looks like a follow-up to it. The repo doesn't link the two.

What the repo does not tell me: team structure, who owns which remote, release cadence, or why this architecture was picked. I won't guess those.

Verified repository evidence

  • frontend · direct

    React Module Federation shell with 13 domain remotes, a route-prefix registry, shared singletons configured in federation.shared.ts, and per-route error boundaries.

    ↳ apps/ holds the shell and 13 remotes; packages/ holds 14 shared @workspace packages.

    arda-labs/arda-mfe ↗

Key Engineering Takeaways

  • The coupling that matters is not the remotes' code but the shared lists: 20 singletons and 8 exemptions have to agree with every remote and one lockfile.
  • Failure containment exists and is real (route-scoped boundary, retry, contract check), but mixed-version rollout is argued in comments rather than tested.
  • Independent remote release is only real on the Cloudflare path; the Dockerfile image ships 7 of 13 remotes, so resolve which path serves production.