This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Isomorphic Layout Composer (ILC): a layout service that composes pages from micro-frontend "fragments", rendering them on the server (SSR) and handing over to client-side routing (single-spa). The repo is a pnpm workspace (pnpm-workspace.yaml) with one lockfile, pnpm-lock.yaml, at the root:
ilc/— the composer itself (server + browser client). Port 8233.registry/— config service and admin UI that ILC reads apps, routes, templates and settings from. Port 4001 (UI loginroot/pwd, read-onlyreadonly/pwd). The admin UI inregistry/client/is a workspace package of its own.e2e/— CodeceptJS end-to-end tests that run ILC + Registry + the demo apps.
Node >= 22 and pnpm (the version in packageManager of the root package.json, e.g. via corepack enable pnpm). The root pnpm install installs every workspace package. pnpm only links a package into an app when its package.json declares it, so declare every dependency the code imports. Settings (overrides, allowed build scripts, the 2 week minimumReleaseAge) live in pnpm-workspace.yaml, not in .npmrc or package.json.
Root:
pnpm start— whole local environment viastart_all.js: ILC dev server, Registry (migrate + seed + dev), the Registry UI watcher, a local OAuth server (registry/lde/oauth-server.ts) and the demo apps in Docker.pnpm start:no-appsskips the demo apps (when developing them separately).pnpm build— builds ILC and Registry (needed before E2E).pnpm format/pnpm format:check— Prettier overregistry/**/*.tsandilc/**/*.{js,ts}only.
ILC (cd ilc):
pnpm test— server +common/tests (mocha,ts-node).pnpm test:client— browser tests (karma; builds SystemJS first).pnpm dev— rebuilds the server on change;pnpm build— server (tsc -p tsconfig.server.json), SystemJS, client (webpack).
Registry (cd registry):
pnpm dev,pnpm migrate,pnpm seed,pnpm reset(DB to a clean state).- PostgreSQL is the only supported DB: start it with
docker compose up postgres, the defaults inconfig/default.tsmatch it and.env(from.env.example) overrides theDB_*variables.pnpm startat the root needs it too. pnpm testdrops and recreates theDB_NAMEdatabase (ilcby default, so it wipes a local dev database) throughdocker exec postgres; suites that usedbFactory()fromtests/common.tsget their own<DB_NAME>_isolateddatabase.pnpm migrate:make <name>creates a Knex migration inserver/migrations.- TypeScript 7.
tsconfig.jsonextends the roottsconfig.base.jsonand referencestsconfig.app.json, which builds the server intobuild/, andtsconfig.spec.json, which type-checks the specs.pnpm compilechecks the app project,pnpm testandtest:cicheck the spec project; to check both without building, runpnpm exec tsc -p tsconfig.app.json --noEmit && pnpm exec tsc -p tsconfig.spec.json. - Tests and
lde/run from source throughtsx, which does not type-check:pnpm testrunstsc -p tsconfig.spec.jsonfirst.tsxcompiles each file the way native ESM would run it: imports are evaluated before the rest of the module, and module exports cannot be stubbed with sinon. - The compiled server, the assets discovery runner and the Knex CLI read node-config from
build/config:config/configDir.tssetsNODE_CONFIG_DIRunless it is already set. The knexfile imports it first, and the server entry points importserver/preload.tsfirst, which loads it before New Relic (newrelic.jsreads node-config). Nothing loads TypeScript at runtime, so a new entry point needs the same first import, or node-config finds the.tsfiles inconfig/and fails. It is set in code, not in package scripts, because images built on top of the registry image startnode build/server/index.jsdirectly and add their ownconfig/*.ts, whichpnpm buildcompiles intobuild/config.
E2E (cd e2e, after pnpm build at the root): pnpm start, pnpm start:verbose, pnpm start:verbose:ui (visible browser).
Both ilc/.mocharc* and registry/.mocharc* define a spec glob, and a file passed on the command line is added to it, so pnpm exec mocha path/to/file.spec.ts still runs the whole suite. Either filter by title, pnpm test --grep "<describe or it text>", or bypass the config:
NODE_ENV=test pnpm exec mocha --no-config --require ts-node/register --timeout 5000 --exit path/to/file.spec.tsIn registry, use --require tsx/cjs instead of ts-node/register, and prefix with pnpm exec dotenv -- so the DB_* variables from .env apply.
Fastify app (app.js). Every page request goes through routes/wildcardRequestHandlerFactory.ts:
- Fetch the Registry config through
server/registry/Registry.js(cached), filtered by domain; Registry address fromconfig/default.json5(registry.address, envREGISTRY_ADDR). - Apply the per-browser override from the
ILC-overrideConfigcookie (tailor/parse-override-config.tssanitizes it against theoverrideConfigTrustedOriginssetting;tailor/merge-configs.tsmerges it). This powers "develop in production" (docs/develop_in_production.md) and is a security boundary: any URL that survives sanitization is loaded as a script or fetched for SSR. - Resolve the route (
common/router), then render the route's template with TailorX (tailor/): fragments are fetched server-side (tailor/request-fragment.ts), and the Registry config plus overrides are injected into the page (tailor/configs-injector.ts,tailor/fragment-hooks.jswrites<script type="text/spa-config-override">).
single-spa based. Client.js boots the page from the injected config, ClientRouter.js handles navigation, registerSpaApps.js registers apps per slot, BundleLoader.ts loads app bundles through a custom SystemJS build (ilc/systemjs), TransitionManager handles reroute animations and the ParcelApi exposes parcels. ilc/common is shared between server and client (router, URL processing, i18n cookie). Client debug logs: localStorage.debug = 'ILC:*'.
Server and client behavior can be extended with plugins (ilc-plugins-sdk), listed in server.plugins.manifest.js / client.plugins.manifest.js.
Our ownership:
Express 5 + Knex on PostgreSQL (server/db/index.ts). Each entity has its own folder (apps, appRoutes, templates, sharedLibs, sharedProps, routerDomains, settings, authEntities, …) with the same layout:
interfaces/: the row type, which follows the PostgreSQL schema and is registered for Knex intypings/knex/tables.d.ts, the Zod schemas, and the input types derived from them withz.output.repositories/: that table's queries. Writes take the transaction.services/: versioned writes, not-found handling and business rules, such as checks that need other tables.routes/: one handler factory per file. It takes the service and validates its input withvalidated()(server/common/validation).
Code that belongs to no single entity:
server/common/services/: registry logic shared by several entities, such as assets discovery, entries and protected entities.server/util/: generic helpers and infrastructure that know nothing about registry entities, such as the logger, the plugin manager,extendError, the axios helpers anddeepMerge. A standalone helper gets its own file named after its export (defined.ts,deepMerge.ts); helpers for one concern share a file (db.ts,logger.ts).
server/composition.ts builds the repositories and services once, and app.ts passes them to the routers. Things that span files:
- Versioning: services wrap entity writes in
versioning.withVersion(user, { type, id }, async (trx) => …)(server/versioning/services/Versioning.ts), which snapshots the record and stores a revertible version. Queries inside the callback must usetrx. Withoutid, the callback returns the created row, whose id column identifies it. Reads that need the version useversioning.versionedSelect(...). - Errors: handlers and services may simply throw; Express 5 forwards rejected async handlers to
server/errorHandler, which mapshttpErrors.*to 4xx and everything else to a logged 500 with an error ID. A failed validation is anUnprocessableContent(422) with Zod's error summary. - Settings have a scope; ILC-scoped ones (e.g.
overrideConfigTrustedOrigins) are served to ILC. - Assets discovery (
server/runnerAssetsDiscovery.ts,pnpm assetsdiscovery) runs as a separate process in production and refreshes app bundle URLs from their manifests. - Admin UI:
registry/client, a React Admin app built with webpack.
Registry tests (registry/tests) drive the HTTP API with supertest. Unit tests of a single module that need no database sit next to it as <file>.spec.ts. Cleanups in finally/hooks call ensureDeleted(req, url) from tests/common.ts, which fails when a record is neither deleted nor already absent, instead of leaving it to break later tests.
-
TypeScript configs follow the Nx layout: the root
tsconfig.base.json(fromtsc --init) holds the shared compiler options, the roottsconfig.jsonreferences the packages that use it (onlyregistryso far), and each package'stsconfig.jsonextends the base and references itstsconfig.app.jsonandtsconfig.spec.json. -
Commits follow Conventional Commits (commitlint); husky + lint-staged run Prettier on staged files. Prettier: 4 spaces, single quotes, width 120.
-
.github/workflows/ci.ymlruns on pull requests and pushes todevelop(the main branch). ILC and Registry are tested inside their Docker images (amd64; arm64 is built on nativeubuntu-24.04-armrunners). Each PR also builds and tests the base branch (destmatrix entries) for the coverage-diff comment. Onlydeveloppushes publish to Docker Hub (namecheap/ilc,namecheap/ilc_registry, staged throughnamecheap/ilc_tmp);release.ymlre-tags them on version tags. -
User-facing docs live in
docs/(MkDocs,mkdocs.yml). -
Currently there is mixed codebase of typescript and javascript, but we're in progress into full migration to the typescript. Convert files to TS if reasonable
-
Don't expose any internal infra details like urls, credentials, plugins, etc
-
Avoid breaking changes for consumers unless the author asks for them
-
Ensure there is a migration if database schema changed