DEV Community: FinClip Super-App

Design a Reusable Retail Mini App Without Sharing Brand Rules

FinClip Super-App — Mon, 14 Sep 2026 07:39:42 +0000

A multi-brand retailer wants one booking Mini App across two banners. Both services appear to follow the same user journey: choose a store, identify the member, select a time window, and receive a booking reference.

The tempting design is one shared UI connected to one “group” membership service and one booking backend. That design often centralizes data and rules that are not actually shared. Banner A and Banner B may use different CRM systems, price books, cancellation policies, store identifiers, and fulfillment workflows. A common screen does not make those dependencies common.

The safer target is smaller: reuse the stable interaction contract while keeping changeable brand decisions behind explicit ports. This article builds that boundary in TypeScript and shows how a Host App or Mini App runtime can carry brand context without becoming the source of retail truth.

The snippets are reference code for the architecture. They are not drop-in FinClip SDK calls and have not been executed against a production retailer.

** Start with the decisions that must remain local**

David Parnas’s information-hiding criterion is useful here: a module should conceal a design decision likely to change. For multi-brand retail, the likely changes are not the steps drawn in the journey map. They are the policies behind those steps.

Before defining a shared service, list the volatile decisions:

which CRM recognizes membership for each banner;
how stores are identified and whether franchise locations participate;
which system owns availability;
how prices, fees, taxes, and legal copy are calculated;
who can confirm, cancel, or reject a booking;
what happens when a banner leaves the shared service.

If the shared module knows those answers directly, it owns brand policy. If it asks a banner adapter through a stable contract, it owns orchestration.

** Make brand context explicit and immutable**

Do not infer the banner from a color theme, hostname, store-number prefix, or the first CRM record returned. The Host App should provide a signed, validated context when it opens the module.

export interface RetailContext {
  hostAppId: string;
  bannerId: string;
  storeId?: string;
  locale: string;
  currency: string;
  sessionId: string;
}

export interface HostAssertion {
  token: string;
  audience: "retail-booking";
  expiresAt: string;
}

export interface BootstrapRequest {
  context: RetailContext;
  assertion: HostAssertion;
}

Treat RetailContext as immutable for one service session. If the user switches banner or store, create a new context and repeat eligibility checks. Silent context mutation makes logs ambiguous and creates opportunities for a response from Banner A to be displayed under Banner B.

The assertion should be short-lived and audience-bound. The Mini App does not need the Host App’s refresh token or an unrestricted user profile. The backend validates the assertion and maps the subject to a banner-specific member identifier through the appropriate adapter.

Define the shared contract in retail language

Avoid a generic interface such as execute(action, payload). It hides nothing from callers because every new rule leaks into the payload. Define small ports using concepts that remain meaningful across banners.

export interface StorePort {
  search(input: {
    bannerId: string;
    query: string;
    service: "pickup";
  }): Promise<StoreSummary[]>;

  getServiceStatus(input: {
    bannerId: string;
    storeId: string;
    service: "pickup";
  }): Promise<"available" | "unavailable" | "temporarily_paused">;
}

export interface MembershipPort {
  resolve(input: {
    bannerId: string;
    hostSubject: string;
  }): Promise<MemberIdentity | null>;
}

export interface BookingPort {
  listWindows(input: WindowQuery): Promise<PickupWindow[]>;
  quote(input: BookingDraft): Promise<BrandQuote>;
  confirm(input: ConfirmRequest): Promise<BookingReceipt>;
  cancel(input: CancelRequest): Promise<CancellationReceipt>;
}

Notice what is absent. There is no shared points balance, tier table, price list, or store roster. The contract exposes the result the journey needs while allowing each adapter to obtain that result differently.

BrandQuote should return customer-facing price and policy text as data owned by the banner backend. The shared UI renders it but does not calculate it.

export interface BrandQuote {
  quoteId: string;
  amount: { value: string; currency: string };
  feeLines: Array<{ code: string; label: string; value: string }>;
  cancellationText: string;
  expiresAt: string;
}

This prevents a shared client release from being required when Banner B changes a fee label or cancellation rule. It also prevents Banner A’s copy from becoming the accidental group default.
**
Compose banner adapters at the edge**

The orchestration service should select adapters from validated banner context. Keep selection in one composition root rather than scattering if (bannerId === ...) branches through the workflow.

interface BannerServices {
  stores: StorePort;
  membership: MembershipPort;
  booking: BookingPort;
}

const servicesByBanner: Readonly<Record<string, BannerServices>> = {
  bannerA: {
    stores: new BannerAStoreAdapter(),
    membership: new BannerACrmAdapter(),
    booking: new BannerABookingAdapter(),
  },
  bannerB: {
    stores: new BannerBStoreAdapter(),
    membership: new BannerBCrmAdapter(),
    booking: new BannerBBookingAdapter(),
  },
};

export function servicesFor(bannerId: string): BannerServices {
  const services = servicesByBanner[bannerId];
  if (!services) throw new UnsupportedBannerError(bannerId);
  return services;
}

Each adapter is an anti-corruption layer. It maps a brand system’s identifiers, status codes, and retry behavior into the shared contract. Banner A may query a modern booking API. Banner B may call a legacy service and wait for store confirmation. The shared orchestration must not pretend these consistency models are identical.

For example, confirm() can return a receipt status of confirmed, pending_store, or rejected. The UI can support those states without exposing vendor-specific codes.

Keep Host App APIs narrow

A Mini App running inside an existing retail app may need Host-owned capabilities: the signed-in identity, the selected store, a native payment flow, or a route back to the Host App. Register these as named APIs with small request and response schemas.

type HostCapability =
  | "retail.context.read"
  | "identity.assertion.create"
  | "payment.checkout.open"
  | "host.navigation.return";

interface CapabilityPolicy {
  miniAppId: string;
  allowed: ReadonlySet<HostCapability>;
}

async function invokeHostApi(
  caller: { miniAppId: string; runId: string },
  capability: HostCapability,
  payload: unknown,
) {
  capabilityGuard.require(caller, capability);
  const input = schemas[capability].parse(payload);
  return handlers[capability](caller, input);
}

Authorize by Mini App identity and active run, not only by API name. Validate input on the Host side even if the Mini App already validates it. Return the smallest result required. A payment API should return a payment result or reference, not card details or a reusable credential.

If the Mini App contains an embedded H5 page, review its API surface separately. Do not assume that an API permitted to the Mini App logic layer should automatically be available to every WebView frame.

Orchestrate the booking without absorbing brand rules

The application service coordinates stable steps. It does not decide membership eligibility, pricing, or whether the store can honor the booking.

export async function prepareBooking(
  context: RetailContext,
  hostSubject: string,
  requestedWindow: string,
) {
  const services = servicesFor(context.bannerId);

  if (!context.storeId) throw new StoreRequiredError();

  const serviceStatus = await services.stores.getServiceStatus({
    bannerId: context.bannerId,
    storeId: context.storeId,
    service: "pickup",
  });
  if (serviceStatus !== "available") {
    return { status: serviceStatus } as const;
  }

  const member = await services.membership.resolve({
    bannerId: context.bannerId,
    hostSubject,
  });
  if (!member) return { status: "membership_not_found" } as const;

  const quote = await services.booking.quote({
    bannerId: context.bannerId,
    storeId: context.storeId,
    memberId: member.memberId,
    requestedWindow,
  });

  return { status: "ready", quote } as const;
}

The function asks the owning systems for decisions. It never checks a local bannerBFees.json, assumes that every member has a group ID, or labels a request confirmed before the store system returns a receipt.

Keep quote and confirm separate. Send quoteId back during confirmation so the banner backend can reject an expired or altered quote. Use an idempotency key for confirmation and cancellation. Mobile retries, network changes, and repeated taps must not create duplicate store work.

Contract-test every banner against the shared behavior

Reuse is credible only when each adapter satisfies the same observable contract. Write one test suite and run it against every banner implementation.

export function bookingContract(
  name: string,
  create: () => Promise<BookingPort>,
) {
  describe(`${name} booking adapter`, () => {
    it("returns banner-owned price and policy copy", async () => {
      const port = await create();
      const quote = await port.quote(validDraft());
      expect(quote.quoteId).toBeTruthy();
      expect(quote.amount.currency).toMatch(/^[A-Z]{3}$/);
      expect(quote.cancellationText.length).toBeGreaterThan(0);
    });

    it("makes confirmation idempotent", async () => {
      const port = await create();
      const request = validConfirmRequest({ idempotencyKey: "same-key" });
      const first = await port.confirm(request);
      const second = await port.confirm(request);
      expect(second.reference).toBe(first.reference);
    });
  });
}

Add adapter-specific tests for legacy quirks, but do not weaken the shared contract silently. If Banner B cannot provide immediate confirmation, model pending_store explicitly and update the user journey. A type that lies about certainty is worse than a type with one more state.

Consumer-driven contract tests can also protect the Host App API. Pin request and response schemas by version. Reject a Mini App package that asks for an undeclared capability or breaks the current contract.

Choose a deployment shape that preserves exit paths

One codebase does not require one deployed package. Three common shapes are valid:

One Mini App package receives bannerId and uses brand adapters behind a backend gateway.
Each banner deploys a separate Mini App package built from shared components.
A shared shell opens smaller banner-specific modules.

Choose based on release ownership, legal separation, outage containment, and how independently the brands change. If Banner B must release or withdraw without Banner A, a separate package may be safer even when most source code is shared.

Record package ID, Host App ID, banner ID, contract version, and backend environment in every launch event. Never derive production routing from visual branding.

The release process should prove four operations before launch: promote a tested package, refuse an incompatible contract version, roll back to a known package, and disable one banner without disabling the others.

Observe boundary failures, not only conversion

Business analytics will track searches, selected windows, and completed bookings. Architecture telemetry should answer different questions:

Did a Host App provide an unknown banner or store?
Which adapter timed out or returned an unmapped status?
Did the Mini App request an undeclared Host capability?
Did quote currency match the banner context?
Did a confirmation retry return the same reference?
Could operations disable one banner and leave the other available?

Include correlation IDs across Host App, Mini App, gateway, adapter, and banner backend. Redact assertions, membership identifiers, and customer data. A shared module should make ownership clearer during an incident, not create a group log containing every banner’s sensitive payloads.

Where FinClip fits

FinClip provides a Mini App runtime and management capabilities that can support modular services inside an existing or purpose-built Host App. Its documentation describes Host-side custom APIs and the association of Mini Apps with applications. Those mechanisms can carry a validated context, expose narrow native capabilities, and manage module availability.

They do not merge CRM, pricing, inventory, POS, or fulfillment. The retailer still designs the shared contract, builds the adapters, defines package ownership, and operates each brand’s backend. SDK integration is also a native Host App change; later Mini App updates do not remove the need to govern new custom APIs or SDK upgrades.

That boundary is the implementation lesson. Reuse the interface that remains stable across the retail family. Hide the brand decisions behind adapters owned by the systems that can answer them. A shared booking door is useful. A fictional group CRM is not.

How Should a Social App Choose Its First Mini Game and Validation Scope?

FinClip Super-App — Fri, 11 Sep 2026 09:15:49 +0000

Adding a mini-game runtime to a social app is an integration task. Operating the first game safely is a systems-design task.

A runtime may let the Host App open a Mini Game package, expose native capabilities, and update that package independently from the Host App binary. None of those mechanisms answers the questions that decide whether the first launch is controllable:

Which existing surface is allowed to start the game?
Which version is allowed to run?
Which Host APIs can that package call?
What happens when a message, call, or moderation action interrupts play?
Who can withdraw the game without waiting for an app-store release?
Which measured conditions keep the experiment online?

This article turns those questions into a small control plane around one game. The examples use framework-neutral TypeScript-style code. They illustrate the Host-side policy layer; they are not drop-in bindings for a particular Mini App SDK.

Start with a bounded deployment, not a game catalog

The first game should prove that the Host App can admit, observe, interrupt, update, and remove a partner module. It should not prove that the company can display a catalog.

Define one entry point, one session expectation, and one release channel. A useful initial scope might be a turn-based party game opened from a group thread. A user plays one turn and returns to chat. That scope is easier to reason about than a new game lobby with multiple studios, virtual goods, voice chat, and ten-minute matches.

The architecture should encode the boundary. Do not leave it in a launch deck.

type Surface = "group_thread" | "profile" | "game_lobby";
type ReleaseChannel = "trial" | "review" | "production";

interface GameLaunchPolicy {
  appId: string;
  allowedVersion: string;
  allowedSurfaces: ReadonlySet<Surface>;
  releaseChannel: ReleaseChannel;
  maxForegroundSeconds: number;
  allowedCapabilities: ReadonlySet<HostCapability>;
  enabled: boolean;
}

type HostCapability =
  | "identity.assertion.create"
  | "social.thread.summary.read"
  | "host.navigation.return"
  | "moderation.report.create";

The manifest deliberately excludes broad permissions such as “read profile,” “access storage,” or “use native bridge.” Capabilities should describe one operation and one data shape. The allowlist should be bound to the Mini Game identity and version, not only to a URL or JavaScript method name.

Put a launch gateway in front of the runtime

The UI should never call the runtime directly. It should ask a Host-owned launch gateway to evaluate context and policy first.

interface LaunchRequest {
  appId: string;
  requestedVersion: string;
  surface: Surface;
  threadId?: string;
  userId: string;
}

type LaunchDecision =
  | { ok: true; sessionId: string; expiresAt: number }
  | { ok: false; reason: string };

function authorizeLaunch(
  request: LaunchRequest,
  policy: GameLaunchPolicy,
  now: number,
): LaunchDecision {
  if (!policy.enabled) return { ok: false, reason: "game_disabled" };
  if (request.appId !== policy.appId) {
    return { ok: false, reason: "unapproved_app" };
  }
  if (request.requestedVersion !== policy.allowedVersion) {
    return { ok: false, reason: "unapproved_version" };
  }
  if (!policy.allowedSurfaces.has(request.surface)) {
    return { ok: false, reason: "unapproved_surface" };
  }
  if (request.surface === "group_thread" && !request.threadId) {
    return { ok: false, reason: "missing_thread_context" };
  }

  return {
    ok: true,
    sessionId: crypto.randomUUID(),
    expiresAt: now + policy.maxForegroundSeconds * 1000,
  };
}

This gateway gives the Host App a single place to enforce a kill switch, version pin, allowed surface, and session budget. It also produces stable refusal reasons for monitoring. A vague “failed to open” event is difficult to operate; unapproved_version tells the release team what changed.

After authorization, pass only the minimum bootstrap context to the runtime. Do not send the full user profile, refresh token, thread history, or moderation state as launch parameters. The Mini Game should request a narrowly scoped capability when it actually needs one.

Mint a task-specific identity assertion

Partner code may need to recognize the current player. It rarely needs the Host App’s primary session credential.

Use a short-lived assertion with an audience, purpose, and expiration. The Host backend should mint it; the Host App should never copy its own refresh token into the Mini Game.

interface IdentityAssertionRequest {
  appId: string;
  sessionId: string;
  purpose: "join_game_session";
}

interface IdentityAssertion {
  token: string;
  audience: string;
  expiresAt: number;
}

async function createGameAssertion(
  request: IdentityAssertionRequest,
  actor: AuthenticatedHostUser,
): Promise<IdentityAssertion> {
  await capabilityGuard.require({
    appId: request.appId,
    sessionId: request.sessionId,
    capability: "identity.assertion.create",
  });

  return hostBackend.mintAssertion({
    subject: actor.stablePseudonymousId,
    audience: request.appId,
    purpose: request.purpose,
    ttlSeconds: 120,
  });
}

The partner receives a pseudonymous subject for this integration, not necessarily the social account’s public identifier. The backend validates the assertion audience and purpose before creating a game session. A token replayed by another Mini Game or used for another operation should fail.

Treat every custom API as a security boundary. Validate the caller identity, active session, capability, input schema, and user consent before invoking native or backend behavior. Log the decision, but never log the assertion itself.

Separate Mini Game APIs from embedded H5 APIs

Many Mini App runtimes can also load H5 pages. That does not mean an API approved for the Mini Game should automatically be exposed to an H5 frame.

Maintain separate registries:

const miniGameApis: ApiRegistry = {
  "identity.assertion.create": createGameAssertion,
  "host.navigation.return": returnToHost,
  "moderation.report.create": createModerationReport,
};

const embeddedH5Apis: ApiRegistry = {
  "host.navigation.return": returnToHost,
};

The smaller H5 registry is intentional. Web content has different origin, navigation, cookie, and frame risks. If a studio needs an H5 page for terms or support, open it with a narrowly scoped URL allowlist and no inherited game credential. If it needs additional Host access, review that access as a new integration path.

Make interruption a first-class lifecycle event

A social app has priorities that a game does not control. Incoming calls, direct messages, moderation notices, audio sessions, account lockouts, and app backgrounding can all interrupt play.

The Host App should publish lifecycle events and enforce the outcome when the game does not cooperate.

type HostInterrupt =
  | { type: "message_opened"; threadId: string }
  | { type: "voice_session_started" }
  | { type: "account_restricted" }
  | { type: "session_budget_exceeded" };

async function handleInterrupt(
  event: HostInterrupt,
  running: RunningGame,
): Promise<void> {
  await running.notify("host.interrupt", event);

  const acknowledged = await running.waitForAck({ timeoutMs: 500 });
  if (!acknowledged || event.type === "account_restricted") {
    await running.close({ preservePartnerState: false });
  }

  hostNavigation.restorePreviousSurface();
}

The 500-millisecond value is an example engineering decision, not a performance claim or universal benchmark. Choose it from product requirements and test it on the supported device range. The key behavior is deterministic: the Host App owns the foreground, can close the module, and can restore the user’s previous social context.

Define what happens to unsaved game state. A casual turn might be safely retried. A competitive action may require a server-issued idempotency key and a reconciliation flow. Do not ask the client to decide whether a wager, score, or virtual item was committed.

Model release and withdrawal as a state machine

Publishing should be a controlled transition, not “upload the latest package.” A minimal state machine is enough for the first integration.

states:
  - draft
  - trial
  - review
  - production
  - suspended
  - withdrawn

transitions:
  draft_to_trial:
    requires: [studio_signature, malware_scan, dependency_manifest]
  trial_to_review:
    requires: [host_qa, api_contract_test, moderation_runbook]
  review_to_production:
    requires: [product_owner, security_owner, operations_owner]
  production_to_suspended:
    requires_any: [kill_switch, incident_policy]
  suspended_to_withdrawn:
    requires: [partner_notification, customer_support_notice]

Bind the production policy to an immutable package version or digest. If the platform uses channels such as trial, review, and production, record the channel and package identity in the launch event. A rollback should move the allowlist to a previously approved package. A withdrawal should disable new launches immediately and define how to close active sessions.

Test both operations before launch. Teams often test the happy path repeatedly and discover during an incident that the person with console access is unavailable or that removing a tile does not close a running module.

Instrument the questions that decide whether the game stays

Do not begin with a dashboard full of generic engagement metrics. Instrument the integration promises.

interface GameHostEvent {
  event:
    | "launch_allowed"
    | "launch_refused"
    | "session_started"
    | "host_interrupted"
    | "return_to_host"
    | "api_allowed"
    | "api_refused"
    | "package_withdrawn";
  appId: string;
  packageVersion: string;
  sessionId: string;
  surface: Surface;
  reason?: string;
  occurredAt: string;
}

From these events, the team can answer operational questions:

Do users return to the originating thread after a session?
Does the game exceed the intended foreground budget?
Which API requests are refused, and are they bugs or unauthorized behavior?
Can operations suspend launches and observe the effect?
Does a new package increase crashes, refusal rates, or failed returns?

Keep business thresholds in a versioned experiment specification. For example, the product owner may require that the return-to-host path remains reliable, moderation reports reach an owned queue, and the package can be suspended within the incident procedure. Those are explicit acceptance conditions. They should not be replaced by invented retention targets from another app.

Map the design to a Mini App platform

FinClip’s current Android documentation states that Mini Programs, Mini Games, and H5 applications share the same SDK initialization path. Its Mini-Program management APIs cover opening and closing supported module types and distinguish release contexts such as trial, review, and official versions. Its custom API documentation provides a way for a Host App to register capabilities that the runtime does not provide.

Those mechanisms map to three parts of this design:

The runtime opens the approved Mini Game package.
The custom API layer carries narrow Host capabilities.
The management platform controls package lifecycle and availability.

The Host App still needs the launch gateway, capability policy, token service, interruption behavior, telemetry, and operational ownership described above. The platform hosts and manages the module; it does not choose the game studio, define community rules, run moderation, settle partner payments, or decide the experiment threshold.

Mini Games are also a distinct project type. FinClip’s published development guide describes game.js and game.json as required root files and notes a minimum base-library level for Mini Game support. Treat that version statement as something to recheck against the target SDK and studio export pipeline before commitment. Engine compatibility, package limits, audio behavior, and device performance should be validated with a pinned version and representative devices.

A pre-launch test plan for the first game

Run these tests before adding a second studio:

Launch the approved package from the approved group-thread surface.
Refuse the same package from an unapproved surface.
Refuse an unapproved package version.
Request each Host capability with the correct and incorrect Mini Game identity.
Verify that expired identity assertions fail at the partner backend.
Load an embedded H5 page and confirm it cannot call Mini Game-only APIs.
Interrupt play with a message, audio session, app background event, and account restriction.
Restore the originating social surface without losing Host App navigation state.
Promote a trial package, reject a review package, roll back production, and activate the kill switch.
Confirm that withdrawal blocks new sessions and handles active sessions according to the runbook.
Verify that logs contain decisions and package identity but no tokens or sensitive content.
Rehearse the incident path with the actual weekend operator.

A first Mini Game is successful when the integration remains bounded under failure, interruption, update, and withdrawal. If the team cannot state which package may enter, which APIs it may call, how long it may hold the foreground, and who can remove it, adding a catalog only multiplies undefined behavior.

Ship one controlled room inside the social app. Prove the Host App still owns the door.

Building an In-App Rescheduling Flow That Actually Confirms the Change

FinClip Super-App — Tue, 08 Sep 2026 05:48:54 +0000

A customer has a broadband installation booked for Friday morning. On Thursday, a work meeting moves into the same time slot. They open the provider's app, find their order, and look for a way to change the visit.

The appointment is there. So is a telephone number.

It is a small gap from the customer's perspective. The company already knows the address, the booking, and the service being installed. Asking someone to explain all of that again feels unnecessary, particularly when the call has to fit into a working day.

For the developer, adding a date picker is probably the easiest part. The harder question arrives after the customer taps Saturday morning: has the installation actually moved? What happens to Friday if Saturday fills up? If the connection drops, which appointment should the customer plan around?

Let's work through this hypothetical service. The goal is an understandable result, with a sensible way to get help when the system cannot complete the change. A team could build this journey into an existing app as a native feature or a mini app; the scheduling responsibilities remain much the same.

Give the confirmation screen something reliable to say

Before choosing UI components, agree with the scheduling team on what each response means. A request can arrive successfully while the installation remains unchanged. An HTTP success response from an intermediary may only acknowledge receipt.

For asynchronous work, 202 Accepted means processing has been accepted and may still fail. It does not establish that the business action succeeded. That distinction is explicit in MDN's explanation of 202 Accepted.

Here is the small vocabulary used in this example:

State	What is known	What the customer should see
`received`	The service recorded the request; no replacement is confirmed.	“We've received your request to move the visit.”
`processing`	The change is underway, or its outcome is being checked.	“We're checking the appointment change. You don't need to submit it again.”
`confirmed`	The scheduling system committed the replacement.	The confirmed date and time, with the updated booking reference.
`unavailable`	The requested slot was rejected without changing the booking.	“That time is no longer available. Your existing appointment is unchanged.”
`needs_support`	The automated path encountered an exception that requires follow-up.	A specific explanation and a route to someone who can continue the request.

The wording can be warmer than these examples. Its certainty should match the evidence. A green tick beside “Request received” can easily look like a completed change, especially to someone glancing at the screen between meetings.

On the selection screen, keep Friday visible while the customer looks at alternatives. Before submission, show the old appointment and the requested replacement together. If changing the visit carries a fee or affects another service, surface that condition before the final tap, using information from the relevant backend. A customer should not have to infer whether selecting Saturday has already cancelled Friday. Clear button labels and a short explanation can remove that uncertainty without adding another tutorial.

Available times also need to come from the scheduling service. The displayed list can become stale before submission, so the backend checks availability again when committing the change. Show the installation location's time zone when there is room for ambiguity.

Keep authority behind the screen

The request body needs an appointment identifier, the requested slot, and an idempotency key. The authenticated customer identity comes from trusted server middleware. A browser or mini app sending userId: "customer-1" does not establish ownership.

The service checks that the authenticated customer owns the appointment before creating a change request. Reading the outcome needs authorization too; knowing a request identifier should not reveal another person's booking.

There is a second boundary underneath that check. The scheduling adapter must support a safe replacement: validate the booking and slot, commit the new reservation, and release the old one together. Until replacement succeeds, the original reservation remains intact. A separate “cancel Friday” call followed by “book Saturday” can leave the customer without either appointment.

Some scheduling systems offer the required transaction. Others need reservation holds, a carefully designed recovery process, or an assisted workflow. If the available API only supports cancellation and fresh booking, this demo does not make that limitation disappear. Establish the backend contract before promising instant rescheduling.

The following runnable example uses an in-memory scheduler to model that contract. It deliberately contains no FinClip SDK calls. Its synchronous update represents a scheduling transaction; JavaScript maps do not provide atomicity across remote services.

Save the three JavaScript blocks below, in order, into one .mjs file. The test data contains synthetic identifiers and time-slot labels.

import assert from 'node:assert/strict';
import { randomUUID } from 'node:crypto';

class DemoScheduler {
  appointments = new Map([
    ['visit-1', { owner: 'customer-1', slot: 'fri-am', version: 1 }],
    ['visit-2', { owner: 'customer-1', slot: 'fri-pm', version: 1 }],
  ]);
  slots = new Set(['sat-am', 'sat-pm']);
  outcomes = new Map();
  calls = 0;
  loseNextReply = false;

  getAppointment(id) {
    return structuredClone(this.appointments.get(id));
  }

  async replace(op) {
    this.calls++;
    if (this.outcomes.has(op.id)) return this.lookupOutcome(op.id);
    const current = this.appointments.get(op.appointmentId);
    let result;
    if (!current || current.owner !== op.subject ||
        current.version !== op.expectedVersion) {
      result = { status: 'needs_support', reason: 'appointment_changed' };
    } else if (!this.slots.has(op.slot)) {
      result = { status: 'unavailable', reason: 'slot_taken' };
    } else {
      // A real scheduling backend must implement this transaction.
      this.slots.delete(op.slot);
      this.slots.add(current.slot);
      const updated = { ...current, slot: op.slot, version: current.version + 1 };
      this.appointments.set(op.appointmentId, updated);
      result = { status: 'confirmed', slot: updated.slot };
    }
    this.outcomes.set(op.id, result);
    if (this.loseNextReply) {
      this.loseNextReply = false;
      throw new Error('Response lost; outcome is unknown to the caller');
    }
    return structuredClone(result);
  }

  async lookupOutcome(id) {
    return structuredClone(this.outcomes.get(id));
  }
}

The version check catches two changes created against the same appointment. Once one succeeds, the other cannot quietly overwrite it. In this small example, that conflict goes to needs_support; a real service may be able to refresh the booking and let the customer choose again.

Make a second tap return the same request

A customer may tap twice, reopen the app, or resend after a slow response. The endpoint has to recognize which business action those attempts belong to. POST does not provide idempotency by default, as the MDN method reference notes.

Here, the key is scoped to the authenticated customer and bound to the appointment and requested slot. Repeating the same request returns its existing result. Reusing its key for a different appointment or time is rejected. A genuinely new choice receives a new key.

The public submission method and the internal processing method are separate so that receipt cannot accidentally be presented as completion. In production, recording the request and arranging durable processing also need a reliable transactional design.

function createRescheduler(scheduler) {
  const requests = new Map();
  const keys = new Map();
  const view = op => ({ id: op.id, status: op.status, ...op.result });

  function requireSubject(session) {
    if (!session?.subject) throw new Error('Unauthenticated');
    return session.subject;
  }

  function ownedRequest(session, id) {
    const subject = requireSubject(session);
    const op = requests.get(id);
    if (!op || op.subject !== subject) throw new Error('Access denied');
    return op;
  }

  return {
    submit(session, { appointmentId, slot, key }) {
      const subject = requireSubject(session);
      for (const value of [appointmentId, slot, key]) {
        if (typeof value !== 'string' || !value.length || value.length > 128) {
          throw new Error('Invalid request');
        }
      }
      const current = scheduler.getAppointment(appointmentId);
      if (!current || current.owner !== subject) throw new Error('Access denied');
      const scope = JSON.stringify([subject, key]);
      const fingerprint = JSON.stringify([appointmentId, slot]);
      const previous = keys.get(scope);
      if (previous) {
        if (previous.fingerprint !== fingerprint) throw new Error('Key reused');
        return view(requests.get(previous.id));
      }
      const op = {
        id: randomUUID(), subject, appointmentId, slot,
        expectedVersion: current.version, status: 'received',
      };
      requests.set(op.id, op);
      keys.set(scope, { id: op.id, fingerprint });
      return view(op);
    },

    // Internal worker entry point, not a public unauthenticated endpoint.
    async process(id) {
      const op = requests.get(id);
      if (!op) throw new Error('Unknown request');
      if (op.status !== 'received') return view(op);
      op.status = 'processing';
      try {
        op.result = await scheduler.replace(op);
        op.status = op.result.status;
      } catch {
        // The backend may already have committed. Query its outcome.
      }
      return view(op);
    },

    async refresh(session, id) {
      const op = ownedRequest(session, id);
      if (op.status === 'processing') {
        const result = await scheduler.lookupOutcome(id);
        if (result) {
          op.result = result;
          op.status = result.status;
        }
      }
      return view(op);
    },
  };
}

Notice the restrained behavior after an exception. A lost reply can happen after Saturday has already been booked. The operation stays processing until a lookup establishes its outcome. The UI should not announce failure, promise that Friday still applies, or start another replacement based only on a timeout.

An unresolved lookup also needs an operational limit. Define when a support queue takes ownership, how the customer receives an update, and who can reconcile the booking. This demo leaves unknown outcomes pending; it does not implement that queue or a background retry worker.

Test the awkward moments before polishing the calendar

These checks use Node's strict assertion module. They cover authorization, a confirmed change, duplicate requests, changed payloads, an unavailable slot, a lost response, and competing changes.

const customer = { subject: 'customer-1' }; // Trusted session in production.
const stranger = { subject: 'customer-2' };
const input = { appointmentId: 'visit-1', slot: 'sat-am', key: 'tap-1' };
const fresh = () => {
  const scheduler = new DemoScheduler();
  return { scheduler, service: createRescheduler(scheduler) };
};

{
  const { scheduler, service } = fresh();
  const before = scheduler.getAppointment('visit-1');
  assert.throws(() => service.submit(stranger, input), /Access denied/);
  assert.throws(() => service.submit(null, input), /Unauthenticated/);
  assert.deepEqual(scheduler.getAppointment('visit-1'), before);
  assert.equal(scheduler.calls, 0);
}
{
  const { scheduler, service } = fresh();
  const accepted = service.submit(customer, input);
  assert.equal(accepted.status, 'received');
  assert.equal(scheduler.getAppointment('visit-1').slot, 'fri-am');
  assert.equal((await service.process(accepted.id)).status, 'confirmed');
  assert.equal(scheduler.getAppointment('visit-1').slot, 'sat-am');
  assert.equal(service.submit(customer, input).id, accepted.id);
  await service.process(accepted.id);
  assert.equal(scheduler.calls, 1);
  assert.throws(() => service.submit(customer, { ...input, slot: 'sat-pm' }), /Key reused/);
  assert.throws(() => service.submit(customer, { ...input, appointmentId: 'visit-2' }), /Key reused/);
  await assert.rejects(service.refresh(stranger, accepted.id), /Access denied/);
}
{
  const { scheduler, service } = fresh();
  const before = scheduler.getAppointment('visit-1');
  const accepted = service.submit(customer, { ...input, slot: 'sold-out' });
  assert.equal((await service.process(accepted.id)).status, 'unavailable');
  assert.deepEqual(scheduler.getAppointment('visit-1'), before);
}
{
  const { scheduler, service } = fresh();
  scheduler.loseNextReply = true;
  const accepted = service.submit(customer, input);
  assert.equal((await service.process(accepted.id)).status, 'processing');
  assert.equal(service.submit(customer, input).status, 'processing');
  assert.equal((await service.refresh(customer, accepted.id)).status, 'confirmed');
  assert.equal(scheduler.calls, 1);
  assert.equal(scheduler.getAppointment('visit-1').slot, 'sat-am');
}
{
  const { scheduler, service } = fresh();
  const first = service.submit(customer, input);
  const second = service.submit(customer, { ...input, slot: 'sat-pm', key: 'tap-2' });
  assert.equal((await service.process(first.id)).status, 'confirmed');
  assert.equal((await service.process(second.id)).status, 'needs_support');
  assert.equal(scheduler.getAppointment('visit-1').slot, 'sat-am');
}
console.log('All rescheduling checks passed.');

Run the saved file with Node.js. Passing these checks verifies the demonstration's behavior. It says nothing about the transaction guarantees of a provider's real scheduling API.

Every map here disappears on restart and is private to one process. Production needs persistent requests, durable idempotency records, safe worker coordination, and defined retention. Real booking eligibility can include service areas, engineer skills, notice periods, and access requirements. Those rules belong with authoritative scheduling data. Authentication middleware, transport security, rate limits, and an actual HTTP interface are outside this sample.

Leave the customer with a usable next step

When an exception needs a person, carry forward the request reference, the permitted booking context, the requested time, and the last verified result. Explain what is being shared. Support should be able to retrieve that context through an authorized system instead of asking the customer to start again.

Avoid putting addresses, telephone numbers, tokens, or free-text customer notes into routine diagnostic logs. An opaque operation identifier and a status code can help correlate events, with appropriate access controls and retention. The demonstration prints only its test result.

The existing app still needs an entry point customers can find. “Manage installation” beside the appointment is a plausible starting place. After confirmation, refresh the booking summary so the old date does not remain elsewhere on screen. If push or email confirmation is provided, derive it from the committed result and handle notification failure separately from booking failure.

Test that screen with someone unfamiliar with the implementation. Ask which appointment they believe they currently have and whether they think another action is required. Hesitation often points to wording or stale information that a successful API test will miss. Include a slow connection in the exercise; that is when reassuring but premature messages tend to cause trouble.

For teams considering mini apps, this is a concrete service to evaluate. FinClip's introduction describes integrating its runtime SDK into a host application so that the app can run mini programs. That can provide a place to deliver the rescheduling interface within an existing app. The runtime does not supply installation availability, customer authorization, or the scheduling transaction described here; those need working connections to the business systems.

Before expanding further, observe whether customers finish this particular journey. Separate successful changes from unavailable slots, unresolved requests, and voluntary choices to contact support. A lower call count alone can hide people who gave up.

For the person rearranging Friday morning, a useful ending is modest: Saturday is confirmed, the app agrees, and there is no need to call just to check.

Enforce Mobile Delivery Boundaries with TypeScript

FinClip Super-App — Mon, 07 Sep 2026 07:14:30 +0000

Modular mobile architecture is easy to describe in a diagram and surprisingly easy to erode in production.

A service begins with two approved host capabilities, then adds direct profile access for convenience. A supposedly independent module cannot launch unless another module has already loaded. A low-risk campaign starts initiating payments through an interface that was never designed for transaction assurance. The repository still contains separate folders, but the operating boundary has disappeared.

This article models three delivery zones in TypeScript:

native: high-consequence capabilities owned by the host application;
modular: bounded services delivered through a controlled runtime;
external: web or separate-app journeys reached through an approved handoff.

The goal is not to make an algorithm decide architecture. The goal is to turn assumptions into reviewable data and reject configurations that violate known boundaries.

Define the delivery vocabulary

Start with a small set of terms shared by product, mobile, security, and platform teams.

export type DeliveryZone = "native" | "modular" | "external";

export type Consequence = "low" | "moderate" | "high" | "critical";

export type Lifecycle =
  | "experimental"
  | "seasonal"
  | "persistent"
  | "retiring";

export type HostCapability =
  | "identity.basic"
  | "identity.strong_auth"
  | "payments.initiate"
  | "payments.confirm"
  | "files.select"
  | "camera.capture"
  | "location.approximate"
  | "notifications.request"
  | "analytics.event";

Keep capabilities task-oriented. A capability named user.everything or native.bridge hides the authority being granted. Narrow names improve review, logging, and later deprecation.

The list should represent what the host is willing to support as a product. An interface that exists only for one module may be a valid exception, but it should not silently become part of the general platform contract.

Describe each customer service

A service record should contain enough information to discuss its boundary without reading implementation code.

export type ServiceDefinition = {
  id: string;
  displayName: string;
  owner: string;
  zone: DeliveryZone;
  consequence: Consequence;
  lifecycle: Lifecycle;
  customerTask: string;
  audience: {
    markets: string[];
    estimatedReachPercent: number;
  };
  capabilities: HostCapability[];
  dependencies: string[];
  independentlySuspendable: boolean;
  fallback?: {
    kind: "native_route" | "https_url";
    destination: string;
  };
};

The customerTask is important. It should describe a coherent outcome such as “book a branch appointment” or “submit eligibility documents.” A technical fragment such as “render offer banner” may belong inside another service rather than becoming its own independently operated module.

The owner must resolve to a maintained team or service identity. A person’s email address is likely to become stale. Connect ownership to the organisation’s current service catalogue and escalation system.

Create explicit zone policy

Policy should describe the normal boundaries. Exceptions can then be identified and reviewed deliberately.

type ZonePolicy = {
  allowedCapabilities: ReadonlySet<HostCapability>;
  maximumConsequence: Consequence;
  requireFallback: boolean;
  requireIndependentSuspension: boolean;
  maximumReachPercent?: number;
};

const consequenceRank: Record<Consequence, number> = {
  low: 0,
  moderate: 1,
  high: 2,
  critical: 3,
};

export const zonePolicies: Record<DeliveryZone, ZonePolicy> = {
  native: {
    allowedCapabilities: new Set<HostCapability>([
      "identity.basic",
      "identity.strong_auth",
      "payments.initiate",
      "payments.confirm",
      "files.select",
      "camera.capture",
      "location.approximate",
      "notifications.request",
      "analytics.event",
    ]),
    maximumConsequence: "critical",
    requireFallback: false,
    requireIndependentSuspension: false,
  },
  modular: {
    allowedCapabilities: new Set<HostCapability>([
      "identity.basic",
      "payments.initiate",
      "files.select",
      "camera.capture",
      "location.approximate",
      "notifications.request",
      "analytics.event",
    ]),
    maximumConsequence: "high",
    requireFallback: true,
    requireIndependentSuspension: true,
  },
  external: {
    allowedCapabilities: new Set<HostCapability>([
      "analytics.event",
    ]),
    maximumConsequence: "high",
    requireFallback: false,
    requireIndependentSuspension: false,
  },
};

This example keeps strong authentication and payment confirmation inside the native zone. A modular service may request a host-controlled payment initiation, while the host owns the final confirmation surface. Your policy will depend on industry, architecture, distribution rules, and threat model.

Avoid treating maximumConsequence as a complete risk decision. A high-consequence modular service may be acceptable with stronger controls, or policy may prohibit it entirely. The field makes the assumption visible so reviewers can challenge it.

Return findings instead of one score

Architecture decisions do not reduce well to a single number. A validator should return specific findings with severity and evidence.

export type Finding = {
  code: string;
  severity: "warning" | "error";
  message: string;
};

export function validateService(
  service: ServiceDefinition,
  allServices: ReadonlyMap<string, ServiceDefinition>,
): Finding[] {
  const findings: Finding[] = [];
  const policy = zonePolicies[service.zone];

  if (!service.owner.trim()) {
    findings.push({
      code: "OWNER_MISSING",
      severity: "error",
      message: "The service needs an accountable owner.",
    });
  }

  if (!service.customerTask.trim()) {
    findings.push({
      code: "TASK_MISSING",
      severity: "error",
      message: "Describe the complete customer task.",
    });
  }

  if (
    consequenceRank[service.consequence] >
    consequenceRank[policy.maximumConsequence]
  ) {
    findings.push({
      code: "CONSEQUENCE_EXCEEDS_ZONE",
      severity: "error",
      message: `${service.consequence} consequence exceeds ${service.zone} policy.`,
    });
  }

  for (const capability of service.capabilities) {
    if (!policy.allowedCapabilities.has(capability)) {
      findings.push({
        code: "CAPABILITY_NOT_ALLOWED",
        severity: "error",
        message: `${capability} is not allowed in the ${service.zone} zone.`,
      });
    }
  }

  if (policy.requireFallback && !service.fallback) {
    findings.push({
      code: "FALLBACK_REQUIRED",
      severity: "error",
      message: "This delivery zone requires a maintained fallback.",
    });
  }

  if (
    policy.requireIndependentSuspension &&
    !service.independentlySuspendable
  ) {
    findings.push({
      code: "SUSPENSION_REQUIRED",
      severity: "error",
      message: "The service must be independently suspendable.",
    });
  }

  if (
    policy.maximumReachPercent !== undefined &&
    service.audience.estimatedReachPercent > policy.maximumReachPercent
  ) {
    findings.push({
      code: "REACH_REVIEW_REQUIRED",
      severity: "warning",
      message: "Expected customer reach exceeds normal zone policy.",
    });
  }

  for (const dependencyId of service.dependencies) {
    if (!allServices.has(dependencyId)) {
      findings.push({
        code: "DEPENDENCY_UNKNOWN",
        severity: "error",
        message: `Unknown dependency: ${dependencyId}`,
      });
    }
  }

  return findings;
}

Run this validation when a definition is proposed, when capabilities change, and before publication. A service that passed review six months ago should not retain approval after its consequence, reach, or dependencies have materially changed.

Detect dependency cycles

Independent services should not form a hidden release cluster. A cycle such as rewards → profile → offers → rewards is a signal that boundaries or interfaces need review.

export function findDependencyCycles(
  services: ReadonlyMap<string, ServiceDefinition>,
): string[][] {
  const visiting = new Set<string>();
  const visited = new Set<string>();
  const path: string[] = [];
  const cycles: string[][] = [];

  function visit(id: string): void {
    if (visiting.has(id)) {
      const start = path.indexOf(id);
      cycles.push([...path.slice(start), id]);
      return;
    }

    if (visited.has(id)) return;

    visiting.add(id);
    path.push(id);

    for (const dependency of services.get(id)?.dependencies ?? []) {
      if (services.has(dependency)) visit(dependency);
    }

    path.pop();
    visiting.delete(id);
    visited.add(id);
  }

  for (const id of services.keys()) visit(id);
  return cycles;
}

A dependency is not always wrong. The question is whether it uses a stable, owned contract and whether the dependent service has a defined response when the dependency is unavailable.

Do not let modules call one another through private runtime handles. Route service-to-service interactions through reviewed host capabilities or backend APIs with authentication, timeouts, observability, and failure behaviour.

Validate a real definition

Here is a bounded appointment service:

export const appointments: ServiceDefinition = {
  id: "support.appointments",
  displayName: "Branch appointments",
  owner: "customer-operations",
  zone: "modular",
  consequence: "moderate",
  lifecycle: "persistent",
  customerTask: "Book, change, or cancel a branch appointment",
  audience: {
    markets: ["GB", "SG"],
    estimatedReachPercent: 18,
  },
  capabilities: ["identity.basic", "analytics.event"],
  dependencies: [],
  independentlySuspendable: true,
  fallback: {
    kind: "https_url",
    destination: "https://services.example.com/appointments",
  },
};

The definition is understandable to more than the runtime team. Product can review the customer task and reach. Security can inspect capabilities and consequence. Operations can check ownership, suspension, and fallback. Mobile engineers can map the zone to the correct renderer.

The URL still requires hostname allowlisting and validation. Configuration should never turn the host into an arbitrary web launcher.

Test controls and architecture assumptions

Use unit tests to keep the policy enforceable:

import { describe, expect, it } from "vitest";
import {
  appointments,
  findDependencyCycles,
  validateService,
} from "./boundaries";

describe("delivery boundary policy", () => {
  it("accepts a bounded modular service", () => {
    const services = new Map([[appointments.id, appointments]]);
    expect(validateService(appointments, services)).toEqual([]);
  });

  it("keeps payment confirmation in the native zone", () => {
    const invalid = {
      ...appointments,
      capabilities: ["payments.confirm" as const],
    };
    const services = new Map([[invalid.id, invalid]]);

    expect(validateService(invalid, services)).toContainEqual(
      expect.objectContaining({ code: "CAPABILITY_NOT_ALLOWED" }),
    );
  });

  it("requires a fallback for modular delivery", () => {
    const invalid = { ...appointments, fallback: undefined };
    const services = new Map([[invalid.id, invalid]]);

    expect(validateService(invalid, services)).toContainEqual(
      expect.objectContaining({ code: "FALLBACK_REQUIRED" }),
    );
  });

  it("reports dependency cycles", () => {
    const first = { ...appointments, id: "first", dependencies: ["second"] };
    const second = { ...appointments, id: "second", dependencies: ["first"] };
    const services = new Map([
      [first.id, first],
      [second.id, second],
    ]);

    expect(findDependencyCycles(services)).toEqual([
      ["first", "second", "first"],
    ]);
  });
});

Add tests for duplicate IDs, malformed destinations, unknown markets, owner resolution, forbidden dependency directions, percentage bounds, unsupported lifecycle transitions, and manifest signatures.

Policy tests should use representative services from the real portfolio. A theoretical rule often appears reasonable until a team tries to describe an existing high-volume or regulated journey.

Keep exceptions visible

A policy model should allow exceptions without making them invisible. Store the approving authority, reason, expiry date, compensating controls, and review ticket next to the exception.

An expiry date matters because temporary exceptions have a habit of becoming permanent platform behaviour. Block publication after expiry unless the exception is reviewed again.

Report exceptions by capability and owner. If many services require the same exception, the platform may be missing a supported capability. If one team accumulates unrelated exceptions, its service boundaries may need redesign.

Make boundary review part of delivery

A service definition has limited value if it is written once for an architecture meeting and never checked again. Put the definition in version control near the code that implements the service, while keeping the organisation-wide policy in an independently owned package or validation service.

The pull request should show the policy impact of each change. Adding a capability, expanding to another market, increasing expected reach, changing consequence, or introducing a dependency deserves more attention than editing descriptive text. A CI job can compare the current and proposed definitions and request the appropriate reviewers based on those fields.

Avoid using repository approval as the only control. Publication should revalidate the signed definition against the current platform policy. A service may have passed CI while the host later retired a capability, raised a minimum runtime version, or suspended a dependency. The launch gateway should also verify that the definition being executed is active and matches the approved digest.

Create a small review record containing:

the definition version and source revision;
validation findings and acknowledged warnings;
required security, product, or compliance approvals;
evidence supporting consequence and customer-reach estimates;
rollout limits and fallback verification;
the next review date.

This record does not need to become a heavyweight committee document. Its purpose is to preserve why a service was assigned to a zone and which assumptions made that placement acceptable.

Review timing should follow change and consequence. A persistent low-risk information service may need review only after material changes. A payment-adjacent module may require periodic reassessment even when its code is stable because regulations, fraud patterns, dependencies, and host capabilities can change around it.

Track policy drift at portfolio level. Useful measures include services with expired ownership, modules using deprecated capabilities, definitions without tested fallbacks, dependency cycles, open exceptions, and services that have not been used for a defined period. These measures indicate whether the platform is preserving deliberate boundaries as it grows.

The review can also move a service between zones. An experimental web journey may become a modular service after demand is demonstrated. A modular journey that becomes central, high reach, and tightly coupled to sensitive controls may move into the native core. A declining service can be separated and retired. Zone assignment describes the current operating model; it is not a permanent identity.

Connect definitions to runtime enforcement

Static validation is only the first layer. The runtime must enforce the same capability set when the service executes. The gateway should verify a signed, active definition; confirm host compatibility and market eligibility; and issue a short-lived launch context.

Telemetry should record service ID, definition version, zone, capabilities granted, route decision, and outcome. Avoid logging personal data or raw authorisation tokens.

An emergency control should suspend one service independently. A separate platform-wide control should disable modular execution if the runtime itself is at risk. Test both paths regularly and maintain the declared fallback.

Definitions also need lifecycle handling. A retiring service should stop new discovery before its data and backend are removed. Existing deep links need a deliberate destination. Support documentation and analytics should identify remaining traffic so the team can complete retirement safely.

Measure independence, not module count

The useful outcome of modular architecture is controlled independence.

A service should be able to change without forcing unrelated releases, use only declared host capabilities, fail within an understood boundary, and reach an accountable owner. Its customer task should remain coherent, and the host should be able to withdraw it without damaging the rest of the app.

TypeScript definitions and validators cannot choose those boundaries for a team. They can expose when the implementation no longer matches the intended design.

That is a better platform signal than the number of modules in a catalogue. A small set of services with real autonomy and enforceable contracts creates more value than a highly fragmented app that still moves as one system.

Add Modular Services Without Rewriting Your React Native Navigation

FinClip Super-App — Fri, 04 Sep 2026 02:28:16 +0000

A mobile platform project often begins with an unnecessary assumption: if the delivery architecture changes, the customer navigation must change with it.

That coupling creates a large first release. The team integrates a runtime, invents a new service catalogue, redesigns the home screen, moves existing routes, and introduces several services at once. Production feedback then becomes difficult to interpret because every layer changed together.

A safer approach keeps the public route contract stable. Existing menu items and deep links continue to represent customer tasks. A gateway decides whether each task should open the original native screen, a modular service, or a web fallback. The implementation can evolve without teaching customers a new information architecture on day one.

This article builds that boundary in TypeScript for a React Native application.

Begin with customer-task routes

Avoid exposing runtime terminology in navigation. A customer should open appointments, not miniapp-host with a collection of technical parameters.

Create a small set of route keys representing durable customer intentions:

export type CustomerTask =
  | "support.appointments"
  | "rewards.seasonal-benefit"
  | "services.document-submission";

export type ExistingNativeRoute =
  | "SupportAppointments"
  | "RewardsHome"
  | "DocumentUpload";

export const nativeFallbacks: Record<CustomerTask, ExistingNativeRoute> = {
  "support.appointments": "SupportAppointments",
  "rewards.seasonal-benefit": "RewardsHome",
  "services.document-submission": "DocumentUpload",
};

These identifiers should change slowly. They can be used by navigation, analytics, support documentation, and deep-link handling even when the destination implementation changes.

The fallback map also makes the first integration reversible. Suspending a module does not need to leave the menu item broken; the gateway can return the customer to the previous native journey.

Describe modular destinations with a manifest

Keep service configuration outside navigation components. A manifest makes ownership, compatibility, and permissions reviewable before a module is allowed to launch.

export type HostCapability =
  | "identity.basic"
  | "analytics.event"
  | "location.approximate"
  | "files.select";

export type ServiceManifest = {
  serviceId: string;
  task: CustomerTask;
  owner: string;
  status: "draft" | "active" | "suspended";
  moduleUri: `miniapp://${string}`;
  webFallback?: `https://${string}`;
  minimumHostVersion: string;
  markets: string[];
  capabilities: HostCapability[];
};

export const appointmentManifest: ServiceManifest = {
  serviceId: "appointments.branch.v2",
  task: "support.appointments",
  owner: "customer-operations",
  status: "active",
  moduleUri: "miniapp://appointments.branch/2.1.0",
  webFallback: "https://services.example.com/appointments",
  minimumHostVersion: "8.4.0",
  markets: ["GB", "SG"],
  capabilities: ["identity.basic", "analytics.event"],
};

Production manifests should be signed, schema-validated, versioned, and served through a controlled publication process. The mobile client should never accept an arbitrary URI or capability list from an untrusted response.

The owner field is operational, not decorative. Monitoring and support systems should be able to turn it into a current escalation route. If a team changes, the registry must change before the service becomes orphaned.

Make the destination decision explainable

The gateway needs enough context to select a route without embedding business logic throughout the UI.

export type LaunchContext = {
  task: CustomerTask;
  market: string;
  hostVersion: string;
  modularServicesEnabled: boolean;
  audienceBucket: number; // 0..99
};

export type LaunchDecision =
  | { kind: "native"; route: ExistingNativeRoute; reason: string }
  | { kind: "module"; uri: string; serviceId: string; reason: string }
  | { kind: "web"; url: string; serviceId: string; reason: string };

function compareVersions(left: string, right: string): number {
  const a = left.split(".").map(Number);
  const b = right.split(".").map(Number);
  const length = Math.max(a.length, b.length);

  for (let index = 0; index < length; index += 1) {
    const difference = (a[index] ?? 0) - (b[index] ?? 0);
    if (difference !== 0) return difference;
  }

  return 0;
}

export function decideDestination(
  context: LaunchContext,
  manifest?: ServiceManifest,
): LaunchDecision {
  const native = nativeFallbacks[context.task];

  if (!context.modularServicesEnabled) {
    return { kind: "native", route: native, reason: "platform_disabled" };
  }

  if (!manifest || manifest.task !== context.task) {
    return { kind: "native", route: native, reason: "manifest_missing" };
  }

  if (manifest.status !== "active") {
    return { kind: "native", route: native, reason: "service_inactive" };
  }

  if (!manifest.markets.includes(context.market)) {
    return { kind: "native", route: native, reason: "market_not_allowed" };
  }

  if (context.audienceBucket >= 10) {
    return { kind: "native", route: native, reason: "outside_rollout" };
  }

  if (compareVersions(context.hostVersion, manifest.minimumHostVersion) < 0) {
    if (manifest.webFallback) {
      return {
        kind: "web",
        url: manifest.webFallback,
        serviceId: manifest.serviceId,
        reason: "host_too_old",
      };
    }

    return { kind: "native", route: native, reason: "host_too_old" };
  }

  return {
    kind: "module",
    uri: manifest.moduleUri,
    serviceId: manifest.serviceId,
    reason: "eligible",
  };
}

The returned reason is important. A fallback caused by staged rollout is healthy behaviour; a missing manifest may indicate a publication failure. If both are logged as generic navigation events, operations cannot distinguish control decisions from defects.

Replace the example version parser with a well-tested semantic-version implementation if your versions include prerelease labels or build metadata.

Adapt the decision to existing navigation

The current menu does not need to know how a modular runtime works. It asks the gateway to open a customer task.

type Navigator = {
  navigate: (screen: string, params?: Record<string, unknown>) => void;
};

type Runtime = {
  open: (uri: string, options: { serviceId: string }) => Promise<void>;
};

type Browser = {
  openSecure: (url: string) => Promise<void>;
};

export async function openCustomerTask(
  decision: LaunchDecision,
  dependencies: {
    navigator: Navigator;
    runtime: Runtime;
    browser: Browser;
  },
): Promise<void> {
  switch (decision.kind) {
    case "native":
      dependencies.navigator.navigate(decision.route);
      return;

    case "module":
      await dependencies.runtime.open(decision.uri, {
        serviceId: decision.serviceId,
      });
      return;

    case "web":
      await dependencies.browser.openSecure(decision.url);
  }
}

The adapter should receive only validated destinations. The runtime must reject unknown URI schemes, unapproved service IDs, and capabilities that are absent from the published manifest. The browser adapter should enforce an HTTPS hostname allowlist and prevent arbitrary redirects.

Do not place personal information in module URIs or query parameters. Pass a short-lived, audience-bound launch token containing an opaque subject reference, then let the service retrieve authorised context from its backend. URLs frequently reach logs, screenshots, browser history, and analytics systems.

Preserve deep-link meaning across implementations

Existing links from email, push notifications, websites, and support messages may be more durable than the screen currently serving them. Keep those links expressed in customer-task language as well.

For example, exampleapp://support/appointments should resolve to the same task key used by the in-app menu. The deep-link parser can validate the external input, discard unknown parameters, and then call decideDestination. It should never accept a raw module URI from outside the app.

When route ownership changes, test old links against every supported host version. Customers may open a months-old notification after the modular service has been upgraded, suspended, or replaced. The gateway needs a valid result for each state: current module, maintained web route, or existing native journey.

Preserve analytics meaning too. A historical dashboard may measure appointment_started and appointment_completed; changing the renderer should not create a second business definition. Add technical dimensions such as delivery_kind, service_id, and manifest_version while keeping customer-task events stable. This allows product teams to compare the original journey with the modular one without stitching together unrelated event names.

Be careful with attribution during staged rollout. The server-assigned cohort, route-decision reason, and service version should travel through the journey as controlled metadata. Do not let individual modules redefine these fields. A shared event envelope makes route comparisons possible while preventing each service team from inventing a separate measurement model.

Finally, document the supported lifetime of task routes. Removing a service may retire the customer proposition, but old links should fail in a deliberate way. Show a clear message, provide the next useful destination, and record the retirement outcome so the organisation can find channels that still publish obsolete links.

Keep visual continuity as a contract

Stable navigation is only part of a familiar experience. Independently delivered services can still introduce inconsistent typography, gestures, loading states, terminology, and error behaviour.

Create a host shell that owns shared chrome and exposes approved design tokens:

export type HostDesignContract = {
  themeVersion: "3";
  colorMode: "light" | "dark";
  textScale: number;
  locale: string;
  safeArea: { top: number; right: number; bottom: number; left: number };
  closeBehavior: "return_to_origin";
};

Version this contract independently from individual services. A module can declare the versions it supports, and the host can refuse or fall back when no compatible contract exists.

The contract should cover behaviour as well as colours. Define how the back button works, where the service title appears, how consent is requested, how support is reached, and how a fatal error returns the customer to a safe screen. Accessibility settings from the host should continue into the module whenever the runtime permits it.

Avoid giving every service unrestricted control over the entire screen. Shared chrome helps customers understand that they remain inside the host app and gives the host a reliable place for navigation and safety controls.

Roll out by stable customer identity

Randomising eligibility on every launch can make the same customer alternate between native and modular journeys. Derive the audience bucket from a stable, non-PII identifier on the server, and keep the percentage in policy configuration.

Start with employees or test accounts, then move to a small customer cohort. Measure at least:

route decision and reason;
module load success and time;
task completion;
fallback activation;
customer exits and retries;
support contacts associated with the service;
host crashes and runtime errors.

A platform metric such as module load time cannot tell you whether the customer completed an appointment. Join runtime telemetry to a privacy-conscious business outcome using a correlation identifier with limited retention.

Design rollback before launch

Rollback should be a policy change, not an emergency mobile release.

Suspending the manifest or setting the rollout percentage to zero should route new sessions to the previous native screen or an approved web fallback. Decide what happens to sessions already open in the module. Financial or transactional tasks may need to complete, fail safely, or resume through a server-side operation identifier.

The fallback must be maintained while it remains part of the recovery plan. A native screen that has silently broken because the team assumed the module would always be available provides false reassurance.

Use separate controls for platform-wide shutdown and individual-service suspension. One faulty appointment module should not remove unrelated services, while a runtime vulnerability may require the host to disable all modular execution immediately.

Test the policy boundaries

Unit tests should focus on routing conditions and fail-safe behaviour:

import { describe, expect, it } from "vitest";
import { appointmentManifest, decideDestination } from "./routing";

const baseContext = {
  task: "support.appointments" as const,
  market: "GB",
  hostVersion: "8.5.0",
  modularServicesEnabled: true,
  audienceBucket: 4,
};

describe("decideDestination", () => {
  it("opens the module for an eligible customer", () => {
    expect(decideDestination(baseContext, appointmentManifest).kind)
      .toBe("module");
  });

  it("keeps most customers on the native route during rollout", () => {
    const result = decideDestination(
      { ...baseContext, audienceBucket: 41 },
      appointmentManifest,
    );
    expect(result).toMatchObject({
      kind: "native",
      reason: "outside_rollout",
    });
  });

  it("uses the maintained fallback when the service is suspended", () => {
    const result = decideDestination(baseContext, {
      ...appointmentManifest,
      status: "suspended",
    });
    expect(result).toMatchObject({
      kind: "native",
      route: "SupportAppointments",
    });
  });
});

Add integration tests for signed manifest validation, expired launch tokens, incompatible design-contract versions, unknown capabilities, runtime load failure, deep links, analytics correlation, and returning from a web fallback.

Test accessibility and navigation on real devices. A module that renders correctly can still trap focus, break the system back gesture, ignore text scaling, or announce unclear screen titles to assistive technology.

Change the implementation before changing the mental model

The gateway creates a narrow seam between what customers ask the app to do and how the app fulfils the request.

That seam lets the organisation add one modular service behind a route customers already understand. It preserves a native fallback, limits exposure, keeps decisions observable, and makes withdrawal possible without waiting for an app-store release.

Once several services demonstrate value, navigation may need to evolve. That decision can use real evidence: which tasks customers seek, which entries become crowded, and whether discovery is failing. The platform architecture prepares the app for that future without forcing a speculative redesign into the first release.

Customers can keep using the app they recognise while the delivery model underneath it becomes more adaptable.

Build a Safe Service Entry Gateway in TypeScript

FinClip Super-App — Thu, 03 Sep 2026 02:19:47 +0000

Build a Safe Service Entry Gateway in TypeScript

A customer should not need a new standalone app for every focused digital service. An appointment, campaign, local offer, claim intake, or partner benefit may fit inside an app the customer already trusts. A secure web journey can also be enough when no deep integration is required.

Removing the extra download creates a new engineering responsibility: the organisation needs a safe way to decide where a service opens and which host capabilities travel with the launch.

This tutorial builds a small TypeScript service-entry gateway. It supports two destinations:

An embedded module running inside an approved host app.
An allowlisted HTTPS fallback for browsers or unsupported host versions.

The gateway validates a versioned service manifest, chooses an eligible route, creates a short-lived signed launch ticket, and returns reasons that can be logged and reviewed. It does not send raw customer records through a URL.

Start with a service manifest

The service producer should declare what the service needs before it can be launched:

export type Capability =
  | "identity.basic"
  | "payment.initiate"
  | "location.approximate"
  | "camera.capture"
  | "analytics.event";

export interface EmbeddedEntry {
  kind: "embedded";
  moduleId: string;
  minimumHostVersion: string;
}

export interface WebEntry {
  kind: "web";
  url: string;
}

export interface ServiceManifest {
  serviceId: string;
  version: string;
  displayName: string;
  owner: string;
  status: "draft" | "active" | "suspended" | "retired";
  allowedMarkets: string[];
  requiredCapabilities: Capability[];
  entries: Array<EmbeddedEntry | WebEntry>;
  supportUrl: string;
}

Keep the manifest small and auditable. It is a contract between the service, host, and gateway, not a place for marketing copy or customer data.

The status field gives operations an independent stop control. A suspended service should stop receiving new launches even if its code remains deployed. allowedMarkets prevents a service approved in one jurisdiction from appearing everywhere by default.

A production manifest would also include data purpose, age classification, risk tier, signing identity, review evidence, and expiry dates. Add fields when the corresponding control exists; decorative metadata can create false confidence.

Describe the launch context

The gateway needs enough context to choose a route without collecting unnecessary information:

export interface LaunchRequest {
  serviceId: string;
  market: string;
  channel: "host_app" | "mobile_web" | "desktop_web";
  hostVersion?: string;
  subjectReference?: string;
  requestedCapabilities: Capability[];
}

export interface LaunchDecision {
  destination: "embedded" | "web" | "deny";
  target?: string;
  ticket?: string;
  reasons: string[];
}

subjectReference should be an opaque identifier understood by the identity broker, not an email address, phone number, account balance, or full customer profile. The receiving service can exchange a valid reference for the minimum data it is authorised to use.

Avoid putting sensitive attributes in query parameters. URLs are copied into analytics, browser history, reverse-proxy logs, screenshots, and support tickets more often than teams expect.

Validate URLs and manifest policy

The gateway should reject malformed or overly broad destinations before any route selection happens:

const ALLOWED_WEB_HOSTS = new Set([
  "services.example.com",
  "partners.example.net",
]);

const HOST_CAPABILITIES = new Set<Capability>([
  "identity.basic",
  "payment.initiate",
  "location.approximate",
  "camera.capture",
  "analytics.event",
]);

function isAllowedHttpsUrl(value: string): boolean {
  try {
    const url = new URL(value);
    return url.protocol === "https:" && ALLOWED_WEB_HOSTS.has(url.hostname);
  } catch {
    return false;
  }
}

export function validateManifest(manifest: ServiceManifest): string[] {
  const errors: string[] = [];

  if (!/^[a-z0-9][a-z0-9.-]{2,63}$/.test(manifest.serviceId)) {
    errors.push("serviceId has an invalid format");
  }

  if (!manifest.owner.trim()) errors.push("owner is required");
  if (manifest.allowedMarkets.length === 0) {
    errors.push("at least one market is required");
  }

  if (manifest.entries.length === 0) errors.push("an entry is required");

  for (const capability of manifest.requiredCapabilities) {
    if (!HOST_CAPABILITIES.has(capability)) {
      errors.push(`unsupported capability: ${capability}`);
    }
  }

  for (const entry of manifest.entries) {
    if (entry.kind === "web" && !isAllowedHttpsUrl(entry.url)) {
      errors.push(`web entry is not allowlisted: ${entry.url}`);
    }
  }

  if (!isAllowedHttpsUrl(manifest.supportUrl)) {
    errors.push("supportUrl must use an allowlisted HTTPS host");
  }

  return errors;
}

Use exact hostnames instead of suffix checks such as endsWith("example.com"). A misleading domain like notexample.com can pass a careless suffix rule. If subdomains are allowed, parse and compare them against an explicit policy.

Validation should happen when a manifest is submitted and again when it is activated. Store the policy version with the result so an old approval remains interpretable after allowlists change.

Compare semantic versions

An embedded module may depend on APIs introduced in a newer host. A simple semantic-version comparison is sufficient for this example:

function compareVersions(left: string, right: string): number {
  const a = left.split(".").map(Number);
  const b = right.split(".").map(Number);
  const length = Math.max(a.length, b.length);

  for (let index = 0; index < length; index += 1) {
    const difference = (a[index] ?? 0) - (b[index] ?? 0);
    if (difference !== 0) return Math.sign(difference);
  }

  return 0;
}

Real semantic versions can include prerelease labels and build metadata. Use a maintained parser in production and define how prerelease host versions are treated. An unexpected version string should fail closed or use the web fallback; it should not be interpreted as the newest possible client.

Issue a short-lived launch ticket

The service needs proof that the gateway approved the launch. We can create a compact payload and sign it with an HMAC. Node’s built-in crypto module is enough for the example:

import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";

interface TicketPayload {
  iss: "service-entry-gateway";
  aud: string;
  serviceId: string;
  serviceVersion: string;
  subjectReference?: string;
  market: string;
  capabilities: Capability[];
  iat: number;
  exp: number;
  nonce: string;
}

function base64url(value: string): string {
  return Buffer.from(value, "utf8").toString("base64url");
}

function signPayload(payload: TicketPayload, secret: string): string {
  const body = base64url(JSON.stringify(payload));
  const signature = createHmac("sha256", secret)
    .update(body)
    .digest("base64url");

  return `${body}.${signature}`;
}

function createTicket(
  manifest: ServiceManifest,
  request: LaunchRequest,
  audience: string,
  secret: string,
  now = new Date(),
): string {
  const issuedAt = Math.floor(now.getTime() / 1000);

  return signPayload(
    {
      iss: "service-entry-gateway",
      aud: audience,
      serviceId: manifest.serviceId,
      serviceVersion: manifest.version,
      subjectReference: request.subjectReference,
      market: request.market,
      capabilities: request.requestedCapabilities,
      iat: issuedAt,
      exp: issuedAt + 120,
      nonce: randomUUID(),
    },
    secret,
  );
}

The two-minute lifetime limits replay exposure. The receiving service should also store consumed nonces until expiry when a ticket is intended for one-time use.

HMAC means the issuer and verifier share a secret. For a partner ecosystem, asymmetric signatures are often easier to separate operationally: the gateway keeps the private key and services receive only the public key. Use a standard token library and managed key service rather than inventing a production token format from this example.

Do not grant capabilities merely because the request asks for them. The request must be a subset of the reviewed manifest.

Choose the route

Now enforce status, market, and capability policy before selecting embedded or web delivery:

function isCapabilitySubset(
  requested: Capability[],
  approved: Capability[],
): boolean {
  const allowed = new Set(approved);
  return requested.every((capability) => allowed.has(capability));
}

export function decideLaunch(
  manifest: ServiceManifest,
  request: LaunchRequest,
  signingSecret: string,
  now = new Date(),
): LaunchDecision {
  const errors = validateManifest(manifest);
  if (errors.length > 0) {
    return { destination: "deny", reasons: errors };
  }

  if (manifest.status !== "active") {
    return {
      destination: "deny",
      reasons: [`service status is ${manifest.status}`],
    };
  }

  if (!manifest.allowedMarkets.includes(request.market)) {
    return {
      destination: "deny",
      reasons: [`service is unavailable in ${request.market}`],
    };
  }

  if (
    !isCapabilitySubset(
      request.requestedCapabilities,
      manifest.requiredCapabilities,
    )
  ) {
    return {
      destination: "deny",
      reasons: ["requested capabilities exceed the reviewed manifest"],
    };
  }

  const embedded = manifest.entries.find(
    (entry): entry is EmbeddedEntry => entry.kind === "embedded",
  );

  if (
    request.channel === "host_app" &&
    request.hostVersion &&
    embedded &&
    compareVersions(request.hostVersion, embedded.minimumHostVersion) >= 0
  ) {
    return {
      destination: "embedded",
      target: embedded.moduleId,
      ticket: createTicket(
        manifest,
        request,
        embedded.moduleId,
        signingSecret,
        now,
      ),
      reasons: ["host version and capability policy allow embedded launch"],
    };
  }

  const web = manifest.entries.find(
    (entry): entry is WebEntry => entry.kind === "web",
  );

  if (web) {
    return {
      destination: "web",
      target: web.url,
      ticket: createTicket(manifest, request, web.url, signingSecret, now),
      reasons: ["using approved HTTPS fallback"],
    };
  }

  return {
    destination: "deny",
    reasons: ["no eligible delivery route is available"],
  };
}

Route selection prefers the embedded service only when the request comes from the host app and the host version meets the declared minimum. Older versions receive the approved web fallback. A service with no fallback is denied cleanly.

The gateway returns the ticket separately from the target. The client can transfer it in an authorised POST request or platform-specific secure handoff. Avoid appending it to the query string.

Verify the ticket

The receiving service must check signature, audience, expiry, and status before exchanging the subject reference:

function verifyTicket(
  token: string,
  expectedAudience: string,
  secret: string,
  now = new Date(),
): TicketPayload {
  const [body, suppliedSignature] = token.split(".");
  if (!body || !suppliedSignature) throw new Error("malformed ticket");

  const expectedSignature = createHmac("sha256", secret)
    .update(body)
    .digest("base64url");

  const supplied = Buffer.from(suppliedSignature);
  const expected = Buffer.from(expectedSignature);

  if (
    supplied.length !== expected.length ||
    !timingSafeEqual(supplied, expected)
  ) {
    throw new Error("invalid signature");
  }

  const payload = JSON.parse(
    Buffer.from(body, "base64url").toString("utf8"),
  ) as TicketPayload;

  const currentTime = Math.floor(now.getTime() / 1000);
  if (payload.exp <= currentTime) throw new Error("ticket expired");
  if (payload.aud !== expectedAudience) throw new Error("wrong audience");

  return payload;
}

JSON parsing still needs runtime schema validation. A valid signature proves that the issuer signed the bytes; it does not prove the decoded object matches your expected shape.

The service should also confirm that its manifest version remains active. A ticket issued moments before an emergency suspension should not guarantee access for the rest of its lifetime if the risk warrants immediate revocation.

Test the important boundaries

Use Vitest to cover the success path and the controls most likely to regress:

import { describe, expect, it } from "vitest";
import { decideLaunch, ServiceManifest } from "./gateway";

const manifest: ServiceManifest = {
  serviceId: "appointments.branch",
  version: "1.4.0",
  displayName: "Branch appointments",
  owner: "customer-operations",
  status: "active",
  allowedMarkets: ["GB", "SG"],
  requiredCapabilities: ["identity.basic", "analytics.event"],
  entries: [
    {
      kind: "embedded",
      moduleId: "miniapp://appointments.branch/1.4.0",
      minimumHostVersion: "8.2.0",
    },
    { kind: "web", url: "https://services.example.com/appointments" },
  ],
  supportUrl: "https://services.example.com/support/appointments",
};

describe("service entry gateway", () => {
  it("launches inside an eligible host", () => {
    const result = decideLaunch(
      manifest,
      {
        serviceId: manifest.serviceId,
        market: "GB",
        channel: "host_app",
        hostVersion: "8.3.1",
        subjectReference: "subject_opaque_92",
        requestedCapabilities: ["identity.basic"],
      },
      "test-secret",
    );

    expect(result.destination).toBe("embedded");
    expect(result.ticket).toBeDefined();
  });

  it("uses web fallback for an older host", () => {
    const result = decideLaunch(
      manifest,
      {
        serviceId: manifest.serviceId,
        market: "GB",
        channel: "host_app",
        hostVersion: "8.1.9",
        requestedCapabilities: [],
      },
      "test-secret",
    );

    expect(result.destination).toBe("web");
  });

  it("denies a capability that was not reviewed", () => {
    const result = decideLaunch(
      manifest,
      {
        serviceId: manifest.serviceId,
        market: "GB",
        channel: "host_app",
        hostVersion: "8.3.1",
        requestedCapabilities: ["camera.capture"],
      },
      "test-secret",
    );

    expect(result.destination).toBe("deny");
  });

  it("denies a suspended service", () => {
    const result = decideLaunch(
      { ...manifest, status: "suspended" },
      {
        serviceId: manifest.serviceId,
        market: "GB",
        channel: "mobile_web",
        requestedCapabilities: [],
      },
      "test-secret",
    );

    expect(result.destination).toBe("deny");
  });
});

Add tests for market restrictions, malformed versions, disallowed hosts, expired tickets, replayed nonces, and audience mismatch. Security tests should fail closed when required evidence is absent.

Treat the fallback as a supported journey

A web fallback is useful only when it remains part of the product, rather than a forgotten URL attached to the manifest. Give the page the same service identity, accessibility standard, analytics vocabulary, and support route as the embedded version. Customers should understand that they are continuing the same task even when the rendering environment changes.

Preserve as little state as possible during the transition. The launch ticket can carry an opaque subject reference and a narrow purpose, while the destination retrieves authorised data through its own backend. Avoid copying form contents, personal details, or durable credentials into query parameters. Browser history, proxy logs, screenshots, and referrer headers can expose more than the original developer expected.

Define what happens when the destination is unavailable. A controlled maintenance response with a retry path and support reference is more useful than sending the customer through repeated redirects. Apply a short timeout to dependency checks, and keep the deny response explainable enough for support teams to identify whether the cause was market policy, host compatibility, service status, or a technical failure.

The embedded and web routes should also share an idempotency strategy. If a customer presses the launch button twice, returns from the browser, or retries after a weak connection, the service must not create duplicate appointments, claims, or payments. Generate the business-operation idempotency key at the service boundary; do not rely on the launch-ticket nonce for this purpose. The nonce limits replay of entry context, while an idempotency key protects the transaction itself.

Finally, test the handoff on real mobile conditions. Slow networks, expired sessions, disabled cookies, older host versions, and interrupted authentication often reveal more than desktop happy-path testing. The route is successful only when the customer can complete the intended job and recover from predictable interruptions.

Operate the gateway as a product boundary

The gateway centralises a decision that otherwise spreads across deep links, web redirects, mobile code, and service-specific integrations. Give it an owner, availability target, audit trail, and emergency process.

Log the service ID, version, chosen destination, policy version, reason, and outcome. Do not log the raw ticket or customer attributes. Metrics should distinguish a clean fallback from an error so an old host version does not look like a failed launch.

Monitor completion after routing. An embedded destination may remove an installation but still present a confusing consent screen. A web fallback may be entirely adequate for a low-frequency task. Customer outcome should decide whether a route is useful.

Roll out new manifests to a small audience first. A feature flag can limit the market, customer segment, or percentage of traffic. The independent suspended status provides a fast response when support, compliance, or reliability problems appear.

One service, several proportionate routes

A safe entry gateway does not decide that every service belongs inside the host app. It gives the organisation a controlled way to support more than one route.

The manifest makes ownership and capability needs visible. Route policy respects host compatibility and market approval. Short-lived signed tickets transfer minimal launch context. The web fallback prevents an unnecessary download when the embedded experience is unavailable.

That combination allows a focused service to reach customers without immediately becoming another standalone application. If the service later demonstrates frequent use, independent brand value, and deeper native needs, its delivery model can evolve. The first implementation remains reversible while the evidence is still developing.

Turn a Mobile App Backlog into Delivery Lanes with TypeScript

FinClip Super-App — Wed, 02 Sep 2026 01:55:16 +0000

Turn a Mobile App Backlog into Delivery Lanes with TypeScript

A mobile app backlog often mixes security work, core journeys, campaigns, regional requests, experiments, and partner integrations. Giving every item the same release path is easy to administer, but it can force a time-sensitive, bounded service to wait behind a high-risk change that correctly requires deeper review.

The answer is not an algorithm that automatically decides product strategy. A useful triage tool makes assumptions visible, enforces non-negotiable constraints, and recommends a delivery lane with reasons that humans can review.

In this tutorial, we will build that tool in TypeScript. It routes a backlog item to one of three lanes:

core_native: part of the main app and its coordinated release.
modular_in_app: a bounded service loaded inside the host under explicit controls.
external_or_standalone: a web handoff or separate app when the audience or boundary is independent.

The model also estimates urgency signals without pretending that uncertain forecasts are exact financial values.

Model the work item

Start with fields that a product, risk, and engineering review can reasonably supply:

export type DeliveryLane =
  | "core_native"
  | "modular_in_app"
  | "external_or_standalone"
  | "needs_discovery";

export type RiskLevel = "low" | "medium" | "high" | "critical";

export interface BacklogItem {
  id: string;
  title: string;
  owner?: string;

  // Demand and timing
  affectedUsersPerMonth?: number;
  evidenceConfidence: "none" | "weak" | "moderate" | "strong";
  valueWindowEndsAt?: string;
  recurringManualCostPerMonth?: number;
  blocksCommittedLaunch: boolean;

  // Customer journey
  startsInHostApp: boolean;
  repeatedLoginOnHandoff: boolean;
  repeatedDataEntryOnHandoff: boolean;
  audienceOverlapWithHost: number; // 0..1

  // Delivery characteristics
  expectedChangesPerQuarter: number;
  hostReleaseDependency: boolean;
  independentlyReversible: boolean;
  independentBusinessOwner: boolean;

  // Integration and risk
  requiredCapabilities: string[];
  capabilityAllowlistDefined: boolean;
  risk: RiskLevel;
  regulatedCoreJourney: boolean;
  broadNativeSurfaceChange: boolean;
  separateBrandOrLegalBoundary: boolean;
}

Several inputs are optional because backlog data is usually incomplete. Missing information should lead to discovery, not a conveniently low score.

audienceOverlapWithHost is an estimate between zero and one. It represents how much of the service's intended audience already uses the host app. It is more useful than asking whether a service is “strategic,” a label that tends to expand during prioritisation meetings.

The data model should be versioned. If teams change the meaning of high risk or strong evidence, old decisions must remain interpretable.

Validate input at the boundary

TypeScript types disappear at runtime, so an API cannot trust incoming JSON merely because it is assigned to BacklogItem. A production service should validate identifiers, ranges, dates, enum values, and currency units before triage. Reject an audienceOverlapWithHost above one, an invalid date, or a negative manual cost. Decide whether missing optional fields are allowed for early discovery and ensure the user interface explains the consequence.

Schema validation libraries can make this concise, but the schema should remain aligned with the policy version. Store the validated snapshot with the result. Recomputing an old decision from data that has since changed weakens the audit trail.

Currency requires special care. If several markets submit costs, store the amount, currency, conversion date, and rate source. The normalised urgency score can compare items only after the organisation agrees on that treatment. Avoid silently treating every numeric amount as the same currency.

Separate hard constraints from preferences

Some conditions should block modular delivery regardless of commercial urgency. A critical service without an owner should not become acceptable because it has a short market window.

export interface TriageResult {
  lane: DeliveryLane;
  confidence: "low" | "medium" | "high";
  urgencyScore: number;
  fitScores: Record<Exclude<DeliveryLane, "needs_discovery">, number>;
  blockers: string[];
  reasons: string[];
  missingEvidence: string[];
}

function findModularBlockers(item: BacklogItem): string[] {
  const blockers: string[] = [];

  if (!item.owner || !item.independentBusinessOwner) {
    blockers.push("A modular service requires a named business owner.");
  }

  if (item.risk === "critical") {
    blockers.push("Critical-risk work stays in the coordinated core lane.");
  }

  if (item.regulatedCoreJourney) {
    blockers.push("The item is part of a regulated core journey.");
  }

  if (item.requiredCapabilities.length > 0 && !item.capabilityAllowlistDefined) {
    blockers.push("Required host capabilities do not have an allowlist.");
  }

  if (!item.independentlyReversible) {
    blockers.push("The service cannot be restricted or removed independently.");
  }

  return blockers;
}

These are example policies, not universal rules. A bank, retailer, airline, and public agency will classify risk differently. The design principle is the important part: keep blockers explicit so a weighted score cannot average them away.

An organisation may support high-risk modular services after building stronger controls. In that case, create a separate policy profile with additional evidence instead of silently weakening the general rule.

Capture missing discovery

The triage engine should resist false certainty. Add a function that identifies information required for a useful decision:

function findMissingEvidence(item: BacklogItem): string[] {
  const missing: string[] = [];

  if (!item.owner) missing.push("service owner");
  if (item.evidenceConfidence === "none") missing.push("demand evidence");
  if (item.affectedUsersPerMonth === undefined) missing.push("affected users");

  if (
    item.recurringManualCostPerMonth === undefined &&
    !item.valueWindowEndsAt &&
    !item.blocksCommittedLaunch
  ) {
    missing.push("cost or timing consequence of delay");
  }

  return missing;
}

Missing evidence does not always mean the item should be rejected. An experiment may exist precisely because demand is uncertain. It should still have a hypothesis, an owner, a limited audience, and a decision that observed usage will inform.

You can distinguish “unknown because this is an experiment” from “unknown because nobody prepared the request” by adding a work type and an experiment plan. Keep this example compact for now.

Estimate urgency without inventing precision

Cost of delay can include a market window, continuing manual work, a committed dependency, and affected users. We can combine normalised signals while retaining the raw evidence for human review.

const DAY_MS = 86_400_000;

function clamp(value: number, min = 0, max = 1): number {
  return Math.min(max, Math.max(min, value));
}

function daysUntil(date: string, now: Date): number {
  return Math.ceil((new Date(date).getTime() - now.getTime()) / DAY_MS);
}

function urgencyScore(item: BacklogItem, now = new Date()): number {
  const windowSignal = item.valueWindowEndsAt
    ? 1 - clamp(daysUntil(item.valueWindowEndsAt, now) / 120)
    : 0;

  const manualCostSignal = clamp(
    (item.recurringManualCostPerMonth ?? 0) / 50_000,
  );

  const reachSignal = clamp((item.affectedUsersPerMonth ?? 0) / 100_000);
  const commitmentSignal = item.blocksCommittedLaunch ? 1 : 0;

  return Number(
    (
      windowSignal * 0.35 +
      manualCostSignal * 0.20 +
      reachSignal * 0.20 +
      commitmentSignal * 0.25
    ).toFixed(3),
  );
}

The thresholds are calibration constants, not benchmarks. A regional organisation may consider 10,000 affected users material. A global consumer platform may not. Put these values in a versioned policy configuration rather than leaving them embedded in application code.

Do not present 0.74 as a financial return. It is a relative urgency signal used to compare similarly evidenced items. Show the underlying market date, cost estimate, and reach alongside it.

The score should also expose evidence confidence. Two requests may receive the same urgency value even though one uses observed call-centre cost and the other uses a campaign forecast. Product reviewers should see that difference. One option is to display a confidence badge beside the score and prevent low-confidence items from outranking committed work without an explicit review.

Do not reward teams for inflating reach or declaring every date a hard deadline. Compare forecasts with actual outcomes after release and report systematic estimation bias by request type, not as an individual performance ranking. The purpose is to improve portfolio decisions, not to create a contest for the largest number.

Score delivery-lane fit

Next, evaluate characteristics that favour each lane:

type ScoredLane = Exclude<DeliveryLane, "needs_discovery">;

function scoreLaneFit(item: BacklogItem): Record<ScoredLane, number> {
  let core = 0;
  let modular = 0;
  let external = 0;

  // Core-native signals
  if (item.regulatedCoreJourney) core += 4;
  if (item.broadNativeSurfaceChange) core += 3;
  if (item.risk === "critical") core += 4;
  if (item.risk === "high") core += 2;
  if (item.audienceOverlapWithHost >= 0.8) core += 1;

  // Modular in-app signals
  if (item.startsInHostApp) modular += 2;
  if (item.repeatedLoginOnHandoff) modular += 2;
  if (item.repeatedDataEntryOnHandoff) modular += 2;
  if (item.expectedChangesPerQuarter >= 3) modular += 2;
  if (item.hostReleaseDependency) modular += 2;
  if (item.independentlyReversible) modular += 2;
  if (item.audienceOverlapWithHost >= 0.5) modular += 1;
  if (item.capabilityAllowlistDefined) modular += 1;

  // External or standalone signals
  if (item.separateBrandOrLegalBoundary) external += 4;
  if (item.audienceOverlapWithHost < 0.25) external += 3;
  if (!item.startsInHostApp) external += 1;
  if (item.requiredCapabilities.length === 0) external += 1;

  return {
    core_native: core,
    modular_in_app: modular,
    external_or_standalone: external,
  };
}

The score explains affinity, while the blockers enforce policy. A campaign may have strong modular characteristics and still remain blocked until its data capability is declared.

Consider negative evidence as well. If a service would add navigation clutter for a tiny unrelated audience, subtract from modular fit. If a web handoff has excellent single sign-on and preserves context, the customer-continuity benefit of embedding may be small.

Make an explainable recommendation

Combine the signals into a result:

function bestLane(scores: Record<ScoredLane, number>): ScoredLane {
  return (Object.entries(scores) as Array<[ScoredLane, number]>).sort(
    (a, b) => b[1] - a[1],
  )[0][0];
}

function scoreGap(scores: Record<ScoredLane, number>): number {
  const ordered = Object.values(scores).sort((a, b) => b - a);
  return ordered[0] - ordered[1];
}

export function triageBacklogItem(
  item: BacklogItem,
  now = new Date(),
): TriageResult {
  const missingEvidence = findMissingEvidence(item);
  const fitScores = scoreLaneFit(item);
  const blockers = findModularBlockers(item);
  const preferred = bestLane(fitScores);
  const reasons: string[] = [];

  if (item.valueWindowEndsAt) reasons.push("The item has a time-bound value window.");
  if (item.hostReleaseDependency) reasons.push("It currently waits for host releases.");
  if (item.repeatedLoginOnHandoff) reasons.push("Handoff repeats authentication.");
  if (item.repeatedDataEntryOnHandoff) reasons.push("Handoff repeats customer input.");
  if (item.separateBrandOrLegalBoundary) {
    reasons.push("The service has an independent brand or legal boundary.");
  }

  let lane: DeliveryLane = preferred;

  if (missingEvidence.length >= 2) {
    lane = "needs_discovery";
  } else if (preferred === "modular_in_app" && blockers.length > 0) {
    lane = item.regulatedCoreJourney || item.risk === "critical"
      ? "core_native"
      : "needs_discovery";
  }

  const gap = scoreGap(fitScores);
  const confidence =
    missingEvidence.length > 0 ? "low" : gap >= 4 ? "high" : "medium";

  return {
    lane,
    confidence,
    urgencyScore: urgencyScore(item, now),
    fitScores,
    blockers,
    reasons,
    missingEvidence,
  };
}

The recommendation can now say “needs discovery” instead of forcing every item into a delivery architecture. That output is useful when it names the missing decision evidence.

The confidence calculation is intentionally simple. A production model could use evidence freshness, source quality, and reviewer agreement, but it should remain understandable to the people approving the work.

Test the policy, especially the boundaries

Policy code needs tests because a small scoring change can alter delivery recommendations. Here are examples using Vitest:

import { describe, expect, it } from "vitest";
import { BacklogItem, triageBacklogItem } from "./triage";

const campaign: BacklogItem = {
  id: "campaign-42",
  title: "Regional renewal campaign",
  owner: "growth-region-a",
  affectedUsersPerMonth: 28_000,
  evidenceConfidence: "strong",
  valueWindowEndsAt: "2026-10-15",
  recurringManualCostPerMonth: 8_000,
  blocksCommittedLaunch: true,
  startsInHostApp: true,
  repeatedLoginOnHandoff: true,
  repeatedDataEntryOnHandoff: false,
  audienceOverlapWithHost: 0.88,
  expectedChangesPerQuarter: 5,
  hostReleaseDependency: true,
  independentlyReversible: true,
  independentBusinessOwner: true,
  requiredCapabilities: ["customer.basic", "analytics.event"],
  capabilityAllowlistDefined: true,
  risk: "medium",
  regulatedCoreJourney: false,
  broadNativeSurfaceChange: false,
  separateBrandOrLegalBoundary: false,
};

describe("mobile backlog triage", () => {
  it("recommends a modular lane for a bounded campaign", () => {
    const result = triageBacklogItem(campaign, new Date("2026-09-02"));
    expect(result.lane).toBe("modular_in_app");
    expect(result.blockers).toEqual([]);
  });

  it("does not average away a missing capability allowlist", () => {
    const result = triageBacklogItem({
      ...campaign,
      capabilityAllowlistDefined: false,
    });

    expect(result.lane).toBe("needs_discovery");
    expect(result.blockers).toContain(
      "Required host capabilities do not have an allowlist.",
    );
  });

  it("keeps a regulated core journey in the core lane", () => {
    const result = triageBacklogItem({
      ...campaign,
      title: "Payment authorization change",
      risk: "critical",
      regulatedCoreJourney: true,
    });

    expect(result.lane).toBe("core_native");
  });

  it("requests discovery when demand and consequence are unknown", () => {
    const result = triageBacklogItem({
      ...campaign,
      owner: undefined,
      evidenceConfidence: "none",
      affectedUsersPerMonth: undefined,
      valueWindowEndsAt: undefined,
      recurringManualCostPerMonth: undefined,
      blocksCommittedLaunch: false,
    });

    expect(result.lane).toBe("needs_discovery");
    expect(result.missingEvidence).toContain("demand evidence");
  });
});

Add regression tests for previously reviewed items before changing weights. If a policy update moves them to another lane, reviewers should understand why.

Run triage as a portfolio conversation

Do not let the tool become a form that teams complete in isolation. Bring product, mobile engineering, security, operations, and the requesting business owner together for the first reviews.

Compare items that have similar evidence and timing. Record the chosen lane, policy version, reviewer, exceptions, and next review date. For rejected or deferred items, record the reason. A backlog becomes easier to manage when “later” has a stated condition rather than functioning as a permanent status.

Run the review at a predictable cadence, while allowing genuinely time-critical items to enter through a documented exception path. A weekly or fortnightly session is often frequent enough for new service requests. Core security incidents should follow their existing emergency process rather than wait for portfolio triage.

Review the distribution of decisions as well as individual results. If nearly every item lands in needs_discovery, the intake form or product discovery process may be weak. If everything is recommended for modular delivery, the scoring weights may be too permissive. If no item can pass the modular blockers, the organisation may lack the controls required for that lane or may be applying core-app rules unchanged.

For the first modular pilot, capture a baseline from the conventional route:

Request-to-release elapsed time.
Active implementation time versus waiting.
Number of handoffs and manual approvals.
Host-app engineering effort.
Change failures, recovery, and rework.
Customer completion and support demand.

Measure the same outcomes after the pilot. A faster release with poor completion or higher incident cost is not a successful result. A slightly faster release that frees core mobile capacity and makes rollback easier may still be valuable.

Treat the first decisions as calibration data. Ask which recommendations reviewers overruled and why. Add a missing policy field only when the same concern recurs; otherwise the intake will grow into a questionnaire that delays the work it was designed to route.

Evolve the lanes carefully

The first version of this engine should be small. Use it to make decisions inspectable and collect disagreements. Those disagreements reveal missing fields, unclear policies, or categories that are too broad.

Over time, add policy profiles for different markets or risk classes, evidence expiry, capability sensitivity, and integration with service manifests. Keep the business inputs visible. An increasingly sophisticated technical score should not conceal uncertain demand.

Most importantly, let the backlog determine whether a new lane is justified. If suitable items appear only once a year, a modular platform may cost more than it saves. If bounded, valuable services repeatedly miss their window because every change depends on the host release, a supported modular path can remove a recurring constraint.

The TypeScript is the easy part. The lasting value comes from agreeing on what each delivery lane is for, which risks cannot be averaged away, and which evidence turns a waiting request into a credible opportunity.

Build a Partner-Readiness Gate for an Internal Mini-App Platform in TypeScript

FinClip Super-App — Tue, 01 Sep 2026 06:44:15 +0000

Build a Partner-Readiness Gate for an Internal Mini-App Platform in TypeScript

An internal mini-app pilot can answer useful engineering questions before a host app opens to third-party developers. It can show whether teams can release independently, whether capability permissions are enforceable, and whether the platform can stop or roll back one service without disturbing the others.

It cannot prove that external onboarding, contracts, support, or partner exits will work. That transition deserves an explicit gate rather than a meeting in which each stakeholder brings a different definition of “ready.”

This tutorial builds a small TypeScript policy module for that gate. The module does not automate a business decision. It collects evidence, enforces a few non-negotiable conditions, and produces an explainable recommendation. It also keeps internal delivery evidence separate from obligations that begin when an independent organisation joins the platform.

Model stages before metrics

A maturity score becomes confusing when nobody agrees on the stage being assessed. Start by defining the operating states:

export type PlatformStage =
  | "internal_pilot"
  | "multi_team"
  | "invited_partner"
  | "broader_ecosystem";

export type Decision = "hold" | "advance";

Each transition answers a different question:

internal_pilot asks whether one bounded service can run safely and create a customer outcome.
multi_team asks whether another internal team can use the supported path without bespoke platform-team work.
invited_partner asks whether an independent organisation can onboard, operate, receive support, and exit under explicit rules.
broader_ecosystem asks whether those processes can support wider participation.

The code in this article focuses on the transition from multi_team to invited_partner. At that point, a platform should have credible internal evidence but may still lack external controls.

This stage model should live outside individual service repositories. A service team can provide evidence about its own ownership, permissions, release, and recovery behaviour, but it should not be able to redefine the platform's transition criteria. Keep the policy in a versioned governance repository or policy service, and record the version used for every decision.

It is also worth separating platform readiness from service acceptance. The platform may be ready to run an invited partner pilot while a particular partner service is unsuitable because it requests excessive data or has no support owner. Conversely, a carefully designed service cannot compensate for a platform that lacks independent credentials or removal controls. In practice, run two gates: one for the platform stage and another for every service release.

Store evidence, not opinions

A boolean named isReady tells reviewers very little. Readiness inputs should identify the evidence behind them. We can represent each check as an evidence item:

export interface EvidenceItem {
  passed: boolean;
  reference?: string;
  observedAt: string;
  owner: string;
}

export interface DeliveryMetrics {
  onboardingHours: number;
  manualInterventionRate: number;
  supportedPathAdoptionRate: number;
  changeFailureRate: number;
  medianRecoveryMinutes: number;
  documentationRequestsPerOnboarding: number;
}

export interface InternalEvidence {
  activeInternalTeams: number;
  customerOutcomeObserved: EvidenceItem;
  ownershipDeclared: EvidenceItem;
  capabilityAllowlistEnforced: EvidenceItem;
  dataPurposeDeclared: EvidenceItem;
  versionCompatibilityDefined: EvidenceItem;
  rollbackExercised: EvidenceItem;
  serviceRemovalExercised: EvidenceItem;
  incidentRouteTested: EvidenceItem;
  documentationUsedByNewTeam: EvidenceItem;
  unresolvedCriticalIncidents: number;
  metrics: DeliveryMetrics;
}

export interface ExternalControls {
  partnerDueDiligenceDefined: EvidenceItem;
  independentIdentityAndSigning: EvidenceItem;
  dataProcessingTermsApproved: EvidenceItem;
  partnerSupportModelApproved: EvidenceItem;
  commercialTermsApproved: EvidenceItem;
  terminationAndDataExitTested: EvidenceItem;
}

export interface ReadinessInput {
  currentStage: PlatformStage;
  internal: InternalEvidence;
  external: ExternalControls;
}

The reference can point to an immutable report, release record, policy version, incident exercise, or signed approval. Avoid placing sensitive customer data in this object. The module needs proof that evidence exists, not the confidential contents of the evidence.

observedAt also matters. A rollback demonstration from two years ago may not say much about the current runtime. Production systems change, so a real implementation should apply freshness rules to selected items.

Evidence references should be resolvable by reviewers and durable enough to survive staff changes. A chat message saying that a test passed is weak evidence. A release record containing the runtime version, service version, approver, result, and timestamp is much stronger. The same principle applies to onboarding studies: capture where the new team needed help, which documentation page it used, and whether the platform team performed an undocumented action.

Some evidence belongs at platform level and some at service level. An identity isolation test may apply to the runtime as a whole. A declared data purpose belongs to a specific service and version. Mixing those scopes creates stale approvals when one service changes. Add fields such as scope, serviceId, serviceVersion, and runtimeVersion when moving this example toward production.

Finally, evidence can expire for more than technical reasons. A contract template may change, a regional privacy requirement may be updated, or the support team may reorganise. Assign a policy owner to each evidence type and let that owner define when revalidation is required.

Do not average away hard blockers

Weighted scores are convenient but dangerous when a high score can hide a missing ownership record or an untested exit. Some conditions should stop the transition regardless of the average.

export interface ReadinessDecision {
  decision: Decision;
  score: number;
  blockers: string[];
  warnings: string[];
  evidenceReferences: string[];
}

function requireEvidence(
  item: EvidenceItem,
  message: string,
  blockers: string[],
): void {
  if (!item.passed) blockers.push(message);
}

function collectReferences(items: EvidenceItem[]): string[] {
  return items
    .map((item) => item.reference)
    .filter((value): value is string => Boolean(value));
}

Now define the hard blockers for the first invited partner:

function findBlockers(input: ReadinessInput): string[] {
  const blockers: string[] = [];
  const { internal, external } = input;

  if (input.currentStage !== "multi_team") {
    blockers.push("The platform must complete the multi-team stage first.");
  }

  if (internal.activeInternalTeams < 2) {
    blockers.push("At least two internal producer teams must use the platform.");
  }

  requireEvidence(
    internal.ownershipDeclared,
    "Every service needs a named operational owner.",
    blockers,
  );
  requireEvidence(
    internal.capabilityAllowlistEnforced,
    "Capability allowlists must be enforced by the runtime.",
    blockers,
  );
  requireEvidence(
    internal.rollbackExercised,
    "Rollback must be exercised, not merely documented.",
    blockers,
  );
  requireEvidence(
    internal.serviceRemovalExercised,
    "Service removal must be tested before partner onboarding.",
    blockers,
  );

  if (internal.unresolvedCriticalIncidents > 0) {
    blockers.push("Resolve critical platform incidents before opening further.");
  }

  requireEvidence(
    external.partnerDueDiligenceDefined,
    "Define partner due diligence and approval ownership.",
    blockers,
  );
  requireEvidence(
    external.independentIdentityAndSigning,
    "Provide independent partner identity, credentials, and signing.",
    blockers,
  );
  requireEvidence(
    external.dataProcessingTermsApproved,
    "Approve data-processing and permitted-purpose terms.",
    blockers,
  );
  requireEvidence(
    external.terminationAndDataExitTested,
    "Test partner termination and data-exit procedures.",
    blockers,
  );

  return blockers;
}

These rules are examples. A healthcare, financial-services, or public-sector platform will have additional blockers. The useful property is their visibility: reviewers can challenge a rule, assign an owner, and version the policy rather than arguing over an unexplained score.

Score the evidence that supports judgement

Once blockers are separate, a score can summarise softer signals. It should never override a blocker.

function clamp(value: number, min = 0, max = 1): number {
  return Math.min(max, Math.max(min, value));
}

function scoreInternalDelivery(evidence: InternalEvidence): number {
  const { metrics } = evidence;

  const onboarding = 1 - clamp(metrics.onboardingHours / 80);
  const selfService = 1 - clamp(metrics.manualInterventionRate);
  const standardPath = clamp(metrics.supportedPathAdoptionRate);
  const stability = 1 - clamp(metrics.changeFailureRate / 0.25);
  const recovery = 1 - clamp(metrics.medianRecoveryMinutes / 240);
  const documentation =
    1 - clamp(metrics.documentationRequestsPerOnboarding / 12);

  return (
    onboarding * 0.15 +
    selfService * 0.25 +
    standardPath * 0.25 +
    stability * 0.15 +
    recovery * 0.10 +
    documentation * 0.10
  );
}

The numbers are deliberately transparent. They are starting assumptions, not universal benchmarks. Teams should calibrate them against their own risk appetite and delivery history. For example, a four-hour recovery time may be unacceptable for a payment service and reasonable for a low-risk campaign tool.

The metrics also need interpretation. A low number of documentation questions could mean the docs are excellent, or that teams stopped trying. Combine delivery telemetry with interviews and observed onboarding sessions.

Calibrate by risk lane

One global threshold is rarely appropriate for every mini app. A read-only branch locator and a payment initiation service have different consequences. Add a risk classification before calculating readiness and let it choose the applicable policy profile.

A low-risk profile might accept a shorter observation period but still require ownership, capability allowlists, monitoring, and removal. A high-risk profile might require a recent recovery exercise, dual approval, stricter data controls, penetration-test evidence, and a lower tolerance for failed changes. The hard blockers should become stricter as consequence increases; they should not disappear because a service is expected to generate revenue.

Do not let service teams select the easiest lane without review. Risk classification should consider data sensitivity, financial impact, regulated activity, customer vulnerability, native capabilities, transaction reversibility, and the blast radius of an outage. Record the factors alongside the chosen lane so an auditor can understand the decision later.

Calibration is an operating exercise. Run the gate against several past releases and compare its result with what actually happened. If known problematic releases receive strong scores, inspect the missing evidence or poorly chosen threshold. If every release is blocked for the same administrative reason, decide whether the rule is essential, automatable, or written at the wrong scope. Keep the history; changing a threshold silently makes trend data misleading.

Produce an explainable result

The final assessor joins blockers, a threshold, and warnings:

const SCORE_THRESHOLD = 0.72;

export function assessPartnerReadiness(
  input: ReadinessInput,
): ReadinessDecision {
  const blockers = findBlockers(input);
  const score = scoreInternalDelivery(input.internal);
  const warnings: string[] = [];

  if (!input.internal.documentationUsedByNewTeam.passed) {
    warnings.push("Observe a new team onboarding from the published docs.");
  }

  if (!input.internal.customerOutcomeObserved.passed) {
    warnings.push("Confirm a customer outcome before expanding supply.");
  }

  if (!input.external.partnerSupportModelApproved.passed) {
    warnings.push("Approve escalation, incident, and complaint ownership.");
  }

  if (!input.external.commercialTermsApproved.passed) {
    warnings.push("Commercial terms remain open for the pilot.");
  }

  if (score < SCORE_THRESHOLD) {
    warnings.push(
      `Internal delivery score ${score.toFixed(2)} is below ${SCORE_THRESHOLD}.`,
    );
  }

  const evidenceReferences = collectReferences([
    ...Object.values(input.internal).filter(
      (value): value is EvidenceItem =>
        typeof value === "object" && value !== null && "passed" in value,
    ),
    ...Object.values(input.external),
  ]);

  return {
    decision:
      blockers.length === 0 && score >= SCORE_THRESHOLD
        ? "advance"
        : "hold",
    score,
    blockers,
    warnings,
    evidenceReferences,
  };
}

A production version should validate runtime input with a schema library, persist the policy version with each decision, and log who approved the transition. It should also prevent a service owner from approving their own evidence where separation of duties is required.

The output should be presented as a decision record, not just a console value. Include the current and proposed stage, policy version, evidence snapshot, blockers, warnings, exceptions, approvers, and an expiry date. If an exception is granted, give it an owner and deadline. Permanent undocumented exceptions eventually become a second release path that is harder to secure and support.

Avoid exposing sensitive evidence references to every developer. The readiness service can return a stable evidence identifier and verification status while limiting the underlying report to authorised reviewers. The decision needs traceability without becoming a directory of security findings or partner contract locations.

Test the policy boundary

Policy code needs tests because small edits can change a governance decision. Vitest works well for a compact TypeScript example:

import { describe, expect, it } from "vitest";
import { assessPartnerReadiness, ReadinessInput } from "./readiness";

const passed = (reference: string) => ({
  passed: true,
  reference,
  observedAt: "2026-08-20T09:00:00Z",
  owner: "platform-risk@example.test",
});

function readyInput(): ReadinessInput {
  return {
    currentStage: "multi_team",
    internal: {
      activeInternalTeams: 3,
      customerOutcomeObserved: passed("report://customer-outcome/42"),
      ownershipDeclared: passed("registry://services/v18"),
      capabilityAllowlistEnforced: passed("test://runtime/allowlist/91"),
      dataPurposeDeclared: passed("registry://data-purpose/v12"),
      versionCompatibilityDefined: passed("policy://compatibility/v4"),
      rollbackExercised: passed("drill://rollback/2026-08"),
      serviceRemovalExercised: passed("drill://removal/2026-08"),
      incidentRouteTested: passed("drill://incident/2026-08"),
      documentationUsedByNewTeam: passed("study://onboarding/team-c"),
      unresolvedCriticalIncidents: 0,
      metrics: {
        onboardingHours: 18,
        manualInterventionRate: 0.08,
        supportedPathAdoptionRate: 0.94,
        changeFailureRate: 0.04,
        medianRecoveryMinutes: 28,
        documentationRequestsPerOnboarding: 2,
      },
    },
    external: {
      partnerDueDiligenceDefined: passed("policy://partners/v3"),
      independentIdentityAndSigning: passed("test://partner-iam/77"),
      dataProcessingTermsApproved: passed("legal://dpa/template-v5"),
      partnerSupportModelApproved: passed("runbook://partner-support/v2"),
      commercialTermsApproved: passed("legal://pilot-terms/v2"),
      terminationAndDataExitTested: passed("drill://partner-exit/2026-08"),
    },
  };
}

describe("partner readiness", () => {
  it("advances when evidence and delivery signals are sufficient", () => {
    const result = assessPartnerReadiness(readyInput());
    expect(result.decision).toBe("advance");
    expect(result.blockers).toEqual([]);
  });

  it("holds when rollback has not been exercised", () => {
    const input = readyInput();
    input.internal.rollbackExercised = {
      ...input.internal.rollbackExercised,
      passed: false,
    };

    const result = assessPartnerReadiness(input);
    expect(result.decision).toBe("hold");
    expect(result.blockers).toContain(
      "Rollback must be exercised, not merely documented.",
    );
  });

  it("does not let a strong score cancel a missing data agreement", () => {
    const input = readyInput();
    input.external.dataProcessingTermsApproved = {
      ...input.external.dataProcessingTermsApproved,
      passed: false,
    };

    const result = assessPartnerReadiness(input);
    expect(result.score).toBeGreaterThan(0.72);
    expect(result.decision).toBe("hold");
  });
});

The last test captures the most important design choice: excellent internal delivery performance cannot compensate for a missing external obligation.

Run the gate as a process

Code alone does not create governance. Connect it to a small operating routine:

Service and platform owners attach evidence references.
Security, privacy, operations, legal, and product owners review the checks they own.
The assessor runs against a versioned policy.
Reviewers discuss blockers and warnings separately.
The decision, exceptions, expiry date, and approvers are recorded.
A limited partner pilot is reassessed after its first release and exit exercise.

Reassessing matters because partner readiness is not permanent. Documentation, runtime versions, support arrangements, and regulations change. A gate should be triggered by meaningful platform changes as well as calendar intervals.

The invited pilot itself should generate new evidence. Track the time a partner spends waiting for access, the number of undocumented questions, support handoffs, rejected capability requests, integration defects, and any manual steps performed by employees. Run a suspension and exit exercise before declaring the pilot complete. A successful first release shows that the service can launch; an orderly exit shows that the host can retain control when the relationship changes.

Keep the pilot deliberately narrow. Limit the first partner's capability set, audience, data access, and transaction types. Feature flags and independent kill controls make this boundary enforceable. Expansion can follow after the team has reviewed production behaviour and closed the gaps found during onboarding.

What this gate tells you

An internal mini-app programme is a strong source of operational evidence. It can demonstrate repeatable onboarding, scoped capabilities, release safety, and customer value. The partner gate prevents that evidence from being stretched beyond what it supports.

The resulting decision is intentionally modest. It says whether the platform has met the organisation's current conditions for an invited partner pilot. It does not predict marketplace demand or guarantee a successful ecosystem.

That modesty is useful. Teams can see why a decision was made, which conditions are mandatory, and what work remains. The first external partner then enters a platform with a tested delivery path and a clear list of new obligations, rather than becoming the experiment that discovers both at once.

Build a Partner-Service Placement Decision Engine in TypeScript

FinClip Super-App — Mon, 31 Aug 2026 02:06:11 +0000

Build a Partner-Service Placement Decision Engine in TypeScript

Partner ecosystems create an architectural choice before they create an integration task. Should a service run inside the host app, open through a controlled deep link, or remain a separate application?

Treating every useful partner as an embedding candidate creates a crowded product and a growing third-party risk surface. Treating every partner as an external link preserves isolation but can leave customers repeating authentication, context, and payment steps.

This tutorial builds a small TypeScript decision engine for comparing the three models. It uses hard gates for conditions that must not be averaged away, followed by explainable signals for the candidates that pass. The policy is illustrative; adapt the thresholds and evidence requirements to your organization, market, and regulatory obligations.

Model the three outcomes

The engine returns one of three placements:

embed: run the partner service within the host experience, for example as a mini app;
handoff: use a verified app link, universal link, or secure browser flow;
separate: keep a dedicated app because the audience or operating boundary is distinct.

export type Placement = "embed" | "handoff" | "separate";

export type Score = 0 | 1 | 2 | 3 | 4 | 5;

export interface PartnerServiceCandidate {
  id: string;
  name: string;

  // Product signals
  journeyContinuity: Score;
  hostCapabilityValue: Score;
  usageFrequency: Score;
  consequenceWhenNeeded: Score;
  distinctAudience: Score;
  specialistExperienceDepth: Score;

  // Operational readiness
  dueDiligenceComplete: boolean;
  supportOwnerAssigned: boolean;
  dataPurposeApproved: boolean;
  exitPlanTested: boolean;
  runtimeMonitoringAvailable: boolean;

  requestedCapabilities: string[];
  allowedCapabilities: string[];
}

export interface PlacementDecision {
  candidateId: string;
  placement: Placement;
  eligibleToEmbed: boolean;
  blockers: string[];
  reasons: string[];
  scores: {
    embed: number;
    handoff: number;
    separate: number;
  };
  policyVersion: string;
  evaluatedAt: string;
}

Keeping product signals separate from operational readiness matters. A service can be highly relevant and still be unfit for embedding because its data purpose is unclear or nobody owns customer complaints.

Add categorical embedding gates

Start with conditions that block the embedded model. Do not represent them as negative points in a weighted average.

function embeddingBlockers(
  candidate: PartnerServiceCandidate,
): string[] {
  const blockers: string[] = [];

  if (!candidate.dueDiligenceComplete) {
    blockers.push("Third-party due diligence is incomplete");
  }

  if (!candidate.supportOwnerAssigned) {
    blockers.push("No owner is assigned for customer support and complaints");
  }

  if (!candidate.dataPurposeApproved) {
    blockers.push("The purpose for partner data access is not approved");
  }

  if (!candidate.exitPlanTested) {
    blockers.push("The service exit and withdrawal plan has not been tested");
  }

  const unapproved = candidate.requestedCapabilities.filter(
    (capability) => !candidate.allowedCapabilities.includes(capability),
  );

  if (unapproved.length > 0) {
    blockers.push(`Unapproved host capabilities: ${unapproved.join(", ")}`);
  }

  return blockers;
}

These rules answer a narrow question: can the service be considered for embedding today? A blocker does not necessarily reject the partnership. It may route the first release to a handoff while the teams complete due diligence or redesign the permission request.

Score the placement signals

For eligible candidates, calculate three explainable scores. The weights below express a policy choice: journey continuity and host capability value matter most for embedding; a distinct audience and deep specialist workflow favor a separate app.

function placementScores(candidate: PartnerServiceCandidate) {
  const embed =
    candidate.journeyContinuity * 3 +
    candidate.hostCapabilityValue * 3 +
    candidate.usageFrequency * 2 +
    candidate.consequenceWhenNeeded +
    (candidate.runtimeMonitoringAvailable ? 3 : 0) -
    candidate.distinctAudience * 2;

  const handoff =
    (5 - candidate.hostCapabilityValue) * 2 +
    (5 - candidate.usageFrequency) +
    candidate.specialistExperienceDepth * 2 +
    (5 - candidate.journeyContinuity);

  const separate =
    candidate.distinctAudience * 3 +
    candidate.specialistExperienceDepth * 3 +
    (5 - candidate.journeyContinuity) * 2;

  return { embed, handoff, separate };
}

The score is not a universal truth. Its purpose is to make tradeoffs visible. Product, architecture, operations, and risk teams can challenge a weight or an input instead of arguing from different unstated assumptions.

Build an explainable evaluator

If embedding is blocked, choose between handoff and separate using the remaining scores. If it is eligible, select the highest score and record the main reasons.

const POLICY_VERSION = "2026-08-31.1";

function maxPlacement(
  scores: PlacementDecision["scores"],
  options: Placement[],
): Placement {
  return options.reduce((best, current) =>
    scores[current] > scores[best] ? current : best,
  );
}

function explain(
  candidate: PartnerServiceCandidate,
  placement: Placement,
): string[] {
  const reasons: string[] = [];

  if (candidate.journeyContinuity >= 4) {
    reasons.push("The service continues a task already underway in the host");
  }

  if (candidate.hostCapabilityValue >= 4) {
    reasons.push("Host identity, payment, or context materially improves the task");
  }

  if (candidate.specialistExperienceDepth >= 4) {
    reasons.push("The partner owns a deep specialist workflow");
  }

  if (candidate.distinctAudience >= 4) {
    reasons.push("The service has a substantially different primary audience");
  }

  if (placement === "handoff") {
    reasons.push("A controlled link preserves the partner experience with less coupling");
  }

  if (placement === "embed" && candidate.runtimeMonitoringAvailable) {
    reasons.push("The host can monitor and withdraw the embedded service");
  }

  return reasons;
}

export function decidePlacement(
  candidate: PartnerServiceCandidate,
  now = new Date(),
): PlacementDecision {
  const blockers = embeddingBlockers(candidate);
  const scores = placementScores(candidate);
  const eligibleToEmbed = blockers.length === 0;

  const options: Placement[] = eligibleToEmbed
    ? ["embed", "handoff", "separate"]
    : ["handoff", "separate"];

  const placement = maxPlacement(scores, options);

  return {
    candidateId: candidate.id,
    placement,
    eligibleToEmbed,
    blockers,
    reasons: explain(candidate, placement),
    scores,
    policyVersion: POLICY_VERSION,
    evaluatedAt: now.toISOString(),
  };
}

Tie-breaking deserves an explicit policy. The implementation above keeps the first option when scores tie, which favors embedding only after all gates pass. A more conservative organization may prefer handoff on every tie.

Evaluate three services

An in-journey assistance service uses host context, has high consequence, and meets the operational gates.

const cardTravelHelp: PartnerServiceCandidate = {
  id: "svc-card-travel-help",
  name: "Card Travel Assistance",
  journeyContinuity: 5,
  hostCapabilityValue: 5,
  usageFrequency: 2,
  consequenceWhenNeeded: 5,
  distinctAudience: 1,
  specialistExperienceDepth: 2,
  dueDiligenceComplete: true,
  supportOwnerAssigned: true,
  dataPurposeApproved: true,
  exitPlanTested: true,
  runtimeMonitoringAvailable: true,
  requestedCapabilities: ["identity.basic", "card.event.read"],
  allowedCapabilities: ["identity.basic", "card.event.read"],
};

console.log(decidePlacement(cardTravelHelp));
// placement: "embed"

A specialist booking provider has a deep experience but receives limited value from host capabilities.

const holidayBooking: PartnerServiceCandidate = {
  id: "svc-holiday-booking",
  name: "Holiday Booking",
  journeyContinuity: 1,
  hostCapabilityValue: 1,
  usageFrequency: 1,
  consequenceWhenNeeded: 2,
  distinctAudience: 2,
  specialistExperienceDepth: 5,
  dueDiligenceComplete: true,
  supportOwnerAssigned: true,
  dataPurposeApproved: true,
  exitPlanTested: true,
  runtimeMonitoringAvailable: false,
  requestedCapabilities: [],
  allowedCapabilities: [],
};

console.log(decidePlacement(holidayBooking));
// placement: "handoff"

A service with a separate professional audience and sustained specialist workflow belongs in its own app.

const merchantOperations: PartnerServiceCandidate = {
  id: "svc-merchant-operations",
  name: "Merchant Operations Suite",
  journeyContinuity: 1,
  hostCapabilityValue: 2,
  usageFrequency: 5,
  consequenceWhenNeeded: 4,
  distinctAudience: 5,
  specialistExperienceDepth: 5,
  dueDiligenceComplete: true,
  supportOwnerAssigned: true,
  dataPurposeApproved: true,
  exitPlanTested: true,
  runtimeMonitoringAvailable: true,
  requestedCapabilities: ["merchant.identity"],
  allowedCapabilities: ["merchant.identity"],
};

console.log(decidePlacement(merchantOperations));
// placement: "separate"

Test blockers, not only happy paths

Use Vitest or another test runner to protect the policy’s important behavior.

import { describe, expect, it } from "vitest";
import { decidePlacement } from "./partner-placement";

describe("partner-service placement", () => {
  it("embeds a ready service that continues a host journey", () => {
    const result = decidePlacement(cardTravelHelp);
    expect(result.placement).toBe("embed");
    expect(result.eligibleToEmbed).toBe(true);
  });

  it("blocks embedding when a capability is not approved", () => {
    const candidate = {
      ...cardTravelHelp,
      requestedCapabilities: ["identity.basic", "location.precise"],
    };

    const result = decidePlacement(candidate);
    expect(result.eligibleToEmbed).toBe(false);
    expect(result.blockers.join(" ")).toContain("location.precise");
    expect(result.placement).not.toBe("embed");
  });

  it("does not embed without a customer-support owner", () => {
    const candidate = {
      ...cardTravelHelp,
      supportOwnerAssigned: false,
    };

    const result = decidePlacement(candidate);
    expect(result.eligibleToEmbed).toBe(false);
  });

  it("records the policy version", () => {
    const result = decidePlacement(holidayBooking);
    expect(result.policyVersion).toBe("2026-08-31.1");
  });
});

Add boundary tests for every score, ties, unknown capabilities, missing fields, expired due diligence, unavailable monitoring, and changes in policy version. Validate incoming JSON before it reaches the evaluator so an unexpected value such as 6 cannot bypass the TypeScript type at runtime.

Keep the decision attached to evidence

A boolean field called dueDiligenceComplete is enough for the example, but production systems should store evidence references. Record who approved the assessment, what activity and data flow it covers, when it expires, and which provider version was assessed.

Do the same for support ownership and exit testing. An exit plan is meaningful only if the platform can identify active versions, stop new sessions, handle customers already in the journey, revoke capabilities, preserve records, and display an appropriate replacement or unavailable state.

Store each placement decision with the service manifest, policy version, capability list, scores, blockers, and evidence digests. Re-evaluate when any material input changes. A previously approved provider should not inherit approval for a new data category or a newly acquired subcontractor.

Separate identity federation from data permission

Single sign-on can improve a partner journey, but successful authentication should not grant the partner access to the customer's host profile. Treat identity federation and data authorization as separate decisions.

Issue a token with the smallest audience and scope the partner needs. Keep it short-lived, bind it to the intended service, and avoid placing reusable credentials in URLs or client-side storage. If the partner needs a customer attribute, expose a purpose-specific claim or API instead of sharing the host session or a complete profile object.

The service manifest should declare:

the identity subject it needs;
every requested data field and capability;
the business purpose and retention period;
whether the partner or host is the system of record;
the user-consent and revocation experience;
where audit and customer-support records will live.

These declarations can feed both the placement evaluator and runtime enforcement. A handoff can still use federated identity, while an embedded mini app may receive no customer data at all until the user starts a specific action.

Model provider failure as part of the placement

Partner availability is part of the host experience once a service is promoted or embedded. Decide what the customer sees when the provider is slow, unavailable, returning incomplete data, or operating in only some regions.

For embedded services, use timeouts, circuit breakers, health signals, and a host-controlled unavailable state. Avoid letting a partner error expose internal messages or leave the host navigation blocked. The host should be able to disable entry points for affected audiences without waiting for the provider to publish a fix.

For handoffs, validate the destination before promoting it and monitor completion callbacks where the relationship permits them. If the host cannot observe task completion, state that limitation in the measurement model rather than treating a click as success.

Separate applications still need coordinated incident communication when the host brand promotes them. The placement boundary reduces technical coupling; it does not make customer confusion disappear.

Add contract and geography events to re-evaluation

Technical inputs are only part of the lifecycle. A commercial change can alter the appropriate placement. Re-run the policy when pricing, liability, service levels, data-processing locations, subcontractors, supported countries, or termination rights change.

For multi-market hosts, evaluate placement per market. One provider may qualify for embedding in a country where it is licensed, supported, and locally monitored, while the same service requires a handoff or must remain unavailable elsewhere. Store the market and policy jurisdiction in the decision record so a global approval cannot silently override local restrictions.

An automated expiry date is useful. When evidence or a contract reaches its review date, block new expansion and notify the owner. Existing customers may need a managed transition rather than immediate shutdown, so the policy should distinguish distribution to new users from continued service for active cases.

Implement each model deliberately

The evaluator chooses a product boundary; it does not implement the boundary.

For an embedded mini app, enforce a capability allowlist at runtime. Give each service an owner, signed package, version, rollout audience, health status, and remote suspension control. Capture consent at the point where the partner requests data or a device permission.

For a handoff, allowlist destinations and use verified links. Send the customer to the specific task, show that the destination is changing, minimize data in URL parameters, and provide a return path. Measure whether customers complete the partner task rather than counting outbound clicks alone.

For a separate app, make the value proposition and audience explicit. Avoid silent account coupling. If the host promotes or pre-fills the separate service, declare the data transfer and support boundary with the same care used for an embedded journey.

Treat placement as a reversible product decision

Do not freeze the outcome in a slide deck. Begin with the least complex model that can test the customer value. A handoff may reveal genuine demand but high abandonment at repeated authentication. That evidence can justify an embedded pilot. An embedded service may develop a distinct audience and operational model that later supports a dedicated app.

Track task completion, abandonment, repeated authentication, time to complete, support contacts, complaints, service availability, incident rate, and cost per completed task. Review these alongside the partner’s commercial performance.

The decision engine gives teams a shared language for that review. It prevents “seamless” from becoming an unsupported architectural preference and prevents risk concerns from turning every partner into a generic external link. Each service earns its place through the customer task it improves, the capabilities it needs, and the responsibility the host is ready to sustain.

Build Risk-Based Release Gates for Mini Apps in TypeScript

FinClip Super-App — Fri, 28 Aug 2026 06:50:16 +0000

Build Risk-Based Release Gates for Mini Apps in TypeScript

Mini-app platforms can shorten the path from a business idea to a customer-facing service. That advantage disappears when every release enters the same manual approval queue. It also becomes dangerous when teams respond by bypassing the queue.

A better release system distinguishes routine changes from changes that alter the host application's risk boundary. Low-risk work can proceed through a self-service path after automated checks. A new service using approved capabilities may require a platform review. New payment, identity, data, or native-device access should reach security and risk specialists.

This article builds a small TypeScript policy evaluator for those three lanes. The rules are examples, not a compliance standard. The important design choices are:

release requests declare their intent and evidence;
certain conditions are categorical blockers;
policy decisions are deterministic and auditable;
a low score never cancels an unapproved capability;
policy evaluation stays separate from deployment execution.

Model the release request

Start with explicit types. Free-form tickets are difficult to validate consistently, so the request should name the change types, data classes, host capabilities, evidence, and people involved.

type ChangeType =
  | "content"
  | "configuration"
  | "new_service"
  | "host_api"
  | "payment"
  | "identity";

type DataClass = "public" | "internal" | "personal" | "sensitive";

type Evidence =
  | "owner_declared"
  | "schema_valid"
  | "tests_passed"
  | "security_scan_passed"
  | "artifact_signed"
  | "rollback_ready"
  | "monitoring_ready"
  | "privacy_assessment";

type ReleaseLane =
  | "self_service"
  | "platform_review"
  | "security_review";

interface ChangeRequest {
  requestId: string;
  serviceId: string;
  requestedBy: string;
  approvedBy?: string;
  changeTypes: ChangeType[];
  dataClasses: DataClass[];
  requestedCapabilities: string[];
  automatedEvidence: Evidence[];
  templateId?: string;
}

interface PolicyContext {
  approvedTemplates: Set<string>;
  allowlistedCapabilities: Set<string>;
}

interface PolicyDecision {
  requestId: string;
  lane: ReleaseLane;
  allowed: boolean;
  reasons: string[];
  missingEvidence: Evidence[];
  evaluatedAt: string;
  policyVersion: string;
}

The approvedBy field is optional because a self-service request may not need a human approver. When an approval is required, the evaluator will prevent the requester from approving their own release.

Define evidence by lane

Each lane requires a different evidence set. The standard path should still prove ownership, validity, testing, integrity, and recoverability.

const EVIDENCE_BY_LANE: Record<ReleaseLane, Evidence[]> = {
  self_service: [
    "owner_declared",
    "schema_valid",
    "tests_passed",
    "artifact_signed",
    "rollback_ready",
  ],
  platform_review: [
    "owner_declared",
    "schema_valid",
    "tests_passed",
    "security_scan_passed",
    "artifact_signed",
    "rollback_ready",
    "monitoring_ready",
  ],
  security_review: [
    "owner_declared",
    "schema_valid",
    "tests_passed",
    "security_scan_passed",
    "artifact_signed",
    "rollback_ready",
    "monitoring_ready",
    "privacy_assessment",
  ],
};

In a real system, evidence should refer to immutable results: a build identifier, scan report digest, test run, signature, policy version, and deployment candidate. A boolean typed into a form is a declaration, not proof.

Classify boundary changes first

The evaluator should look for hard boundaries before considering convenience or speed. New payment and identity behavior always enter the security-review lane in this example. So do sensitive data and capabilities outside the host allowlist.

function includesAny<T>(items: T[], candidates: T[]): boolean {
  return candidates.some((candidate) => items.includes(candidate));
}

function classifyLane(
  request: ChangeRequest,
  context: PolicyContext,
): { lane: ReleaseLane; reasons: string[] } {
  const reasons: string[] = [];

  const unapprovedCapabilities = request.requestedCapabilities.filter(
    (capability) => !context.allowlistedCapabilities.has(capability),
  );

  if (unapprovedCapabilities.length > 0) {
    reasons.push(
      `Unapproved capabilities: ${unapprovedCapabilities.join(", ")}`,
    );
  }

  if (includesAny(request.changeTypes, ["payment", "identity"])) {
    reasons.push("Payment or identity boundary changes require security review");
  }

  if (request.dataClasses.includes("sensitive")) {
    reasons.push("Sensitive data use requires security and privacy review");
  }

  if (reasons.length > 0) {
    return { lane: "security_review", reasons };
  }

  const isTemplateApproved =
    request.templateId !== undefined &&
    context.approvedTemplates.has(request.templateId);

  const onlyRoutineChanges = request.changeTypes.every((change) =>
    ["content", "configuration"].includes(change),
  );

  const dataStaysRoutine = request.dataClasses.every((dataClass) =>
    ["public", "internal"].includes(dataClass),
  );

  if (isTemplateApproved && onlyRoutineChanges && dataStaysRoutine) {
    return {
      lane: "self_service",
      reasons: ["Change stays within an approved template and risk boundary"],
    };
  }

  return {
    lane: "platform_review",
    reasons: ["New service or non-routine change within approved capabilities"],
  };
}

This function deliberately avoids a numeric score. An unapproved camera API should not become acceptable because the change also has good test coverage. Tests and permissions answer different questions.

Evaluate evidence and separation of duties

Classification decides who needs to inspect a release. Authorization decides whether it may proceed now.

const POLICY_VERSION = "2026-08-28.1";

function missingEvidence(
  lane: ReleaseLane,
  supplied: Evidence[],
): Evidence[] {
  return EVIDENCE_BY_LANE[lane].filter(
    (required) => !supplied.includes(required),
  );
}

export function evaluateRelease(
  request: ChangeRequest,
  context: PolicyContext,
  now = new Date(),
): PolicyDecision {
  const classification = classifyLane(request, context);
  const missing = missingEvidence(
    classification.lane,
    request.automatedEvidence,
  );

  const reasons = [...classification.reasons];

  if (missing.length > 0) {
    reasons.push(`Missing evidence: ${missing.join(", ")}`);
  }

  const needsHumanApproval = classification.lane !== "self_service";
  const hasApproval = request.approvedBy !== undefined;
  const selfApproval =
    hasApproval && request.approvedBy === request.requestedBy;

  if (needsHumanApproval && !hasApproval) {
    reasons.push("The selected lane requires a named approver");
  }

  if (selfApproval) {
    reasons.push("Requester and approver must be different people");
  }

  const allowed =
    missing.length === 0 &&
    (!needsHumanApproval || hasApproval) &&
    !selfApproval;

  return {
    requestId: request.requestId,
    lane: classification.lane,
    allowed,
    reasons,
    missingEvidence: missing,
    evaluatedAt: now.toISOString(),
    policyVersion: POLICY_VERSION,
  };
}

The result explains the decision. Store it next to the artifact digest and deployment record. An auditor or incident responder should be able to reconstruct which policy ran, which evidence existed, and why the lane was selected.

Try three requests

Create a small policy context and a helper containing the evidence required by the standard path.

const context: PolicyContext = {
  approvedTemplates: new Set(["campaign-v3", "service-card-v2"]),
  allowlistedCapabilities: new Set([
    "analytics.read",
    "notifications.send",
    "profile.basic.read",
  ]),
};

const standardEvidence: Evidence[] = [
  "owner_declared",
  "schema_valid",
  "tests_passed",
  "artifact_signed",
  "rollback_ready",
];

const campaign: ChangeRequest = {
  requestId: "rel-101",
  serviceId: "summer-rewards",
  requestedBy: "business:rewards-team",
  changeTypes: ["content", "configuration"],
  dataClasses: ["public"],
  requestedCapabilities: ["analytics.read"],
  automatedEvidence: standardEvidence,
  templateId: "campaign-v3",
};

console.log(evaluateRelease(campaign, context));
// lane: self_service, allowed: true

A new service using approved capabilities enters platform review. It needs additional evidence and a separate approver.

const service: ChangeRequest = {
  requestId: "rel-102",
  serviceId: "appointment-booking",
  requestedBy: "product:local-services",
  approvedBy: "platform:on-call-owner",
  changeTypes: ["new_service"],
  dataClasses: ["personal"],
  requestedCapabilities: ["profile.basic.read", "notifications.send"],
  automatedEvidence: [
    ...standardEvidence,
    "security_scan_passed",
    "monitoring_ready",
  ],
};

console.log(evaluateRelease(service, context));
// lane: platform_review, allowed: true

An unapproved native capability moves directly to security review. Missing privacy evidence blocks it.

const identityService: ChangeRequest = {
  requestId: "rel-103",
  serviceId: "partner-identity-check",
  requestedBy: "partner:onboarding-team",
  approvedBy: "security:reviewer",
  changeTypes: ["identity", "host_api"],
  dataClasses: ["sensitive"],
  requestedCapabilities: ["camera.native", "profile.basic.read"],
  automatedEvidence: [
    ...standardEvidence,
    "security_scan_passed",
    "monitoring_ready",
  ],
};

console.log(evaluateRelease(identityService, context));
// lane: security_review, allowed: false
// missingEvidence includes privacy_assessment

Test the rules, including the uncomfortable cases

Policy code deserves tests that protect its safety properties. Vitest works well for this small example.

import { describe, expect, it } from "vitest";
import { evaluateRelease } from "./release-policy";

describe("release policy", () => {
  it("allows a complete routine campaign on the self-service lane", () => {
    const decision = evaluateRelease(campaign, context);
    expect(decision.lane).toBe("self_service");
    expect(decision.allowed).toBe(true);
  });

  it("routes an unapproved capability to security review", () => {
    const decision = evaluateRelease(identityService, context);
    expect(decision.lane).toBe("security_review");
    expect(decision.allowed).toBe(false);
    expect(decision.reasons.join(" ")).toContain("camera.native");
  });

  it("rejects self-approval on a reviewed lane", () => {
    const request = {
      ...service,
      approvedBy: service.requestedBy,
    };

    const decision = evaluateRelease(request, context);
    expect(decision.allowed).toBe(false);
    expect(decision.reasons).toContain(
      "Requester and approver must be different people",
    );
  });

  it("records the policy version for audit", () => {
    const decision = evaluateRelease(campaign, context);
    expect(decision.policyVersion).toBe("2026-08-28.1");
  });
});

Add tests for empty fields, unknown change types at the API boundary, policy-version migrations, unavailable evidence providers, expired approvals, and emergency rollback. Treat an evaluation error as a blocked release. A policy service that fails open can turn an operational incident into a security incident.

Keep evaluation separate from deployment

The evaluator should not deploy the mini app. Instead, return a signed or otherwise tamper-evident decision that the deployment controller verifies. This separation makes it easier to test the policy and restrict deployment credentials.

A production flow might look like this:

The build pipeline produces a signed artifact and evidence references.
The requester submits a structured change manifest.
The policy service selects a lane and reports missing requirements.
Human approval is added only when the lane requires it.
The policy is evaluated again against the immutable artifact.
The deployment controller verifies the decision and promotes the artifact.
Runtime monitoring records health, version, audience, and capability use.
Rollback or remote suspension remains available to the host operator.

Re-evaluation is important. An approval for artifact A must not authorize artifact B, even if the service ID is unchanged.

Treat capabilities as contracts, not strings

The example uses a Set<string> to keep the code readable. A production capability registry should carry enough metadata for a meaningful decision. Each capability can declare its owner, supported versions, data classification, permitted service types, consent requirement, rate limit, and default review lane.

For example, profile.basic.read might expose only a stable customer identifier and display name. profile.financial.read would represent a different data boundary and should not inherit the same policy merely because both names begin with profile.

Version the capability contract as well as the policy. If a host API starts returning an additional field, existing mini apps should not receive it silently. The platform can keep the old contract available, require explicit adoption of the new version, and run the release evaluator again. That turns capability access into a reviewable dependency rather than an ambient privilege.

The registry should also reject unknown capabilities by default. Avoid wildcard permissions such as device.* or profile.* unless the runtime can expand and record the exact operations used. Broad scopes make the initial integration convenient but weaken both audit evidence and incident containment.

Make evidence verifiable and short-lived

Evidence has a lifecycle. A security scan from last month may say little about an artifact built today. A privacy assessment may cover one data flow but not a newly added partner destination. An approval can also expire when the service owner, policy, artifact, or capability contract changes.

Instead of storing only evidence names, use references with at least these fields:

evidence type and producer;
artifact or source revision covered;
result and relevant findings;
creation and expiry timestamps;
integrity digest or signature;
policy version that requested it.

The evaluator can then require fresh, matching evidence. This also prevents a subtle failure mode in which a team attaches a successful test result from a different build.

Keep policy results immutable. If a reviewer grants an exception, record the exact blocker, compensating control, owner, expiration date, and affected artifact. Future policy runs can recognize the exception without erasing the reason it existed. An expired exception should fail closed and return to its normal lane.

Design the runtime response before enabling self-service

Release authorization is only one moment in the service lifecycle. The host application remains responsible for what runs inside it, so the platform needs post-release controls that operate at mini-app speed.

At minimum, record the active service version, audience, requested capabilities, health state, and current owner. Support progressive exposure through employee, pilot, percentage, and general-availability stages. Connect health thresholds to an automatic pause or rollback where the failure is unambiguous, and provide a human-operated suspension control for cases involving fraud, privacy, harmful content, or partner failure.

Test that control regularly. A kill switch that depends on an unavailable admin service or an outdated service identifier offers false reassurance. Recovery exercises should verify that the platform can stop new sessions, handle active sessions safely, preserve evidence, notify owners, and restore a known-good version.

Emergency changes need their own explicit path. They may relax normal timing or approval requirements, but they should tighten observability, scope, expiry, and retrospective review. Hiding emergency behavior inside the standard lane corrupts the data used to improve the policy.

Protect the policy service itself

Once deployments depend on this evaluator, its repository and runtime become high-value control points. Require reviewed changes to policy code, signed releases, least-privilege credentials, and an append-only decision log. Separate the people who change policy from the people who deploy services where regulation or internal policy requires it.

Monitor the evaluator for unavailable evidence providers, unusual approval patterns, repeated exception requests, and sudden shifts between lanes. A surge in security-review classifications may indicate a real product change, an overly broad new capability, or a broken registry. Policy metrics should start an investigation, not automatically loosen the boundary.

Evolve the policy from real release history

Do not begin with hundreds of rules. Review recent releases and find a frequent, low-risk pattern with repeated checks. A seasonal campaign or simple service page can be a good first candidate. Encode the smallest useful standard path, observe failures and exceptions, then expand it.

Measure throughput and stability together. Lead time and approval waiting time show whether the path is faster. Change failure, rollback, recovery time, and rework show whether it remains safe. Also track the share of requests using each lane and the reasons for escalation. If most “standard” releases require exceptions, the path may not reflect actual work.

Risk-based gates make routine governance decisions repeatable and reserve specialist attention for boundary changes. For a mini-app platform, that is the foundation of useful self-service: teams can move quickly because the host already knows the limits, captures the evidence, and can recover when a release behaves unexpectedly.

One Host App, Many Markets: Build a TypeScript Policy Resolver

FinClip Super-App — Thu, 27 Aug 2026 05:54:33 +0000

One Host App, Many Markets: Build a TypeScript Policy Resolver

Multi-market mobile apps often begin with a shared codebase and end with country branches hidden inside conditionals.

if (country === "SG") {
  // one payment flow
} else if (country === "GB") {
  // another consent screen
}

This works until market, product, regulation, client version, and service availability begin changing independently. The host app becomes the place where every local decision is implemented and every market must join the same release train.

A modular platform needs a different boundary. The host should expose stable capabilities. A versioned market policy should describe which local implementations and services are available. Mini apps consume the resolved policy without embedding country-specific assumptions.

In this tutorial, we will build a TypeScript policy resolver that supports:

global capability contracts;
market-specific locales, currencies, and time zones;
approved identity and payment providers;
service availability and minimum host versions;
consent-policy versions;
capability restrictions by market;
explicit validation and deterministic precedence.

The code is deliberately small enough to understand. A production implementation would add signed policy bundles, remote configuration delivery, audit history, staged rollout, and operational tooling.

Model stable capabilities first

The global platform should define the capabilities services can request. Their implementations may vary by market.

Create market-policy.ts:

export type Capability =
  | "identity.profile"
  | "identity.verify"
  | "payments.create"
  | "payments.refund"
  | "analytics.emit"
  | "location.coarse"
  | "storage.secure";

export type ProviderKind = "identity" | "payment";

export interface Provider {
  id: string;
  kind: ProviderKind;
  enabled: boolean;
  capabilities: Capability[];
}

export interface ServicePolicy {
  serviceId: string;
  enabled: boolean;
  minimumHostVersion: string;
  requiredCapabilities: Capability[];
  allowedAudienceSegments: string[];
}

export interface MarketPolicy {
  market: string;
  revision: number;
  locales: string[];
  defaultLocale: string;
  currencies: string[];
  timeZone: string;
  consentPolicyVersion: string;
  providers: Provider[];
  deniedCapabilities: Capability[];
  services: ServicePolicy[];
  effectiveFrom: string;
}

The market code should be an agreed identifier, ideally an ISO country or operating-market code. Locale identifiers should use a consistent standard such as BCP 47. Do not use one free-form language field for locale, market, and regulatory jurisdiction; they are related but different.

deniedCapabilities gives the market a way to narrow the global surface. A capability can exist in the host and still be unavailable in a jurisdiction because the required provider, permission, or approval is absent.

Keep defaults conservative

A global default should provide structural expectations, not silently enable market-sensitive functionality.

export interface GlobalPolicy {
  supportedCapabilities: Capability[];
  requiredServiceCapabilities: Capability[];
  minimumConsentPolicyVersion: string;
}

export const globalPolicy: GlobalPolicy = {
  supportedCapabilities: [
    "identity.profile",
    "identity.verify",
    "payments.create",
    "payments.refund",
    "analytics.emit",
    "location.coarse",
    "storage.secure",
  ],
  requiredServiceCapabilities: ["analytics.emit"],
  minimumConsentPolicyVersion: "3.0.0",
};

Notice that the global object does not name a default payment provider or currency. Choosing one would create unsafe fallback behaviour. If a market policy is missing its provider, payment-dependent services should remain unavailable.

Validate the policy before resolving it

Remote configuration should be treated as executable product policy. Validate it before the host or a mini app uses it.

const MARKET_CODE = /^[A-Z]{2}$/;
const SEMVER = /^\d+\.\d+\.\d+$/;

function duplicateValues(values: string[]): string[] {
  return values.filter((value, index) => values.indexOf(value) !== index);
}

export function validateMarketPolicy(
  global: GlobalPolicy,
  market: MarketPolicy,
  now: Date
): string[] {
  const errors: string[] = [];

  if (!MARKET_CODE.test(market.market)) {
    errors.push("market must be a two-letter upper-case code");
  }
  if (!market.locales.includes(market.defaultLocale)) {
    errors.push("defaultLocale must appear in locales");
  }
  if (!SEMVER.test(market.consentPolicyVersion)) {
    errors.push("consentPolicyVersion must use x.y.z semantic versioning");
  } else if (
    compareSemver(
      market.consentPolicyVersion,
      global.minimumConsentPolicyVersion
    ) < 0
  ) {
    errors.push("consentPolicyVersion is below the global minimum");
  }
  if (duplicateValues(market.locales).length > 0) {
    errors.push("locales contains duplicates");
  }
  if (duplicateValues(market.currencies).length > 0) {
    errors.push("currencies contains duplicates");
  }
  if (duplicateValues(market.deniedCapabilities).length > 0) {
    errors.push("deniedCapabilities contains duplicates");
  }

  const supported = new Set(global.supportedCapabilities);
  for (const denied of market.deniedCapabilities) {
    if (!supported.has(denied)) {
      errors.push(`market denies unknown capability: ${denied}`);
    }
  }

  const providerIds = market.providers.map((provider) => provider.id);
  if (duplicateValues(providerIds).length > 0) {
    errors.push("provider ids must be unique inside a market");
  }
  for (const provider of market.providers) {
    for (const capability of provider.capabilities) {
      if (!supported.has(capability)) {
        errors.push(`${provider.id} exposes unknown ${capability}`);
      }
    }
  }

  const serviceIds = market.services.map((service) => service.serviceId);
  if (duplicateValues(serviceIds).length > 0) {
    errors.push("service ids must be unique inside a market");
  }

  for (const service of market.services) {
    if (!SEMVER.test(service.minimumHostVersion)) {
      errors.push(`${service.serviceId} has an invalid minimumHostVersion`);
    }
    for (const capability of service.requiredCapabilities) {
      if (!supported.has(capability)) {
        errors.push(`${service.serviceId} requests unknown ${capability}`);
      }
    }
  }

  const effective = new Date(market.effectiveFrom);
  if (Number.isNaN(effective.getTime())) {
    errors.push("effectiveFrom must be a valid timestamp");
  } else if (effective > now) {
    errors.push("policy is not effective yet");
  }

  return errors;
}

Schema validation libraries are useful when policy arrives as JSON. The explicit function above keeps cross-field rules visible: the default locale must be allowed, IDs must be unique, and every capability must belong to the global contract.

Production validation should also check that locales and time zones exist, currencies use valid codes, policy age is acceptable, consent versions meet the global minimum, and the policy signature chains to an approved issuer.

Resolve an effective market view

Mini apps should not repeat policy logic. The host can produce an immutable resolved view.

export interface EffectiveMarket {
  market: string;
  revision: number;
  locales: readonly string[];
  defaultLocale: string;
  currencies: readonly string[];
  timeZone: string;
  consentPolicyVersion: string;
  availableCapabilities: ReadonlySet<Capability>;
  providers: readonly Provider[];
  services: readonly ServicePolicy[];
}

export function resolveMarket(
  global: GlobalPolicy,
  market: MarketPolicy,
  now: Date
): EffectiveMarket {
  const errors = validateMarketPolicy(global, market, now);
  if (errors.length > 0) {
    throw new Error(`Invalid market policy: ${errors.join("; ")}`);
  }

  const denied = new Set(market.deniedCapabilities);
  const availableCapabilities = new Set(
    global.supportedCapabilities.filter((capability) => !denied.has(capability))
  );

  const providers = market.providers
    .filter((provider) => provider.enabled)
    .filter((provider) =>
      provider.capabilities.every((capability) =>
        availableCapabilities.has(capability)
      )
    );

  const services = market.services
    .filter((service) => service.enabled)
    .filter((service) =>
      [...global.requiredServiceCapabilities, ...service.requiredCapabilities]
        .every((capability) => availableCapabilities.has(capability))
    );

  return Object.freeze({
    market: market.market,
    revision: market.revision,
    locales: Object.freeze([...market.locales]),
    defaultLocale: market.defaultLocale,
    currencies: Object.freeze([...market.currencies]),
    timeZone: market.timeZone,
    consentPolicyVersion: market.consentPolicyVersion,
    availableCapabilities,
    providers: Object.freeze(providers.map((provider) => Object.freeze({ ...provider }))),
    services: Object.freeze(services.map((service) => Object.freeze({ ...service }))),
  });
}

The filtering rules fail closed. If a capability is denied, providers and services that depend on it disappear from the effective view. They do not receive a partially working configuration.

ReadonlySet communicates intent but does not make JavaScript sets immutable at runtime. Do not expose the returned set to untrusted code. A production bridge can serialise it to a frozen array or answer capability checks through a host-controlled method.

Resolve service eligibility for a specific client

Market availability alone is insufficient. The customer also needs a compatible host version and audience membership.

function compareSemver(left: string, right: string): number {
  const a = left.split(".").map(Number);
  const b = right.split(".").map(Number);
  for (let index = 0; index < 3; index += 1) {
    if (a[index] !== b[index]) return a[index] - b[index];
  }
  return 0;
}

export interface ClientContext {
  hostVersion: string;
  audienceSegments: string[];
}

export function eligibleServices(
  effective: EffectiveMarket,
  client: ClientContext
): ServicePolicy[] {
  return effective.services.filter((service) => {
    if (compareSemver(client.hostVersion, service.minimumHostVersion) < 0) {
      return false;
    }

    return service.allowedAudienceSegments.some((segment) =>
      client.audienceSegments.includes(segment)
    );
  });
}

Audience segments should come from a trusted host service. A mini app should never assign itself to a privileged or regulated segment. Eligibility is also separate from consent: being allowed to see a service does not automatically grant that service access to profile or payment data.

Define two markets without forking code

Now define policies for Singapore and the United Kingdom:

export const sgPolicy: MarketPolicy = {
  market: "SG",
  revision: 7,
  locales: ["en-SG", "zh-SG"],
  defaultLocale: "en-SG",
  currencies: ["SGD"],
  timeZone: "Asia/Singapore",
  consentPolicyVersion: "3.2.0",
  providers: [
    {
      id: "sg-identity-provider",
      kind: "identity",
      enabled: true,
      capabilities: ["identity.verify"],
    },
    {
      id: "sg-payment-rail",
      kind: "payment",
      enabled: true,
      capabilities: ["payments.create", "payments.refund"],
    },
  ],
  deniedCapabilities: [],
  services: [
    {
      serviceId: "merchant-rewards",
      enabled: true,
      minimumHostVersion: "8.3.0",
      requiredCapabilities: ["identity.profile", "analytics.emit"],
      allowedAudienceSegments: ["consumer"],
    },
  ],
  effectiveFrom: "2026-08-01T00:00:00Z",
};

export const gbPolicy: MarketPolicy = {
  market: "GB",
  revision: 4,
  locales: ["en-GB"],
  defaultLocale: "en-GB",
  currencies: ["GBP"],
  timeZone: "Europe/London",
  consentPolicyVersion: "3.1.0",
  providers: [
    {
      id: "gb-payment-provider",
      kind: "payment",
      enabled: true,
      capabilities: ["payments.create", "payments.refund"],
    },
  ],
  deniedCapabilities: ["location.coarse"],
  services: [
    {
      serviceId: "merchant-rewards",
      enabled: true,
      minimumHostVersion: "8.3.0",
      requiredCapabilities: ["identity.profile", "analytics.emit"],
      allowedAudienceSegments: ["consumer"],
    },
    {
      serviceId: "local-events",
      enabled: true,
      minimumHostVersion: "8.4.0",
      requiredCapabilities: ["location.coarse", "analytics.emit"],
      allowedAudienceSegments: ["consumer"],
    },
  ],
  effectiveFrom: "2026-08-10T00:00:00Z",
};

Both markets use the same service definition for merchant rewards. Providers, locale, currency, time zone, consent revision, and capability availability vary through policy.

The United Kingdom policy denies coarse location. The resolver will remove local-events from the effective service list because it requires that capability. The host does not need a country condition inside the service loader.

Test the market boundary

Use Vitest to keep the intended behaviour stable:

import { describe, expect, it } from "vitest";
import {
  eligibleServices,
  gbPolicy,
  globalPolicy,
  resolveMarket,
  sgPolicy,
  type MarketPolicy,
} from "./market-policy";

const now = new Date("2026-08-26T12:00:00Z");

describe("market policy resolver", () => {
  it("removes services that require a denied capability", () => {
    const effective = resolveMarket(globalPolicy, gbPolicy, now);
    expect(effective.services.map((service) => service.serviceId))
      .toEqual(["merchant-rewards"]);
  });

  it("keeps market-specific providers behind global contracts", () => {
    const effective = resolveMarket(globalPolicy, sgPolicy, now);
    expect(effective.providers.map((provider) => provider.id)).toEqual([
      "sg-identity-provider",
      "sg-payment-rail",
    ]);
  });

  it("blocks services on an old host version", () => {
    const effective = resolveMarket(globalPolicy, sgPolicy, now);
    const visible = eligibleServices(effective, {
      hostVersion: "8.2.9",
      audienceSegments: ["consumer"],
    });
    expect(visible).toHaveLength(0);
  });

  it("rejects an unrecognised market code", () => {
    const invalid: MarketPolicy = { ...sgPolicy, market: "SINGAPORE" };
    expect(() => resolveMarket(globalPolicy, invalid, now))
      .toThrow("market must be a two-letter upper-case code");
  });
});

The tests demonstrate the separation of responsibilities. Global code knows capability names and resolution rules. Market policies choose providers and narrow availability. Services do not contain country branches.

Deliver policy like code

A policy bundle can change customer eligibility and access to sensitive capabilities. Treat it with the same care as executable code.

A production delivery path should include:

immutable revision numbers;
schema and semantic validation;
a digital signature from an approved policy publisher;
staged rollout and market-specific approval;
a last-known-good policy stored by the host;
expiry and forced-refresh rules;
an audit event for every activation and rollback;
a global kill switch for a service or provider.

Do not merge arbitrary JSON objects recursively. Deep merge makes precedence difficult to inspect and can preserve a field that a market intended to remove. Resolve explicit structures and use allowlists for capabilities, providers, and services.

The host should also define its behaviour when the policy cannot be verified. Sensitive services should fail closed. Low-risk static content may use a cached last-known-good revision. The fallback needs to be designed before an outage.

Observe global reuse and local results

The policy resolver should emit operational events containing the market, revision, host version, service ID, decision, and reason. Useful reasons include:

service_disabled
host_version_too_old
capability_denied
provider_unavailable
audience_not_eligible
policy_expired
policy_signature_invalid

At platform level, these events show how often local variation is handled by configuration and where markets still request host changes. At product level, teams should also measure task completion, payment success, errors, and support demand in each market.

Technical reuse and local customer value are separate outcomes. A service can load through the same contract everywhere and still perform poorly in one market because its proposition, language, provider, or journey is wrong.

One host can carry deliberate differences

A multi-market platform becomes easier to operate when it is explicit about three categories:

global capabilities and safety controls;
versioned market policy and provider choices;
locally owned services and customer outcomes.

The TypeScript resolver built here keeps those categories visible. It filters denied capabilities, incompatible providers, unavailable services, old host versions, and ineligible audiences without creating country branches in the native shell.

That is the architectural objective: a global improvement can spread through the common host, while a necessary local change travels through policy or a modular service. One app remains recognisable across markets without requiring every market to behave the same way.

Design a Curated Mini-App Catalog Before You Build a Marketplace

FinClip Super-App — Tue, 25 Aug 2026 03:55:45 +0000

Design a Curated Mini-App Catalog Before You Build a Marketplace

A mini-app platform does not need an open marketplace on its first release.

The first technical requirement is usually smaller: the host application must know which services exist, who owns them, which version is approved, which native capabilities they may request, and where customers may encounter them.

That is a registry problem.

In this tutorial, we will build a small TypeScript registry for a curated mini-app catalogue. It will support:

explicit service ownership;
capability allowlists;
review and lifecycle status;
minimum host-version checks;
regional and audience eligibility;
contextual placement instead of a generic store;
immediate suspension without waiting for a native release.

The result is intentionally narrower than a marketplace. There is no public developer signup, paid ranking, open submission, review marketplace, or revenue-share engine. Those products can be added when real supply and discovery pressure justify them.

Start with a manifest owned by the host

Every service needs a record the host can evaluate before loading code. Define the core types in catalog.ts:

export type Capability =
  | "identity.profile"
  | "payments.create"
  | "analytics.emit"
  | "location.coarse"
  | "storage.secure";

export type ServiceStatus =
  | "draft"
  | "review"
  | "approved"
  | "suspended"
  | "retired";

export type Placement =
  | { kind: "home"; priority: number }
  | { kind: "search"; keywords: string[] }
  | { kind: "context"; event: string; priority: number };

export interface MiniAppManifest {
  id: string;
  name: string;
  version: string;
  ownerTeam: string;
  supportContact: string;
  status: ServiceStatus;
  entryUrl: string;
  integritySha256: string;
  minimumHostVersion: string;
  allowedRegions: string[];
  allowedAudienceSegments: string[];
  requestedCapabilities: Capability[];
  placements: Placement[];
  approvedAt?: string;
  retiresAt?: string;
}

The ownerTeam and supportContact fields are as important as entryUrl. A host should be able to route an operational problem without reading source-control history or searching a partner contract.

requestedCapabilities expresses the maximum capability set approved for the service. Runtime calls still need authentication, authorisation, consent, and request-level policy enforcement. A manifest allowlist is an initial boundary, not the entire security model.

The integrity digest allows the host to verify that the downloaded package matches the approved artifact. In a production platform, the manifest itself should also be signed and delivered over an authenticated channel.

Reject ambiguous manifests

A registry should fail closed. An approved service without an owner or integrity value should never become visible because a field happened to be optional in a dashboard.

Add a validator:

const CAPABILITIES: ReadonlySet<Capability> = new Set([
  "identity.profile",
  "payments.create",
  "analytics.emit",
  "location.coarse",
  "storage.secure",
]);

export function validateManifest(manifest: MiniAppManifest): string[] {
  const errors: string[] = [];

  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(manifest.id)) {
    errors.push("id must use lower-case kebab-case");
  }
  if (!/^\d+\.\d+\.\d+$/.test(manifest.version)) {
    errors.push("version must be semantic x.y.z");
  }
  if (!manifest.ownerTeam.trim()) errors.push("ownerTeam is required");
  if (!manifest.supportContact.trim()) errors.push("supportContact is required");
  if (!/^https:\/\//.test(manifest.entryUrl)) {
    errors.push("entryUrl must use HTTPS");
  }
  if (!/^[a-f0-9]{64}$/.test(manifest.integritySha256)) {
    errors.push("integritySha256 must contain 64 lower-case hex characters");
  }

  for (const capability of manifest.requestedCapabilities) {
    if (!CAPABILITIES.has(capability)) {
      errors.push(`unknown capability: ${capability}`);
    }
  }

  const duplicateCapabilities = manifest.requestedCapabilities.filter(
    (capability, index, all) => all.indexOf(capability) !== index
  );
  if (duplicateCapabilities.length > 0) {
    errors.push("requestedCapabilities contains duplicates");
  }

  if (manifest.status === "approved" && !manifest.approvedAt) {
    errors.push("approvedAt is required for an approved service");
  }

  return errors;
}

You may want a schema library such as Zod or JSON Schema when manifests arrive over an API. The explicit validator keeps this example dependency-free and makes the policy easy to see.

Unknown capabilities are rejected. Silently ignoring one can produce confusing behaviour: the service may appear healthy until a customer reaches the feature that depends on it.

Keep review state separate from distribution

Approval answers whether a particular version may run. Placement answers where eligible customers can find it. Mixing the two creates fragile release logic.

Create an in-memory registry that stores one active manifest per service:

export class CuratedRegistry {
  private manifests = new Map<string, MiniAppManifest>();

  upsert(manifest: MiniAppManifest): void {
    const errors = validateManifest(manifest);
    if (errors.length > 0) {
      throw new Error(`Invalid manifest: ${errors.join("; ")}`);
    }
    this.manifests.set(manifest.id, structuredClone(manifest));
  }

  get(id: string): MiniAppManifest | undefined {
    const item = this.manifests.get(id);
    return item ? structuredClone(item) : undefined;
  }

  suspend(id: string): void {
    const item = this.manifests.get(id);
    if (!item) throw new Error(`Unknown service: ${id}`);
    this.manifests.set(id, { ...item, status: "suspended" });
  }

  all(): MiniAppManifest[] {
    return [...this.manifests.values()].map((item) => structuredClone(item));
  }
}

structuredClone prevents a caller from mutating registry state after reading it. A real implementation would persist immutable manifest revisions and append audit events for submission, approval, suspension, and retirement.

The suspension operation is deliberately simple. When a service is compromised or broken, the host needs a remote control that removes it from discovery and prevents launch. Waiting for an iOS or Android release defeats one of the main operational benefits of modular delivery.

Resolve eligibility before ranking

A customer should never see a service that cannot run in their host version or region. Filter eligibility before applying placement rules.

export interface DiscoveryContext {
  region: string;
  audienceSegments: string[];
  hostVersion: string;
  event?: string;
  now: Date;
}

function compareVersion(a: string, b: string): number {
  const left = a.split(".").map(Number);
  const right = b.split(".").map(Number);
  for (let i = 0; i < 3; i += 1) {
    if (left[i] !== right[i]) return left[i] - right[i];
  }
  return 0;
}

function isEligible(
  manifest: MiniAppManifest,
  context: DiscoveryContext
): boolean {
  if (manifest.status !== "approved") return false;
  if (compareVersion(context.hostVersion, manifest.minimumHostVersion) < 0) {
    return false;
  }
  if (!manifest.allowedRegions.includes(context.region)) return false;

  const audienceMatch = manifest.allowedAudienceSegments.some((segment) =>
    context.audienceSegments.includes(segment)
  );
  if (!audienceMatch) return false;

  if (manifest.retiresAt && new Date(manifest.retiresAt) <= context.now) {
    return false;
  }
  return true;
}

This example uses allowlists. Depending on the product, an empty region or audience list could mean “available to nobody” or “available to everyone.” Pick one meaning and encode it explicitly. Ambiguous empty lists are a common source of accidental exposure.

Audience membership should be computed by a trusted host service. Do not let a mini app assign itself to a privileged segment.

Prefer contextual discovery for a small catalogue

An early catalogue may not need search. The service can appear beside the customer journey that makes it useful.

Add a resolver:

export interface DiscoveryResult {
  id: string;
  name: string;
  reason: "context" | "home" | "search";
  priority: number;
}

export function discover(
  registry: CuratedRegistry,
  context: DiscoveryContext
): DiscoveryResult[] {
  const results: DiscoveryResult[] = [];

  for (const service of registry.all()) {
    if (!isEligible(service, context)) continue;

    for (const placement of service.placements) {
      if (placement.kind === "context" && placement.event === context.event) {
        results.push({
          id: service.id,
          name: service.name,
          reason: "context",
          priority: placement.priority + 100,
        });
      }
      if (placement.kind === "home") {
        results.push({
          id: service.id,
          name: service.name,
          reason: "home",
          priority: placement.priority,
        });
      }
    }
  }

  return results
    .sort((a, b) => b.priority - a.priority)
    .filter(
      (result, index, all) =>
        all.findIndex((candidate) => candidate.id === result.id) === index
    );
}

Contextual results receive a boost because they respond to a current customer event. This is only an example policy. The essential design choice is that discovery logic belongs to the trusted host, not to each mini app.

A service can qualify for both home and contextual placement. The final filter keeps its highest-ranked occurrence. In a larger catalogue, you would want explainable ranking, frequency caps, experimentation controls, and separation between paid placement and organic relevance.

Create two real services

Here is a travel-insurance service that appears after an eligible travel purchase:

const registry = new CuratedRegistry();

registry.upsert({
  id: "travel-cover",
  name: "Travel Cover",
  version: "1.2.0",
  ownerTeam: "Protection Products",
  supportContact: "protection-operations",
  status: "approved",
  entryUrl: "https://services.example.com/travel-cover/1.2.0",
  integritySha256: "a".repeat(64),
  minimumHostVersion: "8.4.0",
  allowedRegions: ["GB", "SG"],
  allowedAudienceSegments: ["travel-eligible"],
  requestedCapabilities: [
    "identity.profile",
    "payments.create",
    "analytics.emit",
  ],
  placements: [
    { kind: "context", event: "travel.purchase.completed", priority: 80 },
  ],
  approvedAt: "2026-08-25T09:00:00Z",
});

registry.upsert({
  id: "merchant-rewards",
  name: "Merchant Rewards",
  version: "2.0.1",
  ownerTeam: "Rewards",
  supportContact: "rewards-operations",
  status: "approved",
  entryUrl: "https://services.example.com/merchant-rewards/2.0.1",
  integritySha256: "b".repeat(64),
  minimumHostVersion: "8.2.0",
  allowedRegions: ["GB"],
  allowedAudienceSegments: ["rewards-enrolled"],
  requestedCapabilities: ["identity.profile", "analytics.emit"],
  placements: [{ kind: "home", priority: 30 }],
  approvedAt: "2026-08-20T10:00:00Z",
});

The two services share identity and analytics but have different owners, capability needs, audiences, and placements. That makes them a better test of platform reuse than two nearly identical campaign pages.

Discover services for a customer:

const visible = discover(registry, {
  region: "GB",
  audienceSegments: ["travel-eligible", "rewards-enrolled"],
  hostVersion: "8.5.0",
  event: "travel.purchase.completed",
  now: new Date("2026-08-25T12:00:00Z"),
});

console.log(visible);
// Travel Cover appears first because its context is currently relevant.
// Merchant Rewards remains available through its home placement.

Test suspension and eligibility

Use Vitest to preserve the host’s safety rules:

import { describe, expect, it } from "vitest";
import { CuratedRegistry, discover, type MiniAppManifest } from "./catalog";

const approved: MiniAppManifest = {
  id: "local-service",
  name: "Local Service",
  version: "1.0.0",
  ownerTeam: "Local Partnerships",
  supportContact: "local-ops",
  status: "approved",
  entryUrl: "https://services.example.com/local/1.0.0",
  integritySha256: "c".repeat(64),
  minimumHostVersion: "3.0.0",
  allowedRegions: ["SG"],
  allowedAudienceSegments: ["consumer"],
  requestedCapabilities: ["identity.profile"],
  placements: [{ kind: "home", priority: 10 }],
  approvedAt: "2026-08-25T09:00:00Z",
};

const context = {
  region: "SG",
  audienceSegments: ["consumer"],
  hostVersion: "3.1.0",
  now: new Date("2026-08-25T12:00:00Z"),
};

describe("curated discovery", () => {
  it("shows an eligible approved service", () => {
    const registry = new CuratedRegistry();
    registry.upsert(approved);
    expect(discover(registry, context)).toHaveLength(1);
  });

  it("hides a service immediately after suspension", () => {
    const registry = new CuratedRegistry();
    registry.upsert(approved);
    registry.suspend("local-service");
    expect(discover(registry, context)).toHaveLength(0);
  });

  it("hides a service from an unsupported host version", () => {
    const registry = new CuratedRegistry();
    registry.upsert(approved);
    expect(
      discover(registry, { ...context, hostVersion: "2.9.9" })
    ).toHaveLength(0);
  });
});

These tests cover three important guarantees: approved services can appear, suspension removes them, and an incompatible client never receives them.

Production tests should also cover expired services, unsupported regions, audience mismatches, duplicate placements, malformed semantic versions, unknown capabilities, and manifest-signature failures.

Add observability before adding openness

Every discovery and launch decision should produce a structured event. Record the manifest version, host version, placement reason, policy decision, and a privacy-safe customer or session reference.

Useful events include:

service_eligible
service_impression
service_launch_requested
service_launch_blocked
service_loaded
service_failed
service_suspended
service_completed

This data answers questions that matter before a marketplace exists. Are contextual placements helping customers complete a task? Which service creates support demand? How often do old host versions block access? How quickly can the team suspend a broken release?

It also creates a baseline for the second and third services. A platform becomes valuable when reuse improves delivery and operation, not when a catalogue reaches an arbitrary size.

What changes when a marketplace is justified?

The curated registry remains useful if the ecosystem grows. A marketplace adds systems around it:

provider identity and onboarding;
self-service submission and test environments;
multi-stage automated and manual review;
search indexing and explainable ranking;
commercial agreements, settlement, refunds, and tax handling;
ratings, complaints, abuse detection, and dispute resolution;
partner-level quotas, analytics, and support.

These functions should appear because manual onboarding and contextual discovery have become constraints. Adding them early increases the attack surface and operating workload before the platform knows what its participants need.

A small catalogue can still be a real platform

The code in this tutorial supports only a few services, yet it establishes durable platform boundaries. Services have owners. Capabilities are explicit. Approval is separate from placement. Eligibility is checked before discovery. Suspension is immediate. The host controls context and retains an audit-friendly record of what may run.

That is enough to learn from the first service and test reuse with the second.

When service supply grows, partners request a repeatable publishing path, and customers need help comparing choices, the same registry can sit beneath a broader marketplace. Until then, a curated catalogue keeps the system understandable and the customer experience deliberate.