@opengroundplan/core 0.1.1

package/templates/architectures/bff/files/docs/architecture/bff.typescript.md

@@ -0,0 +1,113 @@
+# Architecture — Backend-for-Frontend ({{ solutionName | title }}, TypeScript)
+
+One server-side backend per **user experience**, owned by the team that builds that UI. Each BFF
+serves exactly its own client's needs; none of them is a general-purpose API.
+
+## The one rule that matters
+
+> **No BFF imports another BFF.** Not a type, not a helper, not a DTO. `scripts/check-bff-boundaries.mjs`
+> fails the build the moment one does.
+
+Two clients that share code directly stop being independently releasable, and you are back to the
+single contended backend the pattern exists to escape — only now with an extra network hop. When
+the {{ primaryClient | kebab }} and {{ secondaryClient | kebab }} backends need the same thing,
+**duplicate it**. Sam Newman's guidance is to extract shared logic only at the *third*
+implementation, and he warns that a shared library reintroduces exactly the coupling you were
+escaping.
+
+The corollary matters just as much: **keep business rules out of the BFF.** A BFF does shaping,
+aggregation, protocol translation, and session/token handling. A policy written in
+`{{ primaryClient | kebab }}/aggregate.ts` will drift from whatever `{{ secondaryClient | kebab }}/aggregate.ts`
+does, and your two clients will start enforcing different rules. That drift — not duplicated DTOs
+— is the real cost of this architecture.
+
+## Layout
+
+```
+src/
+  bff/
+    {{ primaryClient | kebab }}/                 # one BFF per experience, not per team
+      index.ts             #   public surface: routes + DTO types
+      routes.ts            #   web-standard Request -> Response handlers
+      aggregate.ts         #   composes downstream calls into this client's shape
+      dto.ts               #   DTOs this client owns outright
+      config.ts            #   this client's knobs (page size, currency)
+    {{ secondaryClient | kebab }}/
+      …                    #   same files, deliberately different shapes
+  downstream/              # shared clients for upstream services — the ONLY shared layer
+    index.ts               #   the sole importable file (deep imports are a violation)
+    config.ts              #   every service URL, timeout, and retry default
+    http-client.ts
+    profile-client.ts
+    orders-client.ts
+scripts/
+  check-bff-boundaries.mjs # the fitness test
+```
+
+`downstream/` depends on no BFF, ever. It sits *beneath* them; the dependency arrow only points
+down. Add a BFF by copying a client folder — the checker discovers any immediate child of
+`src/bff/`, so there is nothing to register.
+
+## Why the two folders differ
+
+They are not copies, and that is the test of whether you needed a BFF at all.
+`{{ primaryClient | pascal }}DashboardDto` carries avatar, email, formatted totals and a 25-row page.
+`{{ secondaryClient | pascal }}HomeDto` carries an id, a name, and five order summaries — payload size is
+what a phone radio actually charges for. Same two upstream services, two different answers.
+
+## Mounting
+
+Handlers are web-standard `(Request) => Promise<Response>`, so the host mounts them on Hono,
+Fastify, Next route handlers, Bun, or `node:http` via an adapter, without importing anything past
+a BFF's `index.ts`:
+
+```ts
+import { {{ primaryClient | camel }}Routes } from './bff/{{ primaryClient | kebab }}/index.js';
+```
+
+## Configuration
+
+Downstream hosts, timeouts, and retries resolve **only** in `src/downstream/config.ts`
+(`PROFILE_SERVICE_URL`, `ORDERS_SERVICE_URL`, `DOWNSTREAM_TIMEOUT_MS`, `DOWNSTREAM_RETRIES`), so
+both BFFs talk to the same services the same way. Per-client knobs live in that client's own
+`config.ts` under a `{{ primaryClient | upperSnake }}_BFF_` / `{{ secondaryClient | upperSnake }}_BFF_` prefix.
+
+## Enforcement
+
+`node scripts/check-bff-boundaries.mjs` — appended to `lint`, also available as `check:bff`.
+Exits non-zero on:
+
+1. a BFF importing another BFF, by relative path **or** by workspace package name,
+2. `downstream/` importing any BFF,
+3. a BFF deep-importing past `downstream/index.ts`.
+
+It reads specifiers as written and never resolves them on disk, so bundler and TS path-mapping
+quirks cannot make it pass by accident. `--self-test` proves the rules still fire. Override
+discovery with `BFF_ROOTS` / `BFF_SHARED_ROOTS` if you move the layout (a monorepo would use
+`BFF_ROOTS=apps`).
+
+**Not enforced mechanically, and you must watch it in review:**
+
+- **Business logic leaking into a BFF.** No linter can tell shaping from policy. This is the
+  failure mode that actually kills BFF codebases; make it a standing review question.
+- **One BFF per team instead of per experience.** A folder count cannot detect that you built a
+  distributed monolith.
+- **Missing distributed tracing across BFF → services.** Without it the BFF is an invisible
+  latency hop. That is deployment configuration, not something a source scan can see.
+
+If you would rather solve *only* shaping and both ends live in this monorepo, tRPC gives you a
+typed client–server contract with no BFF to maintain. It does not replace the token-handler BFF
+below.
+
+## If this is a token-handler BFF
+
+`draft-ietf-oauth-browser-based-apps` (Best Current Practice track) strongly recommends this
+architecture for applications handling personal data: the browser holds only an
+`HttpOnly`/`Secure`/`SameSite` cookie while the BFF holds access and refresh tokens and proxies
+API calls. That changes the *class* of compromise — there is no refresh token in the browser to
+exfiltrate. Adding it needs server-side session storage and cookie handling, which this overlay
+does not scaffold.
+
+Sources: [Sam Newman — BFF](https://samnewman.io/patterns/architectural/bff/) ·
+[draft-ietf-oauth-browser-based-apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps) ·
+[Microsoft Learn — Backends for Frontends pattern](https://learn.microsoft.com/en-us/azure/architecture/patterns/backends-for-frontends).

package/templates/architectures/bff/files/scripts/check-bff-boundaries.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * Architecture fitness test for the backend-for-frontend layout.
+ *
+ * The rule that matters: no BFF imports another BFF. The moment one client backend reaches
+ * into another they stop being independently releasable, and you are back to the single
+ * contended API the pattern was meant to escape — with extra hops.
+ *
+ * Reads import specifiers as written and never resolves them on disk, so TypeScript/bundler
+ * resolution differences cannot make it pass by accident.
+ */
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+/** Every tunable lives here. Nothing below reads the environment directly. */
+const config = {
+  /** Directories whose immediate children are each a BFF. */
+  bffRoots: split(process.env.BFF_ROOTS) ?? ['src/bff'],
+  /** Downstream service clients — shared by every BFF, dependent on none. */
+  sharedRoots: split(process.env.BFF_SHARED_ROOTS) ?? ['src/downstream'],
+  /** The only file inside a shared root a BFF may import. */
+  sharedEntry: process.env.BFF_SHARED_ENTRY ?? 'index',
+  /** Where to look for importers — a BFF can be imported from anywhere, not just from a BFF. */
+  scanRoots: split(process.env.BFF_SCAN_ROOTS) ?? ['src', 'apps'],
+  extensions: ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'],
+  skipDirs: ['node_modules', 'dist', 'build', 'out', 'coverage', '.git', '.turbo', '.next'],
+};
+
+function split(value) {
+  return value
+    ? value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+    : undefined;
+}
+
+const SPECIFIER_PATTERNS = [
+  /(?:^|[\s;}])(?:import|export)[^;]*?\sfrom\s*['"]([^'"]+)['"]/g,
+  /(?:^|[\s;}])import\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+  /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g,
+];
+
+export function specifiersOf(source) {
+  const found = new Set();
+  for (const pattern of SPECIFIER_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const match of source.matchAll(pattern)) found.add(match[1]);
+  }
+  return [...found];
+}
+
+/** The directory in `dirs` that contains (or is) this path, or null. */
+export function containingDir(filePath, dirs) {
+  return dirs.find((dir) => filePath === dir || filePath.startsWith(`${dir}/`)) ?? null;
+}
+
+/** Package portion of a bare specifier: "@scope/pkg/sub" -> "@scope/pkg". */
+export function packageOf(specifier) {
+  const segments = specifier.split('/');
+  return specifier.startsWith('@') ? segments.slice(0, 2).join('/') : segments[0];
+}
+
+function withoutExtension(filePath) {
+  const extension = path.extname(filePath);
+  return config.extensions.includes(extension) ? filePath.slice(0, -extension.length) : filePath;
+}
+
+/** The rules, isolated so `--self-test` can prove they still fire. */
+export function violationOf(fromFile, specifier, bffs, sharedRoots = config.sharedRoots) {
+  const bffDirs = bffs.map((bff) => bff.dir);
+  const fromBff = containingDir(fromFile, bffDirs);
+  const fromShared = containingDir(fromFile, sharedRoots);
+
+  if (!specifier.startsWith('.')) {
+    const target = bffs.find((bff) => bff.pkgName && bff.pkgName === packageOf(specifier));
+    if (!target || target.dir === fromBff) return null;
+    if (fromBff)
+      return `imports "${specifier}" — that is the ${target.dir} BFF; BFFs never import each other`;
+    if (fromShared)
+      return `imports "${specifier}" — shared downstream code must not depend on a BFF`;
+    return null;
+  }
+
+  const target = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+  const toBff = containingDir(target, bffDirs);
+
+  if (toBff) {
+    if (fromShared)
+      return `imports "${specifier}" — shared downstream code must not depend on a BFF`;
+    if (fromBff && fromBff !== toBff) {
+      return `imports "${specifier}" — ${toBff} is another BFF; duplicate the code or push it down into ${sharedRoots[0]}`;
+    }
+    return null;
+  }
+
+  const toShared = containingDir(target, sharedRoots);
+  if (toShared && fromBff) {
+    const rest = target.slice(toShared.length + 1);
+    if (rest && withoutExtension(rest) !== config.sharedEntry) {
+      return `imports "${specifier}" — ${toShared} is reachable only through ${toShared}/${config.sharedEntry}`;
+    }
+  }
+  return null;
+}
+
+async function listFiles(root) {
+  const found = [];
+  const walk = async (dir) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = path.posix.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (!config.skipDirs.includes(entry.name)) await walk(child);
+      } else if (config.extensions.includes(path.extname(entry.name))) {
+        found.push(child);
+      }
+    }
+  };
+  await walk(root);
+  return found;
+}
+
+/** A BFF is any immediate child directory of a BFF root; its package name is matched too,
+ *  so a monorepo import like "@app/mobile-bff" is caught alongside a relative one. */
+async function discoverBffs() {
+  const bffs = [];
+  for (const root of config.bffRoots) {
+    let entries;
+    try {
+      entries = await readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries.filter((candidate) => candidate.isDirectory())) {
+      const dir = path.posix.join(root, entry.name);
+      const manifest = await readFile(path.posix.join(dir, 'package.json'), 'utf8').catch(
+        () => null,
+      );
+      let pkgName = null;
+      try {
+        pkgName = manifest ? (JSON.parse(manifest).name ?? null) : null;
+      } catch {
+        pkgName = null;
+      }
+      bffs.push({ dir, pkgName });
+    }
+  }
+  return bffs;
+}
+
+const SELF_TEST_BFFS = [
+  { dir: 'src/bff/web', pkgName: '@app/web-bff' },
+  { dir: 'src/bff/mobile', pkgName: '@app/mobile-bff' },
+];
+const SELF_TEST_SHARED = ['src/downstream'];
+const SELF_TEST_CASES = [
+  ['src/bff/web/aggregate.ts', '../mobile/dto.js', true],
+  ['src/bff/web/aggregate.ts', '@app/mobile-bff', true],
+  ['src/bff/web/aggregate.ts', '../../downstream/orders-client.js', true],
+  ['src/bff/web/aggregate.ts', '../../downstream/index.js', false],
+  ['src/bff/web/aggregate.ts', './dto.js', false],
+  ['src/bff/web/routes.ts', '@app/web-bff', false],
+  ['src/downstream/http-client.ts', '../bff/web/dto.js', true],
+  ['src/downstream/http-client.ts', '@app/web-bff', true],
+  ['src/downstream/index.ts', './http-client.js', false],
+  ['src/server.ts', './bff/web/index.js', false],
+];
+
+function selfTest() {
+  const wrong = SELF_TEST_CASES.filter(
+    ([file, specifier, expected]) =>
+      Boolean(violationOf(file, specifier, SELF_TEST_BFFS, SELF_TEST_SHARED)) !== expected,
+  );
+  for (const [file, specifier] of wrong) console.error(`self-test failed: ${file} -> ${specifier}`);
+  return wrong.length === 0;
+}
+
+async function main() {
+  if (process.argv.includes('--self-test')) {
+    if (!selfTest()) process.exit(1);
+    console.log(`BFF boundary rules verified against ${SELF_TEST_CASES.length} cases`);
+    return;
+  }
+
+  const bffs = await discoverBffs();
+  if (bffs.length === 0) {
+    // A silent pass over an empty file set is the failure mode this check exists to avoid.
+    console.error(`No BFFs found under ${config.bffRoots.join(', ')} — is BFF_ROOTS right?`);
+    process.exit(1);
+  }
+
+  const roots = [...new Set([...config.bffRoots, ...config.sharedRoots, ...config.scanRoots])];
+  const files = (await Promise.all(roots.map(listFiles))).flat();
+
+  const violations = [];
+  for (const file of [...new Set(files)]) {
+    const source = await readFile(file, 'utf8');
+    for (const specifier of specifiersOf(source)) {
+      const violation = violationOf(file, specifier, bffs);
+      if (violation) violations.push(`${file}: ${violation}`);
+    }
+  }
+
+  if (violations.length > 0) {
+    console.error(`BFF boundary violations (${violations.length}):\n${violations.join('\n')}`);
+    process.exit(1);
+  }
+  console.log(`BFF boundaries hold across ${bffs.length} BFF(s), ${files.length} file(s).`);
+}
+
+if (!selfTest()) {
+  console.error('The boundary rules no longer detect a known violation — fix violationOf().');
+  process.exit(1);
+}
+await main();

package/templates/architectures/bff/files/src/bff/__primaryClient.kebab__/aggregate.ts

@@ -0,0 +1,38 @@
+import { fetchOrders, fetchProfile, type OrderRecord } from '../../downstream/index.js';
+import { {{ primaryClient | camel }}BffConfig } from './config.js';
+import type { {{ primaryClient | pascal }}DashboardDto, {{ primaryClient | pascal }}OrderRowDto } from './dto.js';
+
+/** Formatting is presentation, so it belongs to the client — not to the orders service. */
+function toRow(order: OrderRecord): {{ primaryClient | pascal }}OrderRowDto {
+  const amount = (order.totalMinorUnits / 100).toFixed(2);
+  return {
+    id: order.id,
+    placedAt: order.placedAt,
+    status: order.status,
+    total: `${order.currency} ${amount}`,
+    itemCount: order.lines.reduce((sum, line) => sum + line.quantity, 0),
+  };
+}
+
+/**
+ * One round trip for the client, two in parallel from here — collapsing chatty calls is the
+ * job. Shaping and protocol translation only: a business rule written here will drift from
+ * whatever the sibling BFF does, and the two clients will start enforcing different policy.
+ *
+ * Unprefixed: the folder is the namespace, and this never crosses a BFF boundary.
+ */
+export async function buildDashboard(userId: string): Promise<{{ primaryClient | pascal }}DashboardDto> {
+  const [profile, orders] = await Promise.all([
+    fetchProfile(userId),
+    fetchOrders(userId, {{ primaryClient | camel }}BffConfig.orderPageSize),
+  ]);
+
+  return {
+    userId: profile.id,
+    displayName: profile.displayName,
+    email: profile.email,
+    avatarUrl: profile.avatarUrl,
+    orders: orders.orders.map(toRow),
+    totalOrderCount: orders.total,
+  };
+}

package/templates/architectures/bff/files/src/bff/__primaryClient.kebab__/config.ts

@@ -0,0 +1,30 @@
+/**
+ * Knobs this client alone owns. Downstream hosts and timeouts are NOT here — they live in
+ * src/downstream/config.ts, because both BFFs must talk to the same services the same way.
+ */
+
+type Env = Record<string, string | undefined>;
+
+const hostEnv = (): Env => (globalThis as { process?: { env?: Env } }).process?.env ?? {};
+
+const integer = (env: Env, name: string, fallback: number): number => {
+  const parsed = Number.parseInt(env[name] ?? '', 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+const text = (env: Env, name: string, fallback: string): string => env[name]?.trim() || fallback;
+
+export interface {{ primaryClient | pascal }}BffConfig {
+  /** A desktop table can render far more rows than a phone list. */
+  readonly orderPageSize: number;
+  readonly displayCurrency: string;
+}
+
+export function load{{ primaryClient | pascal }}BffConfig(env: Env = hostEnv()): {{ primaryClient | pascal }}BffConfig {
+  return {
+    orderPageSize: integer(env, '{{ primaryClient | upperSnake }}_BFF_ORDER_PAGE_SIZE', 25),
+    displayCurrency: text(env, '{{ primaryClient | upperSnake }}_BFF_DISPLAY_CURRENCY', 'USD'),
+  };
+}
+
+export const {{ primaryClient | camel }}BffConfig: {{ primaryClient | pascal }}BffConfig = load{{ primaryClient | pascal }}BffConfig();

package/templates/architectures/bff/files/src/bff/__primaryClient.kebab__/dto.ts

@@ -0,0 +1,21 @@
+/**
+ * Shapes owned by the {{ primaryClient | kebab }} BFF alone. Changing one needs no other client's
+ * agreement — that autonomy is the entire point, so never import these from a sibling BFF.
+ */
+
+export interface {{ primaryClient | pascal }}OrderRowDto {
+  readonly id: string;
+  readonly placedAt: string;
+  readonly status: string;
+  readonly total: string;
+  readonly itemCount: number;
+}
+
+export interface {{ primaryClient | pascal }}DashboardDto {
+  readonly userId: string;
+  readonly displayName: string;
+  readonly email: string;
+  readonly avatarUrl: string | null;
+  readonly orders: readonly {{ primaryClient | pascal }}OrderRowDto[];
+  readonly totalOrderCount: number;
+}

package/templates/architectures/bff/files/src/bff/__primaryClient.kebab__/index.ts

@@ -0,0 +1,6 @@
+/** Public surface of the {{ primaryClient | kebab }} BFF: routes to mount, DTOs to type a client against. */
+
+// Star re-exports, not named ones: a named list sorts by the rendered client name, so any
+// value other than the default would trip an import-sorting lint rule in the generated repo.
+export * from './dto.js';
+export * from './routes.js';

package/templates/architectures/bff/files/src/bff/__primaryClient.kebab__/routes.ts

@@ -0,0 +1,21 @@
+import { DownstreamError } from '../../downstream/index.js';
+import { buildDashboard } from './aggregate.js';
+
+/** Web-standard handler — mount it on Hono, Fastify, Next route handlers, or node:http. */
+export async function handle{{ primaryClient | pascal }}Dashboard(request: Request): Promise<Response> {
+  const userId = new URL(request.url).searchParams.get('userId');
+  if (!userId) return Response.json({ error: 'userId is required' }, { status: 400 });
+
+  try {
+    return Response.json(await buildDashboard(userId));
+  } catch (error) {
+    // The BFF is in the request path, so an upstream fault must not surface as a 500 mystery.
+    const status = error instanceof DownstreamError ? 502 : 500;
+    return Response.json({ error: 'dashboard unavailable' }, { status });
+  }
+}
+
+/** Route table so the host app mounts this BFF without reaching past its index. */
+export const {{ primaryClient | camel }}Routes = {
+  'GET /dashboard': handle{{ primaryClient | pascal }}Dashboard,
+} as const;

package/templates/architectures/bff/files/src/bff/__secondaryClient.kebab__/aggregate.ts

@@ -0,0 +1,23 @@
+import { fetchOrders, fetchProfile } from '../../downstream/index.js';
+import { {{ secondaryClient | camel }}BffConfig } from './config.js';
+import type { {{ secondaryClient | pascal }}HomeDto } from './dto.js';
+
+/**
+ * Same two services as the {{ primaryClient | kebab }} BFF, a different answer. Resist the urge to share this
+ * function with the sibling — Newman's rule is to extract only at the third implementation,
+ * and a shared aggregator reintroduces exactly the coupling a BFF exists to escape.
+ *
+ * Unprefixed: the folder is the namespace, and this never crosses a BFF boundary.
+ */
+export async function buildHome(userId: string): Promise<{{ secondaryClient | pascal }}HomeDto> {
+  const [profile, orders] = await Promise.all([
+    fetchProfile(userId),
+    fetchOrders(userId, {{ secondaryClient | camel }}BffConfig.orderPageSize),
+  ]);
+
+  return {
+    userId: profile.id,
+    displayName: profile.displayName,
+    recentOrders: orders.orders.map((order) => ({ id: order.id, status: order.status })),
+  };
+}

package/templates/architectures/bff/files/src/bff/__secondaryClient.kebab__/config.ts

@@ -0,0 +1,26 @@
+/**
+ * Knobs this client alone owns. Downstream hosts and timeouts are NOT here — they live in
+ * src/downstream/config.ts, because both BFFs must talk to the same services the same way.
+ */
+
+type Env = Record<string, string | undefined>;
+
+const hostEnv = (): Env => (globalThis as { process?: { env?: Env } }).process?.env ?? {};
+
+const integer = (env: Env, name: string, fallback: number): number => {
+  const parsed = Number.parseInt(env[name] ?? '', 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+export interface {{ secondaryClient | pascal }}BffConfig {
+  /** Smaller than the desktop page: payload size is what a phone radio actually charges for. */
+  readonly orderPageSize: number;
+}
+
+export function load{{ secondaryClient | pascal }}BffConfig(env: Env = hostEnv()): {{ secondaryClient | pascal }}BffConfig {
+  return {
+    orderPageSize: integer(env, '{{ secondaryClient | upperSnake }}_BFF_ORDER_PAGE_SIZE', 5),
+  };
+}
+
+export const {{ secondaryClient | camel }}BffConfig: {{ secondaryClient | pascal }}BffConfig = load{{ secondaryClient | pascal }}BffConfig();

package/templates/architectures/bff/files/src/bff/__secondaryClient.kebab__/dto.ts

@@ -0,0 +1,16 @@
+/**
+ * Shapes owned by the {{ secondaryClient | kebab }} BFF alone. Deliberately narrower than the
+ * {{ primaryClient | kebab }} DTO — no avatar, no email, no totals — because this client renders less and
+ * pays for every byte. Two BFFs whose DTOs converge did not need to be two BFFs.
+ */
+
+export interface {{ secondaryClient | pascal }}OrderSummaryDto {
+  readonly id: string;
+  readonly status: string;
+}
+
+export interface {{ secondaryClient | pascal }}HomeDto {
+  readonly userId: string;
+  readonly displayName: string;
+  readonly recentOrders: readonly {{ secondaryClient | pascal }}OrderSummaryDto[];
+}

package/templates/architectures/bff/files/src/bff/__secondaryClient.kebab__/index.ts

@@ -0,0 +1,6 @@
+/** Public surface of the {{ secondaryClient | kebab }} BFF: routes to mount, DTOs to type a client against. */
+
+// Star re-exports, not named ones: a named list sorts by the rendered client name, so any
+// value other than the default would trip an import-sorting lint rule in the generated repo.
+export * from './dto.js';
+export * from './routes.js';

package/templates/architectures/bff/files/src/bff/__secondaryClient.kebab__/routes.ts

@@ -0,0 +1,21 @@
+import { DownstreamError } from '../../downstream/index.js';
+import { buildHome } from './aggregate.js';
+
+/** Web-standard handler — mount it on Hono, Fastify, Next route handlers, or node:http. */
+export async function handle{{ secondaryClient | pascal }}Home(request: Request): Promise<Response> {
+  const userId = new URL(request.url).searchParams.get('userId');
+  if (!userId) return Response.json({ error: 'userId is required' }, { status: 400 });
+
+  try {
+    return Response.json(await buildHome(userId));
+  } catch (error) {
+    // The BFF is in the request path, so an upstream fault must not surface as a 500 mystery.
+    const status = error instanceof DownstreamError ? 502 : 500;
+    return Response.json({ error: 'home unavailable' }, { status });
+  }
+}
+
+/** Route table so the host app mounts this BFF without reaching past its index. */
+export const {{ secondaryClient | camel }}Routes = {
+  'GET /home': handle{{ secondaryClient | pascal }}Home,
+} as const;

package/templates/architectures/bff/files/src/downstream/config.ts

@@ -0,0 +1,35 @@
+/**
+ * Every downstream endpoint, timeout, and retry default resolves here. A BFF that names a host,
+ * a port, or a millisecond budget of its own has started drifting from its sibling.
+ */
+
+type Env = Record<string, string | undefined>;
+
+/** Read the host env without depending on @types/node — a BFF base may not ship them. */
+const hostEnv = (): Env => (globalThis as { process?: { env?: Env } }).process?.env ?? {};
+
+const text = (env: Env, name: string, fallback: string): string => env[name]?.trim() || fallback;
+
+const integer = (env: Env, name: string, fallback: number): number => {
+  const parsed = Number.parseInt(env[name] ?? '', 10);
+  return Number.isFinite(parsed) ? parsed : fallback;
+};
+
+export interface DownstreamConfig {
+  readonly profileBaseUrl: string;
+  readonly ordersBaseUrl: string;
+  readonly timeoutMs: number;
+  /** Extra attempts after the first, for 5xx and transport errors only. */
+  readonly retries: number;
+}
+
+export function loadDownstreamConfig(env: Env = hostEnv()): DownstreamConfig {
+  return {
+    profileBaseUrl: text(env, 'PROFILE_SERVICE_URL', 'http://localhost:4001'),
+    ordersBaseUrl: text(env, 'ORDERS_SERVICE_URL', 'http://localhost:4002'),
+    timeoutMs: integer(env, 'DOWNSTREAM_TIMEOUT_MS', 2000),
+    retries: integer(env, 'DOWNSTREAM_RETRIES', 1),
+  };
+}
+
+export const downstreamConfig: DownstreamConfig = loadDownstreamConfig();

package/templates/architectures/bff/files/src/downstream/http-client.ts

@@ -0,0 +1,41 @@
+import { type DownstreamConfig, downstreamConfig } from './config.js';
+
+export class DownstreamError extends Error {
+  // Fields assigned explicitly: parameter properties are not erasable syntax.
+  readonly status: number;
+  readonly url: string;
+
+  constructor(status: number, url: string) {
+    super(`Downstream ${url} failed with ${status}`);
+    this.name = 'DownstreamError';
+    this.status = status;
+    this.url = url;
+  }
+}
+
+/**
+ * One place where a downstream call gets its timeout, its retry, and its JSON decoding.
+ * Duplicating this per BFF is how two clients end up with different reliability behaviour.
+ */
+export async function getJson<T>(
+  baseUrl: string,
+  path: string,
+  config: DownstreamConfig = downstreamConfig,
+): Promise<T> {
+  const url = new URL(path, baseUrl).toString();
+  let last: unknown;
+
+  for (let attempt = 0; attempt <= config.retries; attempt += 1) {
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(config.timeoutMs) });
+      if (!response.ok) throw new DownstreamError(response.status, url);
+      return (await response.json()) as T;
+    } catch (error) {
+      // A 4xx is our bug, not a blip — retrying it just multiplies the latency we added.
+      if (error instanceof DownstreamError && error.status < 500) throw error;
+      last = error;
+    }
+  }
+
+  throw last;
+}

package/templates/architectures/bff/files/src/downstream/index.ts

@@ -0,0 +1,9 @@
+/**
+ * The only import surface a BFF may use. Deep imports into this folder are a boundary
+ * violation, so downstream clients stay refactorable without touching every client backend.
+ */
+
+export { type DownstreamConfig, downstreamConfig, loadDownstreamConfig } from './config.js';
+export { DownstreamError } from './http-client.js';
+export { fetchOrders, type OrderPage, type OrderRecord } from './orders-client.js';
+export { fetchProfile, type ProfileRecord } from './profile-client.js';

package/templates/architectures/bff/files/src/downstream/orders-client.ts

@@ -0,0 +1,23 @@
+import { downstreamConfig } from './config.js';
+import { getJson } from './http-client.js';
+
+/** The upstream service's shape. No BFF re-exports this — each maps it into its own DTO. */
+export interface OrderRecord {
+  readonly id: string;
+  readonly placedAt: string;
+  readonly status: string;
+  readonly totalMinorUnits: number;
+  readonly currency: string;
+  readonly lines: readonly { readonly sku: string; readonly quantity: number }[];
+}
+
+export interface OrderPage {
+  readonly orders: readonly OrderRecord[];
+  readonly total: number;
+}
+
+/** `limit` is the caller's, never this module's: each client decides how much it can render. */
+export function fetchOrders(userId: string, limit: number): Promise<OrderPage> {
+  const query = new URLSearchParams({ userId, limit: String(limit) });
+  return getJson<OrderPage>(downstreamConfig.ordersBaseUrl, `/orders?${query.toString()}`);
+}