DEV Community: Geminate Solutions

Legacy Application Modernization Without Forcing Password Resets

Geminate Solutions — Mon, 26 Oct 2026 06:45:32 +0000

You can move users to a new login system without making anyone reset their password. To do it, you either import their existing password hashes or check each password once against the old system the next time that user signs in. Most legacy application modernization projects use both methods, with a short period where the old and new identity providers run side by side.

Picture your situation. Your user table is full of hashes from a framework nobody on the team chose. The board wants the new platform live without a wave of "I can't log in" tickets. This guide is written for that moment.

Why can't you just copy the passwords across?

You never had the passwords. You have hashes, and a hash only works with the exact algorithm, salt and settings that created it. The new identity provider can only check a password against an old hash if it understands that format.

Modern providers such as Auth0, Okta, AWS Cognito, Keycloak and Microsoft Entra all handle bcrypt, PBKDF2, scrypt or Argon2 in some form, either natively or through an import hook. The trouble starts with homegrown schemes: unsalted MD5, SHA-1 with a global pepper kept in a config file, or a custom hashing loop someone wrote years ago. Those need custom verification code or a lazy migration.

Then there is everything around the password. MFA secrets, social login links, "remember me" cookies, mobile refresh tokens and API keys all live in the old system too, and each one needs a plan.

What does getting the login switch wrong cost you?

The login page is the one screen every user touches.

The failures are predictable. A user who signed up as "John@Company.com" and later as "john@company.com" becomes two accounts. Mobile apps holding old refresh tokens log everyone out at once. MFA users are asked to enrol again with no warning and assume they have been hacked. A stricter password policy kicks in at first login and blocks people halfway through a task.

Each of those turns into support tickets, paying customers losing their sessions, and a rollback conversation nobody wants. A rushed import can also leave weak legacy hashes sitting in your new provider for years. That turns old security debt into permanent security debt.

Option one: bulk hash import

You export every user record with its hash, salt and algorithm settings, then load them all into the new provider at once. On cutover day, users sign in with their existing password and notice nothing.

When it fits: the old hashes use a standard algorithm the new provider supports, and you want a clean cutover date.

Risks to manage:

Weak hashes come along for the ride. If the legacy store uses MD5 or SHA-1, have the team wrap each one during export (for example, bcrypt applied over the old hash) so nothing weak is stored at rest. Then upgrade to a native hash at each user's next login.
Data drift between export and cutover. Anyone who changes their password after the export ends up with a stale hash. Plan a final delta sync during a short change freeze.
Identity collisions. Normalise emails and resolve duplicates before the import, not after.

Option two: rehash each user at their next login

This is also called lazy or just-in-time migration. When the new provider gets a login from a user it doesn't recognise, it calls a small piece of code that checks the password against the old system. If the password matches, it creates the user with a fresh, modern hash. The Cognito user migration trigger and Auth0 custom database scripts are built for this.

When it fits: the hash format is unusual, you can't export the hashes safely, or you want every stored password upgraded to a modern algorithm.

Risks to manage:

The long tail. Active users move over quickly. Dormant users may never log in, so the old system has to stay reachable until you decide what happens to them.
The new system now depends on the old one. If the legacy database is slow or down, logins fail. Require a strict timeout and a clear error message.
Brute force exposure. The migration code path needs the same rate limiting and lockout rules as the main login.

Plan for the stragglers from day one, not in month six.

Option three: run old and new identity providers side by side

Both systems stay live for a fixed window. A routing layer decides which provider handles each login, usually based on a "migrated" flag on the user. New features go on the new provider, and users move across in waves.

When it fits: you have enterprise customers with their own SAML or OIDC connections, or several apps share one login and can't all move on the same day.

Risks to manage:

Two sources of truth. Profile edits, deactivations and password changes must sync both ways. Otherwise a deactivated employee keeps access through the old door.
Session confusion. Every app must accept tokens from both issuers during the window, then stop accepting old tokens on a set date.
The window never closes. If the plan has no end date, you end up paying for and securing two systems indefinitely.

Which approach should you choose?

Use these rules:

If the hashes are standard and most users are active, do a bulk import with a final delta sync.
If the hashes are weak or custom, use lazy migration with a fixed end date. After that date, send remaining users a friendly reset email.
If you have enterprise SSO connections or several apps, run both providers side by side and migrate tenant by tenant.
If you aren't sure, combine them. Bulk import the users you can, lazy migrate the rest, and keep the old provider read-only as a fallback.

The trade-off is simple. Bulk import is fast but carries old weaknesses forward. Lazy migration is cleaner but slow to finish. Side by side is the most flexible and needs the most discipline.

Who doesn't need any of this?

Some teams can skip all of it. Say your app is an internal tool used by one office, and everyone can walk over to IT. Then a planned reset with a clear email and a help desk on standby is the honest, cheap answer. Don't build a migration pipeline for a problem one well-written email solves.

What should you require from your team before the switch?

Get these in writing before anyone touches production:

A hash inventory. List every algorithm in the user table with a count of users on each. Older apps often hold several generations of hashing, and one unknown format can break a bulk import.
An identity cleanup report. Cover duplicates, case clashes and missing emails. Collisions cause most "wrong account" tickets.
An MFA and session plan. Can TOTP secrets be exported? What happens to existing mobile sessions? Surprise logouts and forced MFA re-enrolment drive most support volume.
A rollback path. Know how to point logins back at the old system within minutes. You want that decided calmly, not during an incident.
A shared dashboard. Show login success rate, failure reasons and migration progress, and make it visible to support. That way the team spots a spike before the inbox does.
A dated end state. Agree when the old provider gets switched off and what dormant users will receive. This stops the side-by-side window from becoming permanent.

One question tests any vendor quickly: what happens to a user with MFA turned on who hasn't logged in for two years? A good team answers right away. A weak one starts guessing.

Authentication is usually one part of a larger modernisation. For how to sequence the rest without breaking what users rely on, read this legacy system modernization guide.

If you'd like a second opinion on your login migration plan, ask Geminate Solutions for a free review.

ERP Development: Sync Your App and ERP With a Postgres Outbox

Geminate Solutions — Sun, 25 Oct 2026 18:44:11 +0000

If your custom app needs to send orders or invoices to an ERP, don't call the ERP API from inside your request handler. Write each change to an outbox table in the same Postgres transaction as the business data. Then let a separate Node.js worker push those rows to the ERP, with retries, backoff and a dead-letter queue. This is the part of ERP development that decides whether you can sync records between a custom app and your ERP without losing any or posting them twice.

You may know the symptoms already. The ERP had a slow afternoon and some orders never arrived. Or the warehouse shipped one order and finance has two invoices for it. Nobody can say which records made it across without checking both systems by hand.

How do you sync records between a custom app and your ERP without losing any?

You make the database the single source of truth for what still needs to be sent. The outbox row and the order row commit together or not at all. A worker reads pending rows, sends them, and marks them done only after the ERP confirms.

The usual approach is a "dual write": save the order, then call the ERP. It fails in three ways.

The call fails after your commit. The order exists in your app and nowhere else. Nothing remembers to try again.
The call succeeds but the response times out. Your code thinks it failed and retries. The ERP now has two invoices.
You make the call inside the transaction. Now a slow ERP holds your database locks open, and its bad day becomes your app's bad day.

The outbox fixes the first and third problems by design. Idempotency fixes the second, which we cover below.

What does a broken sync actually cost you?

The damage shows up downstream, in people's time. Customers get duplicate invoices and start doubting every one after that. Orders missing from the ERP never reach fulfilment, so they ship late or not at all.

Stock levels drift because the ERP never saw some sales. At month end, finance compares exports line by line to find the gaps. Worst of all, these failures are quiet. You usually hear about them from a customer, weeks later.

Do you need an outbox at all?

Not always. If you send a handful of records a day and someone checks them, or a nightly CSV import into the ERP already removes duplicates, keep it. An outbox adds a table, a worker and monitoring, and that is only worth it when records flow all day and people rely on them arriving.

If orders come in all day, the ERP has outages or rate limits, or a duplicate invoice causes a real problem, read on.

Step 1: create the outbox table

CREATE TABLE erp_outbox (
  id               bigserial PRIMARY KEY,
  aggregate        text NOT NULL,
  aggregate_id     text NOT NULL,
  event_type       text NOT NULL,
  payload          jsonb NOT NULL,
  idempotency_key  uuid NOT NULL UNIQUE DEFAULT gen_random_uuid(),
  status           text NOT NULL DEFAULT 'pending',
  attempts         int NOT NULL DEFAULT 0,
  next_attempt_at  timestamptz NOT NULL DEFAULT now(),
  last_error       text,
  created_at       timestamptz NOT NULL DEFAULT now()
)

Add an index so the worker's query stays fast as the table grows:

CREATE INDEX erp_outbox_pending ON erp_outbox (next_attempt_at) WHERE status = 'pending'

The status column has three values: pending, sent and dead. Rows marked dead are your dead-letter queue. They stay in the same table, where you can query them.

Step 2: write the business row and the outbox row together

async function createOrder(pool, order) {
  const client = await pool.connect()
  try {
    await client.query('BEGIN')
    const { rows } = await client.query(
      'INSERT INTO orders (customer_id, status) VALUES ($1, $2) RETURNING id',
      [order.customerId, 'confirmed']
    )
    await client.query(
      `INSERT INTO erp_outbox (aggregate, aggregate_id, event_type, payload)
       VALUES ('order', $1, 'order.created', $2)`,
      [rows[0].id, JSON.stringify({ ...order, id: rows[0].id })]
    )
    await client.query('COMMIT')
    return rows[0].id
  } catch (err) {
    await client.query('ROLLBACK')
    throw err
  } finally {
    client.release()
  }
}

There is no network call here. The user gets a fast response whether or not the ERP is up.

Step 3: how does the worker claim rows safely?

It claims rows with FOR UPDATE SKIP LOCKED and pushes their next_attempt_at forward as a lease. Two workers never take the same row. If a worker crashes halfway, its rows come back on their own once the lease runs out.

async function claimBatch(pool) {
  const { rows } = await pool.query(`
    UPDATE erp_outbox SET next_attempt_at = now() + interval '2 minutes'
    WHERE id IN (
      SELECT id FROM erp_outbox
      WHERE status = 'pending' AND next_attempt_at <= now()
      ORDER BY id LIMIT 20
      FOR UPDATE SKIP LOCKED
    )
    RETURNING *`)
  return rows
}

The lease has to be longer than your HTTP timeout. If it isn't, a slow call can be claimed a second time while the first one is still running.

How do retries, backoff and the dead-letter queue work?

Each failure increases the wait before the next try, with some randomness added so retries don't all land at once. Errors that retrying won't fix, and rows that have used up their attempts, go to dead.

const MAX_ATTEMPTS = 8

function backoffMs(attempts) {
  const base = Math.min(2 ** attempts * 1000, 15 * 60 * 1000)
  return base / 2 + Math.random() * (base / 2)
}

async function sendToErp(row) {
  const res = await fetch(`${process.env.ERP_URL}/api/${row.aggregate}s`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Idempotency-Key': row.idempotency_key,
      Authorization: `Bearer ${process.env.ERP_TOKEN}`
    },
    body: JSON.stringify(row.payload),
    signal: AbortSignal.timeout(30000)
  })
  if (res.ok) return
  const err = new Error(`ERP ${res.status}: ${await res.text()}`)
  err.retryable = res.status === 429 || res.status >= 500
  throw err
}

async function processRow(pool, row) {
  try {
    await sendToErp(row)
    await pool.query(`UPDATE erp_outbox SET status = 'sent' WHERE id = $1`, [row.id])
  } catch (err) {
    const attempts = row.attempts + 1
    const dead = err.retryable === false || attempts >= MAX_ATTEMPTS
    await pool.query(
      `UPDATE erp_outbox
       SET attempts = $2, last_error = $3,
           status = CASE WHEN $4::boolean THEN 'dead' ELSE 'pending' END,
           next_attempt_at = now() + ($5 || ' milliseconds')::interval
       WHERE id = $1`,
      [row.id, attempts, String(err.message).slice(0, 2000), dead, Math.round(backoffMs(attempts))]
    )
  }
}

async function run(pool) {
  while (true) {
    const rows = await claimBatch(pool)
    for (const row of rows) await processRow(pool, row)
    if (rows.length === 0) await new Promise(r => setTimeout(r, 2000))
  }
}

Network errors and timeouts have no retryable flag, so they get retried. A 400 for a missing tax code goes straight to dead, because sending the same bad payload eight more times won't fix it.

To replay a dead row once the cause is fixed, set status = 'pending' and attempts = 0. Keep the same idempotency_key.

How do you stop the ERP from posting an invoice twice?

Give the ERP a key that stays the same on every retry, so a repeated request is recognised and ignored. The outbox's idempotency_key is that key. How you pass it depends on what your ERP supports.

If the ERP accepts an idempotency header, send it, as shown above.
If it supports upsert by external ID, use your outbox key or order number as that ID. NetSuite, for example, can upsert a record by its external ID.
If it supports neither, store your reference in a custom field and look it up before you create the record. This is slower, but it is the only safe option.

One more rule: if the order of events matters for a record, for example order.updated must never arrive before order.created, claim only the oldest pending row for each aggregate_id.

What should you check before going live?

Alert when any row is dead. Each dead row is an order or invoice the ERP doesn't know about.
Alert on the age of the oldest pending row. A stuck worker produces no errors, just silence.
Save the ERP's response body when a call fails. ERPs usually explain validation errors there.
Kill the worker in the middle of a send during testing. That is exactly how duplicates happen, so prove your idempotency handles it.
Delete old sent rows on a schedule. Otherwise the table grows forever.

If you're connecting your own app to an ERP and want a second opinion on the sync design before it goes live, Geminate Solutions can review your plan for free. You can see how we handle this kind of work in our custom development practice.

Application Modernization: Should an API Layer Come Before a Rewrite?

Geminate Solutions — Sun, 25 Oct 2026 07:59:12 +0000

Yes, in most cases you should put an API layer in front of your legacy system before you replace anything, as long as it has a clear boundary, contract tests and a date to retire it. Done that way, application modernization stops being one risky rewrite and becomes a series of small moves that your new web and mobile apps can ship on right now.

You probably know the situation. There is a core system, maybe a customised ERP, a twenty-year-old Java or .NET monolith, or a database packed with stored procedures, and nobody wants to touch it. The people who wrote it have left. The business wants a customer app, a partner portal or a modern dashboard, and every plan seems to start with "first we rewrite the core".

There is a better order.

What does an API layer in front of a legacy system actually do?

An API layer sits between your new applications and the old core. New apps talk only to the layer, the layer talks to the legacy system, and nothing new ever reaches into the old database directly.

It comes in two shapes. A facade is a thin, clean interface: it exposes the operations you need, such as "get order" or "create customer", and hides the awkward calls behind them. An anti-corruption layer goes further. It translates the legacy model into the model your new apps should use, so a customer record split across four tables with cryptic status codes like ST_7 becomes one clear object with a status of "on hold".

The second shape matters more than most teams expect. Without translation, your new mobile app quietly inherits every odd rule and naming choice of the old core. You have not modernised anything. You have moved the mess onto a newer screen.

Why does this let new apps ship while the core keeps running?

Because the layer separates two timelines. The web and mobile teams build against a stable contract, while the old system keeps doing its job behind it, untouched.

Once that contract exists, you can replace what sits behind any single endpoint later. Move "customer lookup" to a new service, point the layer at it, and the apps never notice. This is the strangler pattern, and the API layer is the piece that makes it possible.

When does an API layer only hide the problem?

A facade hides the problem when it becomes permanent and nobody owns the core behind it. Watch for these signs early:

The layer is a pass-through. Every endpoint maps one to one onto a legacy call, with the same names and fields. That is a proxy, not a boundary, and it freezes the old model into every new app.
Business logic is creeping into the layer. Discount rules, eligibility checks or validation get copied into the facade "just for now". You now have two sources of truth that will drift apart.
Writes go around it. The new app reads through the API, but a batch job or a reporting tool still writes straight into the legacy database. The layer cannot protect data it never sees.
Nobody can name what moves first. If there is no list of which capability leaves the legacy core first, the layer is just one more system to maintain forever.

The cost of getting this wrong is quiet on day one. It shows up a year later as two systems to patch, releases that still wait on the old core, outages you cannot trace because the failure happens three hops away, and a team that now fears two systems instead of one.

Who does not need an API layer?

If your legacy system already exposes a reasonably clean, documented API and only one new app consumes it, you may not need another layer. Adding one just adds a network hop, a deployment and something else to monitor.

The same goes for a core that is small, well understood and covered by tests. There, a careful staged replacement can be faster than building a boundary you will throw away in a few months. Be honest about which situation you are in before anyone starts building.

What should you require from the team building it?

This is where these projects succeed or fail, and you can ask for every item in writing before work starts.

1. Contract tests on both sides. Each endpoint needs tests that pin down exactly what it accepts and returns, using a tool like Pact or schema checks against an OpenAPI spec. They run against the legacy-backed version today and against any replacement later. If both pass the same suite, you can swap the backend safely. Without them, every migration step is a guess.

2. A written read/write boundary. Reads through the facade are low risk. Writes are where data gets corrupted. Ask for a list of every system that writes to the legacy data store, plus a rule that all new writes go through the layer. If an old job still writes directly, decide whether to route it through the layer or freeze it before anything else moves.

3. Translation, not mirroring. Ask to see the domain model the new apps will use. If it reads like the legacy table names, push back.

4. Visibility from day one. Every request should carry a correlation ID into the logs on both sides of the layer. Timeouts must be set on purpose, because slow legacy calls can blow through a default 30 second timeout and leave users staring at a spinner. When the core is down, the apps should get a clear error, not a hang.

5. A retirement plan with an order. You want a list of capabilities in the order they will move off the core, and a definition of "done" for each. If the team cannot produce this, you are paying for a permanent facade.

In what order should you do it?

A simple sequence works for most teams:

Map who calls the core today and who writes to its data.
Pick the one capability the new app needs most, usually a read such as order status or account details.
Define the contract for it in the new domain language, then write the contract tests.
Build the layer for that capability only, and ship the new app feature against it.
Add writes one at a time, each behind its own tests and a way to switch back.
When a capability has stable contracts, replace its backend and retire that part of the core.

Use simple decision rules along the way. If a capability changes often and blocks the business, move it off the core early. If it is stable and rarely touched, leave it behind the facade longer. If two capabilities share tangled data, move them together or not at all.

The trade-off is plain: you accept an extra component for a while in exchange for shipping now and replacing the core in pieces you can test and reverse.

For a wider view of when to wrap, rebuild or replace, the guide to legacy system modernization walks through each option and its risks.

What is the next step?

If you have a core system nobody wants to touch and a new app waiting on it, send your current architecture or modernisation plan to Geminate Solutions for a free review. You get an NDA before we talk and a reply within 24 hours.

Shopify App Creation: Webhook HMAC and GDPR Handlers in Node.js

Geminate Solutions — Sun, 25 Oct 2026 06:15:14 +0000

Shopify app creation feels finished the moment your app installs and loads in the admin. Then review sends it back because your webhook endpoint accepted a forged request, or your three mandatory GDPR compliance webhooks do nothing. This walkthrough fixes both in a Node.js custom app: verify the HMAC against the raw body, answer fast and process later, and write real handlers for customers/data_request, customers/redact and shop/redact.

If your logs say "HMAC verification failed" while the secret is definitely correct, this is for you.

Why does HMAC verification fail even with the right secret?

Almost always because you are hashing the wrong bytes. Shopify signs the exact raw request body, and express.json() has already parsed it into an object by the time your handler runs.

Shopify computes an HMAC-SHA256 of the body with your app's client secret, base64-encodes it and sends it in the X-Shopify-Hmac-Sha256 header. If you hash JSON.stringify(req.body) instead, spacing and unicode escaping can differ from the original. One changed byte gives a different signature.

The fix is a raw body parser on the webhook route, registered before any JSON middleware.

import express from 'express'
import crypto from 'node:crypto'

const app = express()

// Webhooks need the raw bytes, so this must come before express.json()
app.use('/webhooks', express.raw({ type: 'application/json' }))
app.use(express.json())

function isValidShopifyHmac(rawBody, hmacHeader, secret) {
  if (!hmacHeader || !Buffer.isBuffer(rawBody)) return false
  const digest = crypto.createHmac('sha256', secret).update(rawBody).digest()
  const received = Buffer.from(hmacHeader, 'base64')
  return received.length === digest.length &&
    crypto.timingSafeEqual(digest, received)
}

Two details matter. timingSafeEqual stops an attacker from guessing the signature byte by byte through response timing. The length check comes first because timingSafeEqual throws on unequal lengths, and a thrown error turns a forged request into a 500 instead of a clean rejection.

What goes wrong if you skip this?

Without verification, anyone who finds your URL can post a fake shop/redact and make you wipe a live merchant's data. Or a fake orders/create that kicks off fulfilment logic.

Shopify's automated review checks this directly. It sends compliance webhooks with an invalid signature and expects a 401. Returning 200 to everything, which plenty of tutorials show, fails the check.

Slow responses cause a quieter failure.

Shopify expects a reply within five seconds. Miss that repeatedly and deliveries are marked failed and retried, and the subscription can eventually be removed. Your app then stops receiving events, and you find out when a merchant asks why orders stopped syncing.

Do you need to write this yourself?

Not always. If you built on Shopify's official React Router or Remix app template, authenticate.webhook(request) already verifies the HMAC and returns a 401 on failure. Keep it and skip to the handler logic below.

This walkthrough is for custom Express or Fastify servers, apps moved off older templates, and teams who want to know what the library does for them.

How do you answer quickly and process later?

Verify, enqueue, acknowledge, then do the real work in a background worker. The request handler should do nothing slow: no Admin API calls, no emails, no bulk deletes.

import { Queue } from 'bullmq'

const connection = { host: process.env.REDIS_HOST, port: 6379 }
const webhookQueue = new Queue('shopify-webhooks', { connection })

app.post('/webhooks', async (req, res) => {
  const valid = isValidShopifyHmac(
    req.body,
    req.get('X-Shopify-Hmac-Sha256'),
    process.env.SHOPIFY_API_SECRET,
  )
  if (!valid) return res.sendStatus(401)

  await webhookQueue.add(
    req.get('X-Shopify-Topic'),
    {
      shop: req.get('X-Shopify-Shop-Domain'),
      payload: JSON.parse(req.body.toString('utf8')),
    },
    {
      jobId: req.get('X-Shopify-Webhook-Id'),
      attempts: 5,
      backoff: { type: 'exponential', delay: 10000 },
      removeOnComplete: { age: 7 * 24 * 3600 },
    },
  )

  res.sendStatus(200)
})

Using X-Shopify-Webhook-Id as the job ID gives you deduplication. Shopify delivers at least once, so the same event can arrive twice, and BullMQ ignores a job whose ID it still holds. That is why completed jobs are kept for a week rather than removed instantly. No Redis? A database table with a unique constraint on the webhook ID does the same job.

What must the three GDPR compliance handlers actually do?

Each topic maps to a privacy obligation, and review expects real behaviour, not an empty 200.

customers/data_request: a customer asked the merchant for their data. The payload carries customer.id, customer.email and orders_requested. Gather what your app stores about that customer and give it to the merchant. You have 30 days.
customers/redact: delete or anonymise that customer's data, including the orders listed in orders_to_redact. Shopify holds this request back if the customer ordered recently, so when it arrives, act on it.
shop/redact: sent about two days after a merchant uninstalls. Delete everything you hold for that shop, access tokens included.

import { Worker } from 'bullmq'

new Worker('shopify-webhooks', async (job) => {
  const { shop, payload } = job.data

  switch (job.name) {
    case 'customers/data_request': {
      const customerId = String(payload.customer.id)
      const records = await db.customerRecord.findMany({
        where: { shop, shopifyCustomerId: customerId },
      })
      await db.dataRequest.create({
        data: {
          shop,
          customerId,
          requestId: String(payload.data_request.id),
          export: JSON.stringify(records),
          status: 'ready_for_merchant',
        },
      })
      await notifyMerchant(shop, payload.data_request.id)
      break
    }
    case 'customers/redact': {
      const orderIds = (payload.orders_to_redact ?? []).map(String)
      await db.$transaction([
        db.customerRecord.deleteMany({
          where: { shop, shopifyCustomerId: String(payload.customer.id) },
        }),
        db.orderNote.deleteMany({
          where: { shop, shopifyOrderId: { in: orderIds } },
        }),
      ])
      break
    }
    case 'shop/redact': {
      await db.$transaction([
        db.customerRecord.deleteMany({ where: { shop } }),
        db.orderNote.deleteMany({ where: { shop } }),
        db.session.deleteMany({ where: { shop } }),
      ])
      break
    }
  }
}, { connection })

Then register the topics in shopify.app.toml and run shopify app deploy:

[webhooks]
api_version = "2026-10"

[[webhooks.subscriptions]]
compliance_topics = ["customers/data_request", "customers/redact", "shop/redact"]
uri = "/webhooks"

What do most implementations miss before review?

The handlers above delete rows in your main database. Customer data usually lives in more places than that. Run this checklist before you submit:

Logs. If you log full webhook payloads, customer emails stay in your log store long after the redact. Log the webhook ID and topic, not the body.
Third-party tools. Email, analytics and support tools your app syncs to need their own delete call inside the redact job.
Caches and search indexes. A deleted customer who still shows up in a Redis cache or search index has not been redacted.
A rejection test. Send a request with a made-up HMAC header using curl and confirm you get 401, not 200 or 500.
A delivery test. Use shopify app webhook trigger for each compliance topic and watch the job complete in your worker.

The rule of thumb: if a merchant's customer asked "where is my data?", every answer your system could give should come back empty after the redact job runs.

Where to go from here

Webhooks are one piece of a production Shopify app, alongside billing, rate limits and data sync. For the wider picture, the ecommerce development guide covers how these parts fit together.

If you are close to submitting and want a second pair of eyes, Geminate Solutions offers a free review of your app or plan, with a reply within 24 hours.

Software Acceptance Testing with Playwright Your Client Can Read

Geminate Solutions — Sat, 24 Oct 2026 06:05:06 +0000

Software acceptance testing works best when the person signing off can read the tests themselves. With Playwright, you get there by writing each acceptance criterion as a Given/When/Then step, attaching a screenshot to every step and handing over the HTML report as the sign-off record.

Maybe you have sat in a sign-off call where the client asks "but does it actually do what we agreed?" while you scroll through a green CI log. This tutorial is for you. When you finish, every criterion from the spec will appear in the report in the same words, with pass or fail and a picture next to it.

Why do sign-off meetings stall even when every test passes?

They stall because the tests and the criteria are written in two different languages. The spec says "a trial customer can upgrade to the paid plan from the billing page". The test says await page.click('#btn-upg-2'). Nobody outside the dev team can connect the two.

So the client does what any careful buyer would do. They click through the app themselves, find something that looks off, and the meeting turns into a bug triage session.

The tests passed, but they proved nothing to the person who needed proof.

What does a vague acceptance process cost you?

It costs you the sign-off date. Each round of "let me just check one more thing" pushes the release back. Every disputed criterion turns into an argument about what was agreed instead of a quick look at evidence.

It also costs trust. When clients cannot see what was tested, they assume the worst and start testing everything by hand. That slows every release after this one too.

Who doesn't need this?

Skip this if you are building an internal tool and the person signing off also writes the code. A short checklist in the pull request is enough. This approach pays off when someone outside the dev team has to say yes before the work counts as done.

Step 1: Write the criteria before the tests

Turn each criterion into a numbered, testable sentence and agree it with the client before anyone writes code. A good criterion has one actor, one action and one visible outcome.

AC-04: Given a customer on a trial plan, when they choose the Pro plan on the billing page and confirm, then the billing page shows "Pro" as their current plan.

Reject anything that says "should work well" or "fast". Without a number, a criterion like that can never fail, so nobody can sign it off either.

How do you make each Playwright step read like the criterion?

Wrap test.step in three small helpers so the report says "Given", "When" and "Then" in plain words. Each helper also takes a screenshot, even when the step fails.

// acceptance.ts
import { test, Page } from '@playwright/test'

async function step(page: Page, label: string, body: () => Promise<void>) {
  await test.step(label, async () => {
    try {
      await body()
    } finally {
      await test.info().attach(label, {
        body: await page.screenshot({ fullPage: true }),
        contentType: 'image/png',
      })
    }
  })
}

export const given = (page: Page, text: string, body: () => Promise<void>) =>
  step(page, `Given ${text}`, body)
export const when = (page: Page, text: string, body: () => Promise<void>) =>
  step(page, `When ${text}`, body)
export const then = (page: Page, text: string, body: () => Promise<void>) =>
  step(page, `Then ${text}`, body)

The finally block matters. Without it, a failing step throws before the screenshot is taken, and you lose the one picture the client most needs to see.

How do you set up test data the client can trust?

Create the data for each test through an API and delete it afterwards. Never rely on a shared "test user" that someone edited by hand last week. Once that account drifts, criteria start failing for reasons nobody can explain.

A Playwright fixture handles the setup and the cleanup:

// fixtures.ts
import { test as base } from '@playwright/test'

type Customer = { id: string, email: string, password: string }

export const test = base.extend<{ trialCustomer: Customer }>({
  trialCustomer: async ({ request }, use) => {
    const email = `ac-${Date.now()}@example.test`
    const password = 'Accept-Test-123'
    const res = await request.post('/api/test/customers', {
      data: { email, password, plan: 'trial' },
    })
    const { id } = await res.json()
    await use({ id, email, password })
    await request.delete(`/api/test/customers/${id}`)
  },
})
export { expect } from '@playwright/test'

Only staging and test environments should have the /api/test/customers endpoint. Put it behind an environment flag so it can never reach production.

What does a full criterion look like as a test?

Put the criterion ID in the test title and the original sentence in an annotation. The HTML report shows both at the top of the test.

// billing.spec.ts
import { test, expect } from './fixtures'
import { given, when, then } from './acceptance'

test('AC-04: A trial customer can upgrade to Pro', async ({ page, trialCustomer }) => {
  test.info().annotations.push({
    type: 'Criterion',
    description: 'Given a customer on a trial plan, when they choose the Pro plan on the billing page and confirm, then the billing page shows "Pro" as their current plan.',
  })

  await given(page, 'a customer on a trial plan is signed in', async () => {
    await page.goto('/login')
    await page.getByLabel('Email').fill(trialCustomer.email)
    await page.getByLabel('Password').fill(trialCustomer.password)
    await page.getByRole('button', { name: 'Sign in' }).click()
    await expect(page.getByText('Trial')).toBeVisible()
  })

  await when(page, 'they choose the Pro plan and confirm', async () => {
    await page.goto('/billing')
    await page.getByRole('button', { name: 'Choose Pro' }).click()
    await page.getByRole('button', { name: 'Confirm upgrade' }).click()
  })

  await then(page, 'the billing page shows Pro as the current plan', async () => {
    await expect(page.getByTestId('current-plan')).toHaveText('Pro')
  })
})

getByRole and getByLabel find elements by the words a person sees on screen, so even the code reads close to the criterion. Keep the "Then" step to assertions only. If it clicks anything, you are really testing two criteria.

How do you produce the report you hand over at sign-off?

Turn on the HTML reporter with a fixed output folder and keep traces for failures:

// playwright.config.ts
import { defineConfig } from '@playwright/test'

export default defineConfig({
  reporter: [['html', { outputFolder: 'acceptance-report', open: 'never' }]],
  use: {
    baseURL: process.env.BASE_URL ?? 'http://localhost:3000',
    trace: 'retain-on-failure',
  },
})

Run BASE_URL=https://staging.example.com npx playwright test, then zip the acceptance-report folder. The client unzips it and runs npx playwright show-report acceptance-report, or you host the folder on any static URL, because the report needs to be served over HTTP. Each test shows its AC number, the criterion sentence, every step with a pass or fail mark, and a screenshot under each step.

What should you check before sending the report?

Run through this list first:

Every agreed criterion has a test. Compare the AC numbers in the spec with the test titles. A missing criterion looks like something you hid.
The run used the build being signed off. Put the commit hash in the zip file name and in an annotation, so nobody argues later about which build was tested.
Failures stay in. If AC-09 fails, send it as failed with a note. A report where everything is green looks suspicious and invites a manual retest.
No real customer data appears in screenshots. Use fixture data only, with obvious test emails.
Flaky tests get fixed, not retried until they pass. If a criterion needs retries to pass, the client will run into the same flakiness in real use.

Where do you start with software acceptance testing on your next project?

Start at your next sign-off. Pick the three criteria the client cares about most, write them as Given/When/Then tests with the helpers above, and send the report before the meeting instead of during it.

If you want help setting this up, or want to know whether your current tests cover what you agreed with your client, Geminate Solutions offers a free review of your app and test plan and replies within 24 hours. Details are on the software testing and QA page.

Legacy Application Modernization: Freeze Features or Keep Shipping?

Geminate Solutions — Fri, 23 Oct 2026 11:58:13 +0000

Most legacy application modernization projects fail on two simple options: a full feature freeze, or shipping new work on both systems for as long as the rebuild takes. The rule that usually works is a short, dated freeze on the area being rebuilt. Agree in writing that new features go only on the new system once each part of it is live.

If you are a CTO, you know this meeting. Sales has deals waiting on a feature. The old system gets more fragile with every release. Someone senior asks why the team can't just do both. This piece covers what each option costs in team time, risk and business pressure. It also shows how to get the business to agree the rule before anyone writes new code.

What are the three options, in plain terms?

There are three options, and each one moves the pain somewhere different. Pick based on where your organisation can take that pain.

Full feature freeze. Nothing new ships on the old system until the new one replaces it. The team stays focused and the business waits.
Dual build. New features ship on the old system and are also built, or later ported, on the new one. The business keeps moving and the team pays for every feature twice.
New features only on the new system. The old system gets bug fixes, security patches and legal changes, nothing else. Any new capability is built on the new system, which goes live module by module next to the old one.

Why does a full feature freeze feel safe but rarely hold?

A freeze is easy to explain and engineers like it. It breaks because rebuilds almost always take longer than planned, and the business stops waiting long before the rebuild is finished.

The delay usually comes from inside the old system. Ten years of code hides business rules nobody wrote down: a discount that only applies to one region, or a report finance relies on every month-end. Each one you find adds weeks.

Then comes the first exception: one urgent feature for one important customer. Then a second one. Now you are running a dual build that nobody planned or budgeted for.

The early warning sign is simple. If someone asks for an exception in the first few weeks, your freeze will not last, so change the plan now.

What does a dual-build period cost your team?

A dual build lets the business keep shipping, but every feature needs two specs, two builds and two rounds of testing. The visible cost is time. The hidden cost is that the two systems slowly drift apart.

Drift is quiet. The old system rounds tax one way and the new one rounds it another way. A validation rule gets updated in one place and not the other. These gaps stay hidden until cutover, when real customer data runs through the new system and the numbers don't match.

There is a people cost too. The engineers who know the old system best get pulled back to maintain it, so the rebuild is left with the people who understand the business least. That is the opposite of what you need.

Is "new features only on the new system" the best default?

For most mid-size systems, yes, if the new system can go live in slices. It forces you to ship real parts of the rebuild early, and it keeps engineers from building the same feature twice.

It works best with the strangler approach. You put a routing layer in front of the old application and move one module at a time, such as billing, then scheduling, then reporting. Each module is switched over to the new system and its old code path is turned off.

The cost is that the business may wait for a feature until its area has moved. You can reduce that wait by migrating the areas with the most demand first, even when they are not the easiest technically. The real engineering work is the overlap: shared login, shared data, and keeping records in sync while both systems run. Plan for that from the start.

What does it cost to get this decision wrong?

The worst result is a rebuild that never finishes, where you run two systems indefinitely with a team split between them. You keep paying for both systems and never get the benefits of the new one.

You also lose trust. A freeze that breaks after two months makes leadership doubt every date you give them afterwards. Data mismatches at cutover can mean wrong invoices, missing records or a rollback in front of customers. Good engineers get tired of building the same thing twice and leave.

None of this comes from bad code. It comes from a rule that was never agreed, or was agreed vaguely.

Who can skip all of this?

Some teams don't need a formal rule. If the old system is small enough to rebuild in a few weeks, or the product is in maintenance mode with almost no feature requests, just freeze it and move on.

The same goes if your project is a hosting move rather than a rewrite. Moving an application to new infrastructure without changing its behaviour rarely needs a feature policy. A cutover plan and a rollback plan are usually enough.

How do you agree the rule with the business before the rebuild starts?

Put the rule on paper and get it signed by the people who will push hardest against it. Usually that means the CEO, the head of product and the head of sales. Do this before work starts, not when the first exception request arrives.

A sequence that works:

List the roadmap for the next two quarters, with a named business owner for each item.
Sort each item into one of three groups: must ship on the old system (legal, contractual or tied to a fixed date), can wait, or can be built on the new system first.
Write the exception process. Name who can approve a change to the old system, what evidence they need, and how many weeks of rebuild delay the requester agrees to accept. Making that trade-off visible stops most casual requests.
Put dates on everything. The freeze needs an end date and a review checkpoint, not "until it's done".
Define "done" for each slice as the old code path being switched off, not "the new version works".

Use these decision rules to choose:

If your situation is...	Then choose...
Short rebuild, light roadmap	Full freeze with a fixed end date
System splits into clear modules	New features only on the new system, busiest areas first
Contractual commitments on the old system, hard to split	Short dual build with a hard cap, porting each feature in the same sprint

What should you ask your team or vendor before committing?

These questions show quickly whether a plan will survive contact with the business. Vague answers usually mean the rule hasn't been thought through.

Which module goes first, and was it chosen for business demand or because it is technically easy?
How will data stay consistent while both systems are live, and who checks it?
Who is responsible for finding the undocumented business rules in the old code?
What exactly happens when sales asks for an exception?
On what date is each old code path turned off?

At Geminate Solutions, after 50+ products shipped, we have learned that the agreement matters as much as the architecture.

For the full picture on approaches and sequencing, read our guide to legacy system modernization. If you want another pair of eyes on your plan, ask Geminate Solutions for a free review. We reply within 24 hours.

eLearning Software Development: Accept LTI 1.3 Launches in Node.js

Geminate Solutions — Fri, 23 Oct 2026 03:59:38 +0000

In eLearning software development, getting your product to run inside Moodle or Canvas means accepting an LTI 1.3 launch. In Node.js, that takes three steps: answer an OIDC login request, verify a signed JWT against the platform's public keys, and turn the claims inside it into your own users and courses. The hard part is the handful of checks that stop one school's teacher from landing in another school's data.

This walkthrough is for you if a district just asked "does it work with Canvas?" and your team is now reading the IMS spec.

What actually happens during an LTI 1.3 launch?

A launch is an OpenID Connect login. The LMS is the identity provider and your app is the client. The LMS starts the flow, your app sends the browser back with a state and a nonce, and the LMS returns a signed id_token through a form POST.

In order:

The LMS sends the browser to your login URL with iss, login_hint, target_link_uri and usually client_id and lti_message_hint.
Your app stores a state and a nonce, then redirects to the platform's authorization endpoint.
The platform POSTs id_token and state to your launch URL.
You verify the token, run the LTI checks and start a session.

In Moodle, the endpoints are under /mod/lti/: auth.php handles authorization and certs.php serves the key set. On Canvas cloud the issuer is https://canvas.instructure.com and the endpoints are on sso.canvaslms.com. Every Canvas cloud customer shares that one issuer, so client_id is how you tell registrations apart.

What does a sloppy launch cost you?

Most launch bugs fail silently. They let the wrong person in, or they quietly create duplicate accounts.

Without a nonce check, someone who captures an id_token can replay it and sign in as that teacher until the token expires. Without a deployment ID check, any Canvas account that installs your developer key gets in, including schools that never signed a contract. If you match users on email, accounts get mixed up when a school hides emails or a student changes theirs.

Each of these ends up as a ticket from a school IT director, and that IT director has a say in your renewal.

Do you need to build this yourself?

Not always. If you connect to a single Moodle site you control, a maintained library such as ltijs will get you there faster than writing it by hand.

Write it yourself when you serve many institutions, own your user model or need to audit exactly what you trust. The code below uses Express, jose and Redis.

Step 1: handle the OIDC login request

import express from 'express'
import cookieParser from 'cookie-parser'
import crypto from 'node:crypto'
import Redis from 'ioredis'

const app = express()
const redis = new Redis(process.env.REDIS_URL)
app.use(express.urlencoded({ extended: false }))
app.use(cookieParser())

// One entry per registration. Canvas cloud shares one issuer, so match on client_id too.
const platforms = [{
  issuer: 'https://moodle.example.edu',
  clientId: 'moodle-client-id',
  authUrl: 'https://moodle.example.edu/mod/lti/auth.php',
  jwksUrl: 'https://moodle.example.edu/mod/lti/certs.php',
  deploymentIds: ['1'],
}]

const findPlatform = (iss, clientId) =>
  platforms.find(p => p.issuer === iss && p.clientId === clientId)

app.all('/lti/login', async (req, res) => {
  const p = { ...req.query, ...req.body }
  const platform = findPlatform(p.iss, p.client_id)
  if (!platform) return res.status(400).send('Unknown platform')

  const state = crypto.randomUUID()
  const nonce = crypto.randomUUID()
  await redis.set(`lti:${state}`,
    JSON.stringify({ nonce, iss: platform.issuer, clientId: platform.clientId }), 'EX', 600)
  res.cookie('lti_state', state, { httpOnly: true, secure: true, sameSite: 'none', maxAge: 600_000 })

  const url = new URL(platform.authUrl)
  url.search = new URLSearchParams({
    scope: 'openid', response_type: 'id_token', response_mode: 'form_post',
    prompt: 'none', client_id: platform.clientId,
    redirect_uri: 'https://tool.example.com/lti/launch',
    login_hint: p.login_hint, state, nonce,
    ...(p.lti_message_hint && { lti_message_hint: p.lti_message_hint }),
  })
  res.redirect(url.toString())
})

Two details matter here. First, the state cookie has to be SameSite=None and Secure. The launch arrives as a cross-site POST, and a default Lax cookie is not sent back on it. Second, platforms can send the login as either GET or POST, so app.all accepts both. If a platform leaves out client_id, fall back to matching on the issuer alone, but only when you have exactly one registration for that issuer.

How do you verify the id_token against the platform's JWKS?

Use createRemoteJWKSet from jose and let jwtVerify check the signature, issuer, audience and expiry. The key set is fetched once and cached. It is fetched again when a token arrives with a key ID it has not seen, so key rotation on the platform side needs no work from you.

import { createRemoteJWKSet, jwtVerify } from 'jose'

const keySets = new Map()
const keySet = url => {
  if (!keySets.has(url)) keySets.set(url, createRemoteJWKSet(new URL(url)))
  return keySets.get(url)
}
const LTI = 'https://purl.imsglobal.org/spec/lti/claim/'

app.post('/lti/launch', async (req, res) => {
  const { id_token, state } = req.body
  if (!state || state !== req.cookies.lti_state) return res.status(401).send('State mismatch')

  const saved = await redis.getdel(`lti:${state}`)
  if (!saved) return res.status(401).send('Login expired or already used')
  const { nonce, iss, clientId } = JSON.parse(saved)
  const platform = findPlatform(iss, clientId)

  let claims
  try {
    ({ payload: claims } = await jwtVerify(id_token, keySet(platform.jwksUrl), {
      issuer: platform.issuer, audience: platform.clientId, clockTolerance: 30,
    }))
  } catch {
    return res.status(401).send('Invalid token')
  }

  if (claims.nonce !== nonce) return res.status(401).send('Nonce mismatch')
  if (Array.isArray(claims.aud) && claims.aud.length > 1 && claims.azp !== platform.clientId)
    return res.status(401).send('Bad azp')
  if (claims[LTI + 'version'] !== '1.3.0') return res.status(400).send('Wrong LTI version')
  if (claims[LTI + 'message_type'] !== 'LtiResourceLinkRequest')
    return res.status(400).send('Wrong message type')
  const deploymentId = claims[LTI + 'deployment_id']
  if (!platform.deploymentIds.includes(deploymentId))
    return res.status(403).send('Unknown deployment')

  // mapping continues below
})

Which checks does most sample code leave out?

A valid signature only proves the LMS issued the token. It does not prove the token is fresh, that it belongs to this login, or that it comes from a deployment you agreed to serve. Each of those needs its own check.

Nonce, used once. Compare it with the stored value and delete the record in the same step. GETDEL does both, so posting the same token a second time fails.
State tied to the browser. The cookie and the form field must match. Otherwise an attacker can push their own launch into someone else's browser session.
Deployment ID allowlist. One Canvas developer key can be installed in many sub-accounts, and each install gets its own deployment_id. Accept only the ones you registered.
azp when aud is an array. If the audience has more than one value, azp must equal your client ID.

The message_type check matters as well. Without it, a deep-linking message could reach your resource launch handler.

How do you map launch claims to your own users and courses?

Identify users by iss plus sub. Identify courses by iss, deployment_id and the context id. Names, emails and course titles are display data: update them on every launch and never use them as identifiers.

// inside the launch handler, after the checks. `db` is your own data layer.
const user = await db.users.upsert({
  where: { issuer: claims.iss, subject: claims.sub },
  set: { name: claims.name, email: claims.email ?? null },
})
const context = claims[LTI + 'context'] ?? {}
const course = await db.courses.upsert({
  where: { issuer: claims.iss, deploymentId, contextId: context.id },
  set: { title: context.title },
})
const roles = claims[LTI + 'roles'] ?? []
const isTeacher = roles.some(r => /#(Instructor|Administrator)$/.test(r))
await db.enrolments.upsert({ userId: user.id, courseId: course.id, role: isTeacher ? 'teacher' : 'student' })

const target = new URL(claims[LTI + 'target_link_uri'])
if (target.origin !== 'https://tool.example.com') return res.status(400).send('Bad target')
req.session.userId = user.id
res.redirect(target.pathname + target.search)

If a teacher runs the same course at two schools, they get two course records. That is the correct result. Roles arrive as full URIs, so match on the suffix and not on the bare word Instructor. Some launches come from outside a course and have no context claim, so skip the course step when it is missing.

How do you test against Moodle and Canvas before a school does?

Run Moodle locally in Docker, register your app as an External tool and launch it from a course. Then do the same in a Canvas test instance.

Run four tests on each platform: post the same launch twice (the second must fail), launch from a deployment you have not registered (expect a 403), launch once as a student and once as a teacher, and launch as a user with no email. Then try Safari. When your tool runs in an iframe, Safari's third-party cookie blocking can drop your state cookie. The fix is to open the tool in a new window or to support the LTI platform storage messages that Canvas offers.

Where does the launch fit in eLearning software development?

The launch only gets people in the door. Behind it come grade passback through Assignment and Grade Services, roster sync through Names and Role Provisioning, and the tenant model that keeps each school's data separate. If your identity keys are right from day one, those later pieces stay simple.

Geminate Solutions has built EdTech systems, including an EdTech platform with 250K+ daily active users. The LMS integration decisions made early tend to shape whatever comes after them.

If you are planning bigger changes, read the EdTech platform rewrite guide, or send Geminate Solutions your launch flow for a free review, with a reply within 24 hours.

EHR Integration: Matching Patients Without Duplicates or Mix-Ups

Geminate Solutions — Wed, 21 Oct 2026 18:54:11 +0000

In EHR integration, the safe way to match patients is to rely first on the identifier the hospital's EHR already trusts. That is its own patient ID or MRN, tied to the system that issued it. Use exact rules when you have that ID. Use scored matching only for the cases where you don't, and send every uncertain result to a human instead of letting your system guess.

You probably know the situation. Your product collects patient details at intake. The hospital has its own records in Epic, Oracle Health or something older. Somebody has to decide whether "Jon Smith, 07/03/1984" in your database is the same person as "Jonathan Smith, 03/07/1984" in theirs. If you decide wrong one way, you create a duplicate. If you decide wrong the other way, you attach one patient's results to someone else.

Why is patient matching hard when both systems have the data?

The US has no national patient identifier, and the data people type in is messy. An MRN is only unique inside the facility that issued it. So an MRN from one hospital means nothing to the clinic down the road, and it means nothing to your app unless you store which system it came from.

The usual ways matching fails are predictable:

Day and month swapped in a date of birth, especially when staff or patients use different date formats.
Name changes after marriage or divorce, hyphenated surnames, nicknames, and first and middle names entered the wrong way round.
Twins and family members who share a surname, an address, a phone number and sometimes an insurance subscriber ID.
Newborns registered as "Baby Girl Patel" and renamed days later.
Junior and senior with the same name at the same address.

Every one of these looks like a perfect match on some fields and a clear mismatch on others.

Deterministic or probabilistic matching: which should you use?

Use both, in that order. Deterministic matching links records only when specific fields agree exactly, for example the same MRN from the same issuing system. Probabilistic matching gives each field a score and adds them up.

Deterministic rules are predictable and easy to explain to a hospital's compliance team. Their weakness is that a single typo means no match, so you get duplicates.

Probabilistic matching, usually based on the Fellegi-Sunter model, handles messy data better. A matching rare surname counts for more than a matching "Smith". A matching date of birth counts for more than a matching sex. You then set two thresholds:

Above the upper threshold: link automatically.
Below the lower threshold: treat as a new or different patient.
In between: send to human review.

If the hospital supports the FHIR Patient/$match operation, it will return candidates with a grade such as certain, probable or possible. Treat only "certain" as safe to link without a person checking. A "probable" result is still a guess.

Which identifiers should you rely on?

Not all fields deserve the same trust. This is a sensible starting order:

Identifier	Trust	Why
EHR patient ID or MRN plus issuing system	High	It is the hospital's own key, but only within that system
Date of birth	High	Stable, but watch for day and month swaps
Legal first and last name	Medium	Changes over a lifetime, and spellings vary
Phone and email	Medium	Families share them, and numbers get recycled
Last four of SSN	Medium	Useful when present, often missing, and sensitive to store
Sex	Low	Too few values to tell people apart, and it can change
Address	Low	People move, and households share it

One field should never be enough by itself: the insurance member ID. Dependants often share the subscriber's number, and it changes when the employer switches plans.

Once a link is confirmed, store the EHR's patient ID against your record. From then on, match on that ID and stop re-matching on demographics.

What does it cost you to get this wrong?

Duplicates are the mild failure. A patient's history gets split across two records, so a clinician may miss an allergy or order a test that was already done. Someone at the hospital then has to find and merge the records by hand.

Overlays are the serious failure. An overlay is two different people merged into one record. Lab results, notes and medications go to the wrong person. That is a clinical safety problem and a privacy disclosure at the same time. Separating the records afterwards is slow, manual work, and some hospitals will switch off an interface until it has been cleaned up.

Trust matters too. Hospital integration teams remember the vendor whose feed created a mess, and that memory comes back at contract renewal and in reference calls.

When do you not need any of this?

If your app runs inside the EHR through a SMART on FHIR launch, the EHR tells you which patient is open. There is nothing to match. The same goes for an app that only receives patients from the hospital's ADT feed with the MRN attached.

In those setups, store the ID the EHR gives you and handle merge events properly. You only need matching logic when your system creates patients on its own, for example through self-registration, a referral form or a partner's data, and then has to connect them to hospital records.

How should the human review queue work?

The queue is where uncertain matches get settled, so it needs an owner, a clear screen and a record of every decision.

Show both records side by side with the differing fields highlighted. Give the reviewer three choices: same person, different people, or needs more information. Save the decision, the reason and the reviewer's name.

While a match is pending, hold the clinical data for that patient. Do not create a placeholder record that someone will have to merge later. Remember every "different people" decision so the same pair is not flagged again next week.

Track how long items sit in the queue. A queue nobody works is worse than having no queue, because it hides data clinicians expect to see. Review the decisions every month and use them to adjust your thresholds.

What should you require from the team before any patient data syncs?

Before a single record moves, ask your team or vendor for these:

A written matching policy, agreed with the hospital's health information management team. They own record integrity, and they will have to live with your rules.
A test set of hard cases (twins, name changes, swapped dates, newborns) built from synthetic or de-identified data, with the expected result written down for each one. Without it, nobody can tell whether a threshold works.
Thresholds set from test results, not guessed. Guessed numbers drift towards whatever clears the backlog fastest.
Handling for EHR merges and unmerges, through HL7 v2 ADT A40 messages or the FHIR Patient.link "replaced-by" field. Hospitals merge records all the time, and your links have to follow.
An audit trail for every link and unlink, so you can answer when a record was linked, why, and by whom.
A way to unlink. If a link cannot be reversed, an overlay becomes permanent.
A dry run period where matching runs against the real feed without writing anything, so you can review the results first.
Monitoring of new duplicates, queue size and manual overrides, with alerts when any of them jumps.

A good question for any vendor: "Show me what your system does when the EHR merges two patients we have already linked." A vague answer tells you what you need to know.

If you are planning an integration and want a second opinion on your matching approach, our guide to healthcare app development covers the wider build. You can also send your plan to Geminate Solutions for a free review. We sign an NDA before we talk and reply within 24 hours.

Find underused EC2 instances and unattached EBS volumes with Node.js

Geminate Solutions — Wed, 21 Oct 2026 18:40:00 +0000

You can find underused EC2 instances and unattached EBS volumes with one Node.js script. It pulls 14 days of CloudWatch CPU and network metrics for every running instance, flags the ones that barely move, and lists every volume whose status is available. That covers most of the quick wins in cloud optimization, and it only needs read-only permissions.

This is for you if your AWS bill keeps growing while traffic stays flat and nobody can say for sure which servers still do real work. The script writes two CSV files that your team can go through in one meeting.

Why do idle instances and orphaned volumes pile up?

Creating resources is easy, and nobody is in charge of deleting them. Someone spins up a staging box for a demo. A load test leaves a fleet at its peak size. An Auto Scaling group gets replaced and its old instances stay behind.

Volumes are worse. When you terminate an instance, only volumes with DeleteOnTermination set to true are deleted with it. Data volumes attached later default to false, so they stay behind, detached and still billed for every provisioned GiB.

Oversizing has a different cause. Teams pick a size at launch with room for a spike that never comes. Once the app works, nobody looks at the size again.

What does it cost you to leave this alone?

The direct cost is paying every hour, with no end date, for capacity nobody uses. Four things drive it: instance size, instance count, hours running and provisioned GiB on every volume.

The indirect cost is harder to see. An account full of unnamed resources with no owner slows every security review and hides real capacity problems. The next person who tries to clean up is afraid to touch anything, and with good reason.

Delete the wrong volume and you can lose data you will never get back.

Who does not need this script?

If you run a handful of instances in one region, use AWS Compute Optimizer and the rightsizing view in Cost Explorer. Both look at a similar 14 day window and need no code. Compute Optimizer only needs you to opt in.

The script is worth it when you have several accounts or regions, want to set your own thresholds, or need a report you can run in CI every week and compare over time.

How does the script decide what is idle or oversized?

It pulls hourly data points for 14 days and applies a few simple rules. Fourteen days covers two full weeks, so a batch job that only runs on Sundays still shows up.

Verdict	Rule	Suggested action
IDLE	p95 of hourly max CPU under 5% and under 50 MB of network a day	Find the owner, then stop it
OVERSIZED	Average CPU under 10% and p95 peak under 40%	Test one size smaller
NO_DATA	No CloudWatch data points	Probably launched recently, check again later
OK	Anything else	Leave it

The script uses the 95th percentile of hourly peaks instead of the single highest value. That way one spike during a deploy does not hide a server that is otherwise idle.

One limit you should know about: EC2 does not send memory metrics to CloudWatch by default. A database or cache with low CPU can still be using most of its RAM. If you run the CloudWatch agent, add mem_used_percent from the CWAgent namespace before you trust an OVERSIZED verdict on those machines.

The script

Install the two SDK clients:

npm i @aws-sdk/client-ec2 @aws-sdk/client-cloudwatch

The role running it needs only ec2:DescribeInstances, ec2:DescribeVolumes and cloudwatch:GetMetricData. GetMetricData is billed per metric requested, so the cost of each run grows with your instance count (four metrics per instance). Run it weekly, not every minute.

// rightsize.mjs
import { EC2Client, paginateDescribeInstances, paginateDescribeVolumes } from '@aws-sdk/client-ec2'
import { CloudWatchClient, GetMetricDataCommand } from '@aws-sdk/client-cloudwatch'
import { writeFileSync } from 'node:fs'

const region = process.env.AWS_REGION || 'us-east-1'
const DAYS = 14
const ec2 = new EC2Client({ region })
const cw = new CloudWatchClient({ region })
const end = new Date()
const start = new Date(end.getTime() - DAYS * 86400000)

async function listRunningInstances() {
  const out = []
  const pages = paginateDescribeInstances({ client: ec2 }, {
    Filters: [{ Name: 'instance-state-name', Values: ['running'] }]
  })
  for await (const page of pages) {
    for (const r of page.Reservations ?? []) {
      for (const i of r.Instances ?? []) {
        const name = i.Tags?.find(t => t.Key === 'Name')?.Value ?? ''
        out.push({ id: i.InstanceId, type: i.InstanceType, name: name.replace(/,/g, ' ') })
      }
    }
  }
  return out
}

function queriesFor(inst, n) {
  const dims = [{ Name: 'InstanceId', Value: inst.id }]
  const q = (id, metric, stat) => ({
    Id: id + '_' + n,
    MetricStat: {
      Metric: { Namespace: 'AWS/EC2', MetricName: metric, Dimensions: dims },
      Period: 3600,
      Stat: stat
    }
  })
  return [
    q('cpuavg', 'CPUUtilization', 'Average'),
    q('cpumax', 'CPUUtilization', 'Maximum'),
    q('netin', 'NetworkIn', 'Sum'),
    q('netout', 'NetworkOut', 'Sum')
  ]
}

async function fetchMetrics(instances) {
  const values = {}
  for (let b = 0; b < instances.length; b += 100) {
    const queries = instances.slice(b, b + 100).flatMap((inst, k) => queriesFor(inst, b + k))
    let NextToken
    do {
      const res = await cw.send(new GetMetricDataCommand({
        StartTime: start, EndTime: end, MetricDataQueries: queries, NextToken
      }))
      for (const r of res.MetricDataResults ?? []) {
        values[r.Id] = (values[r.Id] ?? []).concat(r.Values ?? [])
      }
      NextToken = res.NextToken
    } while (NextToken)
  }
  return values
}

async function listUnattachedVolumes() {
  const out = []
  const pages = paginateDescribeVolumes({ client: ec2 }, {
    Filters: [{ Name: 'status', Values: ['available'] }]
  })
  for await (const page of pages) {
    for (const v of page.Volumes ?? []) {
      out.push({
        id: v.VolumeId,
        type: v.VolumeType,
        sizeGiB: v.Size,
        ageDays: Math.round((end - v.CreateTime) / 86400000),
        snapshot: v.SnapshotId || ''
      })
    }
  }
  return out
}

const sum = a => a.reduce((s, v) => s + v, 0)
const avg = a => (a.length ? sum(a) / a.length : null)
function p95(a) {
  if (!a.length) return null
  const sorted = [...a].sort((x, y) => x - y)
  return sorted[Math.floor(sorted.length * 0.95)]
}

function classify(cpuAvg, cpuPeak, netMBPerDay) {
  if (cpuAvg === null) return 'NO_DATA'
  if (cpuPeak < 5 && netMBPerDay < 50) return 'IDLE'
  if (cpuAvg < 10 && cpuPeak < 40) return 'OVERSIZED'
  return 'OK'
}

const instances = await listRunningInstances()
const metrics = await fetchMetrics(instances)

const rows = instances.map((inst, n) => {
  const cpuAvg = avg(metrics['cpuavg_' + n] ?? [])
  const cpuPeak = p95(metrics['cpumax_' + n] ?? [])
  const netBytes = sum(metrics['netin_' + n] ?? []) + sum(metrics['netout_' + n] ?? [])
  const netMBPerDay = netBytes / DAYS / 1e6
  return { ...inst, cpuAvg, cpuPeak, netMBPerDay, verdict: classify(cpuAvg, cpuPeak, netMBPerDay) }
})
const volumes = await listUnattachedVolumes()

const fmt = v => (typeof v === 'number' ? v.toFixed(1) : (v ?? ''))
const toCsv = list => [Object.keys(list[0]).join(',')]
  .concat(list.map(r => Object.values(r).map(fmt).join(',')))
  .join('\n')

if (rows.length) writeFileSync('instances.csv', toCsv(rows))
if (volumes.length) writeFileSync('volumes.csv', toCsv(volumes))
console.table(rows.filter(r => r.verdict !== 'OK'))
console.table(volumes)

GetMetricData accepts up to 500 queries per call. The script sends 100 instances (400 queries) at a time and follows NextToken until it has every data point. Run it with AWS_REGION=eu-west-1 node rightsize.mjs, then repeat for each region you use.

How do you act on the report without breaking production?

Go from the cheapest and safest change to the riskiest.

Unattached volumes older than 30 days. Take a snapshot, tag it with the volume ID and the date, then delete the volume. A snapshot is billed on the data actually stored, not the provisioned size.
IDLE instances. If the instance has an owner tag, message the owner. If nobody claims it within a week, stop it but do not terminate it. A stopped instance keeps its volumes, so you can start it again if someone turns out to need it.
OVERSIZED instances. Move down one size in the same family, for example m5.2xlarge to m5.xlarge, during a quiet window. Watch latency and error rates for a few days before you go smaller again.

These rules are worth writing down for the team:

If it is a burstable T family instance, check CPUCreditBalance before you downsize. A smaller T instance earns credits more slowly, and an app that runs out of credits gets throttled.
If it belongs to an Auto Scaling group, change the launch template, not the instance. If you change only the instance, the group replaces it at the old size.
If CPU is low but the app is slow, the problem is somewhere else: disk, database or memory. Downsizing will make it worse.

What should you check before deleting a volume?

Check three things. First, ageDays counts from when the volume was created, not when it was detached. Look up the DetachVolume event in CloudTrail to see how long it has really been unused. If CloudTrail shows nothing in its 90 day event history, the volume has been detached for longer than that.

Second, read its tags for a project or owner. Third, if the snapshot column is empty, nothing backs this volume up yet, so take a snapshot first.

The cleanup is the easy part. Keeping the account clean takes tagging rules, named owners and sensible default sizes in your infrastructure code. If you want a second opinion on your AWS setup, Geminate Solutions offers a free review through its cloud and DevOps service and replies within 24 hours.

Online Assessment Platform Integrity: Server Controls vs Theatre

Geminate Solutions — Wed, 21 Oct 2026 06:09:58 +0000

Online assessment platform integrity depends on what your server controls, not on what the browser is told to block. Question sets issued by the server, per-student randomisation, server-side timing and answer-pattern checks hold up under pressure. Fullscreen locks, copy-paste blocking and tab-switch alerts mostly don't.

Maybe a university partner, a certification body or your own board has asked you a direct question: how do we stop cheating? You have a lockdown ticket in the backlog, a proctoring vendor's deck in your inbox and limited engineering time. This article is about where that time should go.

Why can a student get around browser lockdowns?

The browser runs on the student's machine, and the student controls that machine. Anyone can read, pause or override a check written in JavaScript by opening developer tools, installing an extension or running the exam inside a virtual machine.

Tab-switch detection is the clearest example. It listens for focus and visibility events. A phone on the desk, a second laptop or a friend on a call never fires those events. So the control catches the student who opened another tab by accident and misses the one who planned ahead.

Copy-paste blocking works the same way. It stops casual copying and does nothing against a phone camera.

The bigger leak usually isn't about lockdown at all. It's the API response. Many platforms load the whole test into the page at the start, including correct answers or scoring keys, so the front end can grade instantly. Anyone who opens the network tab has the answer key. No lockdown fixes that.

Which anti-cheating controls actually hold?

The ones the student can't touch. If the server decides what is shown, when time runs out and what counts as suspicious, there is nothing on the student's device worth tampering with.

Server-issued question sets. The client asks for the next question and gets only that question, with no correct answer attached. The server stores the answer and grades it. Trade-off: this means more round trips, so an honest student on weak mobile data feels every slow request. You need retries and saved progress so a dropped request never loses an answer.

Per-student randomisation. Draw each question from a pool, shuffle the options and, where it makes sense, change the numbers inside the question. A shared screenshot then helps far less. Trade-off: the versions have to be equally hard, or some honest students get a harder paper by chance. Store the random seed for every attempt so you can show any student exactly what they saw when they appeal.

Server-side timing. The server records when the attempt started and rejects answers after the deadline. The countdown on screen is only a display. Trade-off: a dropped connection uses up real exam time. Set your policy in advance, for example a short grace period after reconnecting, and log every gap so support can judge cases fairly.

Answer-pattern checks. After each sitting, look for answers submitted faster than anyone could read the question. Look for groups of students who share the same unusual wrong answers, and for many attempts coming from one network or device. Shared wrong answers are a much stronger signal than shared right ones, because right answers are supposed to match. Trade-off: false positives. A flag should start a human review and never change a grade by itself.

What does weak online assessment platform integrity cost you?

A leaked answer key doesn't stay with one student. It spreads through a group chat during the first sitting, and by the second sitting the results tell you nothing. The institution voids the exam, students re-sit it, and your platform takes the blame.

The opposite mistake hurts too. Aggressive lockdowns break screen readers and other assistive tools. They also flag honest students whose browsers lose focus for ordinary reasons, like a system notification. Each false flag turns into an appeal, a support ticket and a student who no longer trusts the result.

Then there is load. With server-issued questions, every student calls your API in the same minute. If a whole cohort starts at 10:00, your integrity design is also a traffic design. Our guide to handling exam-day load on an assessment platform covers that side.

Do you need all of this?

Not always.

If your tests are practice quizzes, open-book by design or low-stakes, shuffle the options, keep answers off the client and stop there. The rest adds cost and friction, and honest students will feel it more than any cheater.

The exception is an exam in a supervised room on devices you manage. There, a locked kiosk browser such as Safe Exam Browser does work, because you control the hardware as well as the software. On a student's own laptop, lockdown is theatre. On your machines, it's a real control.

In what order should you build these controls?

Start with what leaks the most and costs the least to fix.

Audit what the client receives. Open the network tab during a live test. If any response contains correct answers, scoring rules or the full question bank, fix that before anything else.
Move timing to the server. If the deadline exists only in the front end, a paused script or an edited request can extend it.
Add question pools and randomisation. Do this next if the same exam runs in more than one time slot or for more than one cohort. If one group sits it once, at one time, it can wait.
Log events and run pattern checks. Record timing, answer changes, focus events and network data. Have a person review the flags after each sitting.
Consider lockdown or remote proctoring last. Treat browser events as signals for review, not as verdicts. Add them only when the stakes justify the friction for honest students.

What should you ask a vendor or your own team?

These questions separate real controls from a feature list:

What does the API return when a question loads? If the answer is in there, nothing else matters yet.
Where is the deadline enforced? The only acceptable answer is the server.
Can you reproduce exactly what one student saw? Without stored seeds, appeals turn into arguments.
What happens to a student who loses connection for 90 seconds? A vague answer means honest students will lose marks.
Who reviews a flag before it affects a grade? If nobody does, expect appeals you can't defend.
What happens when 20,000 students press start at once? Integrity controls that fail at peak load protect nobody.

Geminate Solutions has built an exam platform with 10M+ requests per minute handled in production. That work taught one simple lesson: integrity and scale are the same design problem. Every control you move to the server adds another request at the busiest moment of the day.

If that peak worries you, read our guide to EdTech login storm architecture, or ask Geminate Solutions for a free review of your exam flow. You'll get a reply within 24 hours.

A GitHub Actions Security Gate for Node.js: Block Leaked Keys

Geminate Solutions — Wed, 21 Oct 2026 05:00:34 +0000

A GitHub Actions security gate for Node.js is a single workflow that runs on every pull request. It scans the new commits for leaked API keys, checks new dependencies for known vulnerabilities and confirms the lockfile is honest. If any of those checks finds something real, it blocks the merge. You can build it in an afternoon with free tools, and most of that afternoon goes into tuning, not setup.

You may have found a live Stripe key in a commit from three weeks ago. Or you may have a Dependabot tab full of alerts that nobody has opened since spring. Either way, this walkthrough is for you.

Why do leaked keys and vulnerable packages get past code review?

Code review happens on diffs, and people reviewing a diff read the logic, not the config. A key pasted into a test fixture looks like noise. A risky transitive dependency hardly shows up at all. It sits somewhere in a 2,000-line lockfile change that nobody scrolls through.

AI coding assistants make both problems worse. To get an example working, they hardcode credentials, and they add packages without a second thought. The code runs, the reviewer approves, and the key goes into history.

What does it cost when one slips through?

Deleting a leaked key in a later commit does not remove it. Git history keeps it, and so does every clone and fork. Bots scan public pushes for credential patterns all the time. The only real fix is rotation: you find every service and environment that uses the key, issue a new one and redeploy without breaking production.

A vulnerable dependency costs you differently. You end up doing an emergency upgrade across major versions, under pressure, on code you didn't write.

The hidden cost is a noisy gate. If the check fails on things that don't matter, people stop reading it. They re-run it, or an admin turns on bypass. Then the one real finding goes straight through.

Do you actually need a custom gate?

Maybe not. A solo side project with no paying users and no production credentials may only need what GitHub already gives you: secret scanning with push protection and Dependabot alerts, both free on public repositories. Turn those on and stop there.

You need the gate when several people merge code, when the app holds customer data or payment keys, or when part of the codebase came from an AI builder and nobody has reviewed it line by line.

The workflow

Save this as .github/workflows/security-gate.yml:

name: security-gate
on:
  pull_request:
    branches: [main]

permissions:
  contents: read

jobs:
  secrets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Scan PR commits for secrets
        uses: trufflesecurity/trufflehog@main # pin a release tag or SHA
        with:
          extra_args: --results=verified,unknown

  dependencies:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/dependency-review-action@v4
        with:
          fail-on-severity: high
          fail-on-scopes: runtime

  lockfile:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - name: Lockfile matches package.json
        run: npm ci --ignore-scripts
      - name: Lockfile only pulls from the npm registry over https
        run: npx --yes lockfile-lint --path package-lock.json --type npm --allowed-hosts npm --validate-https

Here is what each job does and why it is set up this way.

Secrets. TruffleHog scans only the commits between the PR base and head, so it stays fast. fetch-depth: 0 gives it that history. --results=verified,unknown means it fails on keys it confirmed are live, plus keys it couldn't check. It ignores ones it proved are dead.

Dependencies. Dependency review looks only at packages this PR adds or changes. That one choice keeps old debt from blocking unrelated work. fail-on-scopes: runtime ignores dev-only tooling. On private repositories this action needs GitHub's paid code security add-on.

Lockfile. npm ci fails when package.json and package-lock.json disagree, which catches the classic "I edited package.json by hand" PR. --ignore-scripts stops install scripts from running inside your gate. lockfile-lint fails if a resolved URL points to an unknown host or plain http, which is a common way to sneak in a tampered package.

If dependency review isn't available to you, swap that job for npx --yes audit-ci@7 --config audit-ci.jsonc with a config like this:

{
  "high": true,
  "skip-dev": true,
  "allowlist": [
    // Only reachable from an internal admin script. Review by 2026-12-01. Owner: backend lead
    "GHSA-xxxx-xxxx-xxxx"
  ]
}

How do you tune it so the team doesn't learn to ignore it?

Only fail on findings someone would actually fix today. Everything else goes into a report, not a red X.

Start with verified secrets only. Run TruffleHog with --results=verified for the first two weeks, then add unknown. The team's first experience should be a real catch, not ten false alarms.
Gate on high and critical in runtime code. Moderate issues in a test runner are real, but they are not merge blockers. Handle them in a scheduled job.
Run a nightly full audit separately. A schedule: workflow running npm audit --omit=dev across the whole tree catches newly disclosed issues in old packages. It opens an issue instead of blocking someone's unrelated PR.
Every exception needs a reason, an owner and a review date. An allowlist entry with no comment becomes permanent. The allow-ghsas input on dependency review and the audit-ci allowlist both work for this. Read through them once a month.
Keep the gate under three minutes. Slow checks get skipped. The three jobs run in parallel for that reason.
Make the failure tell people what to do. Add a short note to your PR template: if the secrets job fails, rotate the key first, then remove it from the code. Removing it alone fixes nothing.

How do you make sure nobody can skip it?

In your repository settings, add a branch protection rule (or ruleset) on main and mark secrets, dependencies and lockfile as required status checks. Turn on "Do not allow bypassing" for admins too. A gate that the most senior person can quietly skip only trains everyone else to ask that person.

One honest limit: this gate stops new problems. It doesn't find the key that was committed eight months ago. Run a full history scan once (trufflehog git file://. --results=verified) and rotate whatever it finds before you trust the clean green checks.

If your app started life in Lovable, Bolt, Cursor or a similar tool, the exposure is usually bigger than one pipeline. The vibe coding security guide covers what to check beyond CI. Or send your repo or pipeline to Geminate Solutions for a free review, under NDA, with a reply within 24 hours.

On-Prem to Cloud Migration: Running the Systems That Can't Move Yet

Geminate Solutions — Tue, 20 Oct 2026 08:28:53 +0000

If your on-prem to cloud migration plan assumes one clean cutover, expect that plan to change. Most migrations run hybrid for months or years. The real work is deciding how the systems left behind connect to the ones that moved, how people sign in to both, and who answers when something breaks in between.

You probably know the situation. The customer portal and the new APIs already run in AWS or Azure. The ERP, the warehouse database, a licence server tied to a physical dongle and a nightly mainframe batch job are still in the server room. The migration plan has a slide that says "phase 2", and nobody has a date for it.

This piece covers the four decisions that make that period stable or painful: network connectivity, shared identity, latency, and ownership of failures that cross the boundary.

Why do so many systems get left behind?

Some systems stay behind because of contracts, not code. Common examples are a vendor licence tied to specific hardware, a regulator that wants data kept in a particular facility, or a support agreement that ends if you change where the software is hosted.

Others stay because nobody fully understands them. Think of a 15-year-old application with hard-coded IP addresses, a shared database that six other tools read from directly, or a nightly file drop to a partner over SFTP. Moving those safely means untangling them first, and that takes longer than the migration schedule allowed.

A hybrid state does not mean the planning failed. It is the normal shape of a migration. The real mistake is treating it as temporary and building it with temporary decisions.

What does it cost to get the hybrid period wrong?

The cost rarely arrives as one big outage. It shows up as slow, confusing incidents that eat weeks of your team's time.

A cloud service calls an on-prem database over a VPN that was sized for admin traffic. Pages that used to load instantly now take several seconds, and the team spends weeks blaming the new code.
Staff have two logins, one for the old domain and one for the cloud tenant. When someone leaves, only one gets switched off. Months later, that former employee can still reach the ERP.
An order fails somewhere between the cloud checkout and the on-prem inventory system. The cloud team sees a timeout. The infrastructure team sees a healthy server. The customer gets no confirmation because nobody owns the gap.

In each case, nobody made the decision on purpose. You can make it now, before an incident forces it.

When can you handle this without outside help?

You may not need outside help if what's left on-prem is a few internal tools with light traffic and you already use one identity provider for single sign-on. Set up redundant VPN tunnels, name an owner for each flow, add link monitoring and look at it again in six months.

Outside help is worth it when customer-facing traffic crosses the boundary, when user accounts live in two separate directories, or when the setup has been "temporary" for over a year and incidents keep landing in the gap.

How should the old and new environments connect?

Choose the connection based on how much traffic crosses it and how much an outage would hurt. A site-to-site VPN over the internet is quick to set up and fine for admin access, light API traffic and batch jobs. A dedicated link such as AWS Direct Connect, Azure ExpressRoute or Google Cloud Interconnect gives steadier speed and capacity, but the carrier can take weeks to set it up.

Decision rules:

If customer-facing requests cross the boundary on every page load, plan for a dedicated link with a VPN as backup.
If only nightly jobs and admin tools cross it, a pair of redundant VPN tunnels is usually enough.
If you can't tell yet, measure first. Log every cross-boundary call for two weeks, then choose.

Two details get missed often. The first is overlapping IP address ranges between the office network and the cloud network, so plan addresses before you build because renumbering later is miserable. The second is DNS, the system that turns server names into addresses. Cloud services need to find on-prem servers by name, and on-prem servers need to find private cloud services. Set up forwarding in both directions on day one.

Should you run one identity system or two?

Run one. Staff should sign in once and reach both the old and new systems. When someone leaves, a single switch-off should remove their access everywhere.

In practice, that usually means keeping Active Directory on-prem as the master list of users for now, syncing it to Microsoft Entra ID or connecting it to Okta, and putting cloud apps behind single sign-on using SAML or OIDC. Older on-prem apps that only understand LDAP or Kerberos keep pointing at Active Directory. Once most apps are in the cloud, you make the cloud directory the master list.

System-to-system logins need the same care. If a cloud function reads the on-prem database, give it its own named account with only the access it needs. Keep its credentials in a secrets manager, never as a shared admin password copied into a config file.

If the answer to "how many places do I disable a leaver?" is anything other than one, fix identity before you migrate anything else.

How do you handle latency between old and new systems?

Assume every call across the boundary is slower and less reliable than a call inside one data centre. An app that made 200 small database queries per request was fine on a local network. With 20 to 40 milliseconds per round trip, those queries add up to seconds.

Try these fixes in this order:

Keep chatty systems together. If an app and its database talk constantly, migrate them together or leave both on-prem.
Batch and cache. Replace one-row-at-a-time calls with bulk requests, and keep a copy of slow-changing reference data on the cloud side with a clear refresh rule.
Use a queue. Put a queue between the two sides for anything that doesn't need an instant answer, such as order sync, invoice posting or stock updates. If the link drops, messages wait in line instead of failing.

Give every cross-boundary call a deliberate timeout and retry rule. A 60 second default timeout on a request a customer is waiting for is a bug.

Who owns a failure that crosses the boundary?

Name one person before go-live. Hybrid incidents drag on when two teams each prove their side is healthy while the fault sits between them.

What closes the gap:

One owner per flow, not per system. For example, someone owns "checkout to inventory" from end to end, including the alert, the runbook and the fix.
One trace across both sides. Give each cloud request a tracking ID, pass it into the on-prem logs, and send both sets of logs to one tool such as Datadog, Grafana or Elastic. Without that, someone ends up matching timestamps by hand.
Monitoring for the link itself. Track latency, dropped traffic and tunnel status, and give the link its own alerts like any other service.
A runbook for when the link goes down. Write down what slows down, what waits in a queue and what you tell customers.

What order should you do this in?

Map every flow that crosses the boundary, with its traffic volume and the teams that depend on it.
Fix identity so one account and one offboarding step cover both sides.
Choose connectivity from that map, and plan IP ranges and DNS.
Redesign the chattiest flows by moving pairs together, batching, caching or queueing.
Give every cross-boundary flow an owner, tracing and a runbook.
Give each system that stayed behind an exit date and an exit condition, even if the date moves.

Without step 6, a hybrid setup can become permanent by accident.

A next step if you're in the middle of this

Geminate Solutions has shipped 50+ products, including an exam platform handling 10M+ requests per minute in production. Much of that work comes down to making old and new systems run as one. If you'd like a second opinion on your hybrid setup, the cloud and DevOps team offers a free review of your migration plan under NDA, with a reply within 24 hours.