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
✎ Key Insights in 30 Seconds
Architecture note: 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.
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.
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
- 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.
- 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.
- 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.
- 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.
- 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.
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.
! careful
The Dockerfile image covers 7 of 13 remotes. If that is the path serving production, six remotes cannot load; if Cloudflare serves it, the Dockerfile is stale. Either way one of the two paths is wrong.
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:
- 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. - Whether Cloudflare deploys of individual remotes build against the same lockfile commit as the live shell.
requiredVersion: falsehides a React or router mismatch; the only guard is that the workspace shares onebun.lock. - 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. - A test for the reverse of the 2026-09-08 incident:
check:federationchecks lists, not boot order. The code says to revisit sharingposting-flowonly with a hard-repro harness, which doesn't exist yet. docs/federation-performance-review-2026-09-15.mdlists 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 providesexceljsandpdfjs-distas 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.