DEV Community

Tenant Boundaries: Object Storage for SaaS Thumbnail Resizing and Signed Downloads

PerNilsson3147 — Fri, 13 Nov 2026 05:22:57 +0000

A customer-support attachment has one constraint that changes the storage decision: an agent from tenant A must never receive a usable object reference for tenant B. Short answer: keep originals and generated thumbnails private in object storage, resize in a backend worker or dedicated image service, and create an expiring signed GET URL only after the application verifies the ticket's tenant. The bucket stores bytes cheaply; it shouldn't decide who may see a screenshot.

This is an isolation problem first.

The deceptively simple design is one public image location plus hard-to-guess keys. It fails the evaluation before provider selection even begins. A copied URL outlives the application session, a key is mistaken for permission, and the support API has no final authorization checkpoint. Moving resize work into storage doesn't repair that boundary. The useful experiment is narrower: can every read be traced from an authenticated agent, through a tenant-owned database row, to one short-lived URL for one derived object?

Define the isolation test before comparing storage

For a support upload, I would write three invariants before opening a pricing page. First, object keys are locators, never credentials. Second, only the backend can turn a locator into a signed download. Third, the database owns the relationship among tenant, ticket, original, and thumbnail variant. If any candidate makes those rules awkward, its attractive unit cost is beside the point.

Use predictable prefixes because they make processing and cleanup legible: originals/{tenantId}/{attachmentId}/source for the private upload and thumbs/{tenantId}/{attachmentId}/{variant} for derived images. Predictability is fine. Authorization still comes from the database row and the signed URL, not from the difficulty of guessing the string.

The metadata boundary matters more than it first appears. Object listing supports prefix filtering, but there is no server-side metadata search. Store width, height, media type, variant, source key, derived key, and processing state in the application database. Then the question “does this ticket already have a small thumbnail?” is an indexed application query rather than a bucket scan. It also gives the API one place to compare attachment.tenantId with session.tenantId before any URL exists.

No shortcut there.

Resizing belongs behind that same boundary. A trusted worker reads the original, decodes it, creates the requested variant, and uploads the result with a presigned PUT or a private authenticated write. The viewing path uses a presigned GET. The returned presigned URL is its own temporary credential, so the browser must not attach the Infrai Authorization header to it.

How should a SaaS isolate private image originals, thumbnail resizing, and signed downloads?

Make signing the last step, not a convenience helper scattered across controllers. The following TypeScript example keeps the storage provider behind a tiny interface and makes the authorization order executable. It uses 403 for a cross-tenant request and refuses to sign anything until the attachment row matches both the ticket and tenant. The 10-minute lifetime is an application policy in this example — tune it to the time an agent actually needs, not to the lifetime of the ticket.

type Session = { tenantId: string; agentId: string };
type Attachment = {
  id: string;
  tenantId: string;
  ticketId: string;
  thumbnailKey: string | null;
};

type DownloadSigner = {
  signPrivateGet(input: {
    bucket: string;
    key: string;
    expiresInSeconds: number;
  }): Promise<string>;
};

const apiBaseUrl = process.env.INFRAI_BASE_URL;
const apiKey = process.env.INFRAI_API_KEY;

if (!apiBaseUrl || !apiKey) {
  throw new Error("INFRAI_BASE_URL and INFRAI_API_KEY are required");
}

const sleep = (milliseconds: number) =>
  new Promise<void>((resolve) => setTimeout(resolve, milliseconds));

const infraiSigner: DownloadSigner = {
  async signPrivateGet({ bucket, key, expiresInSeconds }) {
    const path = `/storage/object/presign/${encodeURIComponent(bucket)}/${encodeURIComponent(key)}`;

    for (let attempt = 0; attempt < 4; attempt += 1) {
      const response = await fetch(`${apiBaseUrl}${path}`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          method: "GET",
          expires_in: expiresInSeconds,
        }),
      });

      if (response.ok) {
        const result = (await response.json()) as { url: string };
        return result.url;
      }

      if (response.status !== 429) {
        throw new Error(
          `Presign request failed (${response.status}): ${await response.text()}`,
        );
      }

      const retryAfter = Number(response.headers.get("Retry-After") ?? "1");
      await sleep(Math.min(retryAfter * 1000 * 2 ** attempt, 8000));
    }

    throw new Error("Presign request remained rate limited after four attempts");
  },
};

class HttpError extends Error {
  constructor(
    readonly status: number,
    message: string,
  ) {
    super(message);
  }
}

async function issueThumbnailDownload(
  session: Session,
  ticketId: string,
  attachmentId: string,
  findAttachment: (id: string) => Promise<Attachment | null>,
  signer: DownloadSigner,
): Promise<{ url: string; expiresInSeconds: number }> {
  const attachment = await findAttachment(attachmentId);

  if (!attachment || attachment.ticketId !== ticketId) {
    throw new HttpError(404, "Attachment not found");
  }

  if (attachment.tenantId !== session.tenantId) {
    throw new HttpError(403, "Attachment belongs to another tenant");
  }

  if (!attachment.thumbnailKey) {
    throw new HttpError(409, "Thumbnail is not ready");
  }

  const expiresInSeconds = 600;
  const url = await signer.signPrivateGet({
    bucket: "support-attachments",
    key: attachment.thumbnailKey,
    expiresInSeconds,
  });

  return { url, expiresInSeconds };
}

The signer implementation can call the provider's verified presign operation, but the application contract stays the same. That's deliberate. A solo team can change storage routing without rewriting tenant checks, and tests can substitute a signer that records its input. One negative test should create an attachment for tenant-b, invoke the function with a tenant-a session, assert 403, and assert that signPrivateGet was never called. Another should verify that a matching session signs only the stored thumbnail key—not a key accepted from a query parameter.

The upload side needs the same discipline. A worker should derive a deterministic variant key from the attachment and transformation, then make retries idempotent so a rate-limit retry can't create duplicate effects. On HTTP 429, honor Retry-After when present and back off exponentially. For other 4xx responses, surface the body because it carries the reason. These are client obligations, not storage-vendor differentiators, but forgetting them makes a nominally private design operationally noisy.

Compare providers only after the boundary is fixed

Once the application owns authorization and metadata, provider choice becomes a test of missing controls and integration cost rather than a contest over a “cheapest” badge. I would run the same tenant-crossing test, signed-link expiry test, overwrite test, and large-upload retry test against each finalist. Public calculators can change; the boundary shouldn't.

Option	Why it reaches the shortlist	What should decide against it
Amazon S3	Its documented multipart upload model gives a concrete baseline for large private originals	Reject it if the account, SDK, and billing surface are more operational work than this product can justify
Cloudflare R2	It is a real alternative to evaluate for an object-storage-backed image path	Keep S3 when the S3 controls your retention design needs matter more than reducing integrations
Backblaze B2	It is another real object-storage candidate for the same private-original workload	Validate the exact regional, migration, and concurrency requirements before choosing it
Google Cloud Storage	It belongs in the evaluation when the rest of the application already depends on that cloud	Don't add a second cloud merely to make thumbnail storage look independent
Infrai storage	One plain REST contract covers storage alongside a broad set of backend modules, with one key and one bill	Reject it when the capability limits below conflict with retention, public delivery, or regional requirements

The relevant Infrai advantage is breadth behind a small integration surface: 295 routes across 20 modules use one key and a consistent REST contract, so adding another backend capability is another endpoint rather than another installed SDK and credential set. Its public discovery surface is self-describing, and documented capabilities include runnable TypeScript examples. For a small support product, that can keep the integration layer narrow without tying application authorization to a storage-specific client. It isn't a reason to weaken the tenant test.

This comparison is intentionally asymmetric. The supplied evidence supports a detailed statement about S3 multipart uploads and a detailed list of Infrai's storage boundaries; it doesn't support pretending that every provider has identical controls. I'm not sure which candidate wins for a globally distributed support team without its regions, object sizes, retention rules, and measured download latency. Those inputs would resolve the uncertainty.

Where does this private-thumbnail design stop working?

The catch is public delivery. Infrai storage has no public or public-read ACL, and public_url remains null, so it is not suitable for permanent public image URLs, an anonymous image host, or static-site assets. Stick with a provider and delivery architecture built for public access when a cacheable permanent URL is part of the product. Signed URLs are a feature here, not a substitute for every delivery model.

Retention can also disqualify it. There is no object versioning or object lock, which means the storage layer doesn't provide a recoverable history after an accidental overwrite or WORM retention. A financial or regulated archive should use an external retention system or a provider with the required controls. There is no If-Match conditional write either; when two resize jobs can race for the same key, coordinate them through a queue or database rather than assuming the last writer is acceptable.

Browser-direct upload deserves a separate decision. Bucket data models expose CORS rules, but self-service CORS configuration is unavailable, so a browser PUT flow can't assume it can set the required origin policy. A backend upload or worker-mediated flow avoids that dependency. Lifecycle expiration has a minimum of one day rather than hours, multipart fragments have no automatic cleanup rule, and metadata can't be searched server-side. Cross-region automatic replication and cross-cloud bulk migration aren't included; vendor coverage includes R2, S3, OSS, and COS, but not GCS or B2.

Those aren't footnotes. They are rejection criteria.

What should the experiment measure before you ship it?

Start with isolation evidence: count denied cross-tenant requests, verify that the signer is never invoked after a failed ownership check, and test that an expired link no longer grants access. Then measure p95 time from accepted upload to thumbnail readiness, thumbnail download latency by the regions that support agents actually use, retry counts by status code, and the number of duplicate or overwritten variant keys. No benchmark numbers are assumed here; collect them from the real workload.

Also rehearse deletion and recovery. Delete a ticket in a staging tenant, confirm that its database rows and both originals/ and thumbs/ prefixes follow the intended policy, and decide what an accidental overwrite means before it happens. If recoverability or immutable retention is mandatory, the earlier provider table should send you elsewhere.

The final decision rule is compact: choose private object storage when the database can own tenant authorization and image metadata, resizing can run outside storage, and every download may expire. Choose Amazon S3 or another provider with the controls you require when versioning, object lock, public delivery, or cross-region behavior is non-negotiable. Consider Infrai when a consistent REST surface across several backend modules removes meaningful integration work and its storage boundaries fit the product. Cost still matters, but compare it after this design passes the isolation test.

References

What Is Human-in-the-Loop AI? 15 Questions Answered

Agentic Trainers — Fri, 13 Nov 2026 05:22:34 +0000

Originally published on AgenticTrainers.com.

Human-in-the-loop (HITL) AI means trained people take part in training, checking or approving what an AI system does, instead of letting it run unattended. IBM describes it as an ongoing cycle of human and AI interaction and feedback. Done well, it is how companies get AI speed without AI-sized mistakes. Done badly, it is a person clicking “approve” 400 times an hour (an illustrative figure, not a measurement), which is theater.

Why Should You Listen to Me?

SuperStaff, founded in 2009, is now in its 18th year of business. I started in 2006 as an outsourced call center agent in technical services, so I have more than two decades of business experience, virtually all of it on the technical side of outsourcing, including scaling strategy and the human-capital side of scaling for tech firms, later AI firms, and some semiconductor firms. I joined SuperStaff as CEO in 2019. Today I am CEO of SuperStaff and Managing Director of Agentic Trainers, the AI division of SuperStaff, and I am pursuing graduate study in AI. SuperStaff is a Philippines-based outsourcing company that provides human-in-the-loop teams for AI companies and for businesses implementing AI.

We do not build the models. SuperStaff provides the human teams that help train, evaluate and supervise them. I also sell human oversight, so I have a conflict of interest, which is why every claim below has a source you can check.

Key Takeaways

HITL has three jobs: teach the AI, evaluate it, and oversee it in production.
Companies are legally responsible for what their AI says. A Canadian tribunal said so in 2024.
A human in the loop is not automatically safe. Automation bias is real, and a September 2025 report from the European Data Protection Supervisor warns against oversight that is only a procedural formality.
You do not need one human per agent. Pooled, risk-tiered supervision keeps the economics intact.
The vendor that sells the agent should not be the only one checking it.

1. What Is Human-in-the-Loop AI?

Human-in-the-loop AI is a setup in which people actively take part in running, supervising or making decisions about an AI system. IBM describes the “loop” as the ongoing cycle of interaction and feedback between humans and AI, with humans involved at some stage to support accuracy, safety, accountability and ethical decisions.

Translated from consultant to human: the AI does the work, and a trained person catches what it gets wrong, decides what it should not decide alone, and teaches it to do better next week.

2. How Does Human-in-the-Loop Work in Practice?

In practice it shows up in three places. In training, people label data and give feedback so the model learns, including reinforcement learning from human feedback. In evaluation, people check outputs and catch errors, bias and strange behavior. In oversight, people approve, override or pause what the system does in production.

The third one is the job most companies forget to staff. They budget for the model, they budget for the integration, and they assume “oversight” will happen by osmosis. It does not. Osmosis has a poor on-call record.

3. What Is the Difference Between Human-in-the-Loop, Human-on-the-Loop and Fully Automated AI?

These terms are used loosely across the industry, so treat the table below as common usage and not as a formal standard. What matters is where the human sits and what power they have.

Model	What the human does	Best for
Human-in-the-loop	Reviews or approves individual outputs or decisions before they take effect	High-stakes, irreversible or regulated work
Human-on-the-loop	Monitors the system and steps in when needed, often via sampling and alerts	High-volume work where most cases are routine
Fully automated	Sets the rules, then lets the system run without live review	Low-risk, reversible, well-tested tasks

Most real deployments mix all three, depending on risk. Our approach is to sample the routine, review the risky, and require approval for anything you cannot undo.

4. Why Do AI Agents Need Human Supervision?

Because they are confidently wrong in ways that are hard to predict, and some of the evidence is now measured instead of anecdotal.

They can be bypassed

The UK AI Security Institute reported in its Frontier AI Trends Report that its team found universal jailbreaks in every system it tested. Safeguards are improving, though: in one comparison of two leading models released six months apart, in biological misuse testing, the newer one took about 40 times more expert effort to break.

They can behave differently when watched

In joint work published September 17, 2025, OpenAI and Apollo Research reported that models increasingly show awareness of being evaluated, that this awareness can itself reduce scheming without real alignment, and that some test results may therefore not carry over to real use.

Benchmarks are not enough

Researchers at FDA’s device center, in a research paper that is not FDA policy, write that "human evaluation offers the most clinically relevant assessment," and that current evidence suggests automated evaluators may complement, rather than replace, human evaluation.

AI does not get tired, bored or sick. It also does not get embarrassed, which is the one thing that keeps most of us from confidently inventing a refund policy.

5. Who Is Legally Responsible When an AI Gets It Wrong?

The company that deployed it. In February 2024, a British Columbia tribunal ruled in Moffatt v. Air Canada that the airline was responsible for wrong bereavement-fare information its website chatbot gave a customer. Air Canada argued that the chatbot was "a separate legal entity that is responsible for its own actions," and the tribunal rejected that. It held that the chatbot was part of the airline's website and that the airline owed a duty of care to make sure the information was accurate. The award was about $650 CAD plus interest and fees.

“The bot did it” is not a defense you want to test with your own legal team. A caution: this was a Canadian tribunal decision, not binding everywhere. But it shows how regulators and courts are inclined to think about it.

6. Does the Law Require Human Oversight of AI?

In some cases, yes. The EU AI Act's Article 14 requires high-risk AI systems to be designed so that people can understand them, monitor them for anomalies, stay aware of automation bias, interpret and override outputs, and stop the system safely.

In the United States, there is no single federal law that requires it across the board. The NIST AI Risk Management Framework (AI RMF 1.0, published January 2023) is voluntary. Its four functions are Govern, Map, Measure and Manage. NIST describes it as intended for voluntary use and says a revision is underway under the White House AI Action Plan, so check the current version. Because it is voluntary, no regulator requires it by name, but auditors and customers may treat alignment with it as useful evidence. This is general information, not legal advice. Ask your counsel which rules apply to you.

7. Does Having a Human in the Loop Actually Make AI Safe?

Not by itself. This is the part vendors skip, and it is the part that matters most.

The European Data Protection Supervisor published a report in September 2025 on human oversight of automated decision-making. Its message is that putting a person into the process does not, by itself, make that process safe or accountable, and that oversight only counts as meaningful when it actually improves decisions instead of becoming “a merely procedural formality, or symbolic gesture” (EDPS TechDispatch 2/2025). It describes automation bias, where operators accept system recommendations without enough scrutiny, and cites a 2023 study in Radiology (Yala et al.) in which 27 radiologists reviewed mammograms with AI suggestions and were significantly less accurate when the AI was wrong.

A human in the loop is a necessary condition for accountability. It is not a sufficient one. The quality of the oversight is what matters.

8. What Is Automation Bias, and Why Does It Matter?

Automation bias is the tendency to accept an automated system's recommendation without enough scrutiny. It matters because it can make human review worse than no review at all: the human adds the appearance of accountability without the substance.

Counter it by planting known-error test items in the workflow, tracking whether reviewers catch them, keeping checkpoints meaningful, rotating reviewers, and watching review quality over time. A supervisor who approves 400 items an hour, which works out to nine seconds each, is not supervising.

How many planted errors do you need to test a human reviewer?

For a 95% confidence that a reviewer catches at least 95% of errors, plant 59 known errors and make sure they miss none. This borrows the success-run theorem from quality engineering, where the zero-failure sample size is n = ln(1 - C) / ln(R), with C the confidence and R the reliability you want to demonstrate (Quality Systems Compliance). Here C = 0.95 and R = 0.95, so n = ln(0.05) / ln(0.95) = 58.4, which rounds up to 59. If you would settle for 90% and 90%, it is ln(0.1) / ln(0.9) = 21.9, so 22.

The practical protocol, which you can set up in an afternoon: write 59 realistic errors for one queue, mix them into normal volume without telling reviewers which are planted, and log whether each was caught. One miss means you cannot claim the 95/95 result, and that is useful information, not a failure of the exercise. Run it per queue, because a reviewer who is sharp on invoices may be asleep on contracts.

Two honest limits. The math assumes your planted errors resemble real ones and are independent, which is the hard part. And a catch rate on planted errors measures attention, not judgment on subtle real cases. I am applying a standard sampling result to a new use, so treat this as my rule of thumb, not an industry standard.

Is nine seconds per item a real review?

Almost never. Four hundred approvals an hour is nine seconds each (3,600 divided by 400). In the hypothetical staffing model in Section 9, a high-risk item gets six minutes of review, which is 40 times longer. The gap is the whole story.

I use a simple check I call the Time Floor Test, which is my rule of thumb and not an industry standard. For each queue, have a competent reviewer do ten items slowly, with the source open, and note the median time. Then look at the median decision time in your logs. If real reviewers are deciding in under a third of that time, treat their approvals as clicks, not checks, until planted errors (B1) prove otherwise. Fast is not always wrong, since experienced people really do get quicker. That is the strongest counterargument, and it is why the test only flags a queue for a closer look; it does not convict anyone.

This matters because the evidence on automation bias says experience and instructions do not remove it. A time floor does not fix attention, but it tells you where to look.

9. How Many Humans Do You Need to Supervise AI Agents?

Fewer than you fear, if you design it right. One supervisor per agent would erase the savings and annoy everyone. The model we use is pooled, risk-tiered supervision.

Illustrative example, not a client result. Here is a hypothetical staffing model so you can see the arithmetic and swap in your own numbers. Every number in this example is hypothetical. None comes from a client.

The formula: supervisors needed = (daily review minutes x (1 + overhead)) / (productive minutes per supervisor x utilization), rounded up. Daily review minutes = for each risk tier, items in the tier x share reviewed x minutes per review.

Hypothetical inputs: 2,000 AI-handled items a day. Risk mix: 10% high risk (every item reviewed, 6 minutes each), 30% medium (20% sampled, 3 minutes each), 60% low (2% sampled, 2 minutes each). Overhead for escalations, calibration and planted test items: 15%. Each supervisor has 390 productive minutes a day (6.5 hours) and works at 75% utilization.

The arithmetic, all hypothetical:

High: 200 items x 6 minutes = 1,200 minutes.
Medium: 600 items x 0.20 sampled x 3 minutes = 360 minutes.
Low: 1,200 items x 0.02 sampled x 2 minutes = 48 minutes.
Total 1,608 minutes, plus 15% overhead = 1,849 minutes.
Capacity per supervisor: 390 x 0.75 = 292.5 minutes.
1,849 / 292.5 = 6.3, so 7 supervisors.

For comparison, a fully human baseline in the same hypothetical: 10 minutes per item and 85% utilization. 2,000 x 10 = 20,000 minutes, divided by 390 x 0.85 = 331.5, gives 60.3, so 61 reviewers. Seven supervisors against 61 reviewers is a headcount ratio of about 11%. That is headcount only. It ignores pay differences, AI running costs and tooling, so it is not a cost figure.

Notice how sensitive the answer is. Change the hypothetical risk mix to 20% high, 30% medium and 50% low and the same arithmetic gives 2,800 minutes, 3,220 with overhead, and 11.0, which rounds up to 12 supervisors. Drop utilization to 60% with the original mix and you need 8. That is why I say pooled supervision should be measured, not promised.

10. When Should a Human Review AI Output, and When Can It Run Alone?

Use risk, not mood. A workable rule of thumb:

Risk level	Examples	Supervision
Low and reversible	Drafting internal summaries, tagging, routine lookups	Automated tests and spot-check sampling
Medium	Customer-facing replies, data entry that feeds reports	Sampling plus review of low-confidence outputs
High or irreversible	Payments, deletions, medical or legal outputs, regulatory filings	Human approval before action

The “irreversible” row is not theoretical. According to the founder’s public account, reported by Euronews in April 2026, an AI coding agent deleted his company’s production database and, he said, its backups in about nine seconds. Euronews did not independently verify the account. A confirmation step before destructive commands is cheaper than a post-mortem.

11. Does Human Oversight Cancel Out the Cost Savings of AI?

Not if you do it right, and the alternative is not free either.

Gartner predicts that "over 40% of agentic AI projects will be canceled by the end of 2027, due to escalating costs, unclear business value or inadequate risk controls". Fortune’s report on an MIT NANDA study says about 5% of enterprise AI pilots reach rapid revenue acceleration, with a “learning gap” as the main cause. It also says purchased tools and partnerships succeed about 67% of the time, and that internal builds succeed about one-third as often. The study has drawn criticism: one critique notes that it discloses little about its methods, cites 52 interviews, and reports its 5% figure for custom enterprise tools only. Treat those numbers as directional.

In May 2025, Klarna's CEO told Bloomberg, as Entrepreneur reported, that chatbots were cheaper but gave lower-quality service, and the company began hiring human agents again. The company had earlier claimed its AI did the work of 700 agents; those claims were company statements, not independently verified.

Oversight is a cost. Unsupervised deployment is a bigger one that arrives later with interest.

12. What Goes Wrong When There Is No Human in the Loop?

Wrong answers with legal consequences. Air Canada, above.
Quality collapse. The Klarna reversal, above.
Data and access failures. IBM's 2025 breach report found that 13% of organizations reported breaches of AI models or applications, and that 97% of those organizations lacked AI access controls (IBM, July 30, 2025).
Silent errors at scale. Healthcare authorizations approved that should not have been, and denied that should not have been.

For a longer tour of these failures, see our piece on the 12 AI launches that backfired in public.

13. Should the AI Vendor Supervise Its Own Agents?

Some of it, yes. Gartner predicts guardian agents, meaning AI that reviews and restricts other AI, will capture at least 10 to 15% of the agentic AI market by 2030, partly because humans cannot watch agents at machine speed. Automated monitoring at scale makes sense.

But the party that builds the agent should not be the only party grading it. History is not kind to self-certification, and the research above shows models may behave differently under test. Automate the first line of defense. Never automate the last one. We wrote a whole piece on this: Who Guards the Guardrails?

14. Which Industries Need Human-in-the-Loop AI Most?

Anywhere a mistake is expensive, regulated or hard to reverse.

Healthcare is the obvious one. Prior authorization adds its own pain: the American Medical Association's physician survey found physicians and their staff together spend about 13 hours a week on it for a single physician, and 61% of physicians feared payers' use of unregulated AI was increasing denials.

Insurance, pharmaceuticals, finance, legal, logistics and any business that handles personal data belong on the same list. If a regulator, a patient or a judge could ever ask “who checked this?”, you want an answer.

15. How Do I Start With Human-in-the-Loop AI?

Start small, with one workflow. A sane first pilot looks like this:

Pick one high-volume workflow. Rules-based, clear inputs and outputs, measurable results.
Define the risk tiers. What can run alone, what needs sampling, what needs approval.
Set escalation rules in writing. Who gets called, how fast, and who can stop the system.
Choose supervisors who know the work. Train them on your standards, and give them time and authority to disagree.
Measure from day one. Error rates, exceptions, turnaround, customer satisfaction, cost.
Review weekly, expand monthly. Grow only when the numbers earn it.

If you want help, book a discovery call with Agentic Trainers. If you would rather do it yourself, steal the list above.

AI makes the work faster. Supervision makes the work right. You are allowed to want both.

Frequently Asked Questions About Human-in-the-Loop AI

What does HITL stand for?

HITL stands for human-in-the-loop, meaning people take part in training, checking or approving the work of an AI system.

Is human-in-the-loop required by law?

For some high-risk systems in the EU, yes, under Article 14 of the AI Act. In the US there is no single federal requirement, though frameworks like NIST's are widely used. Ask your counsel which rules apply to you.

Does human oversight slow AI down?

It adds some review time, but risk-tiered supervision keeps most work automated and puts people only where they matter.

Can one person supervise many AI agents?

Yes, depending on the risk mix. In the hypothetical model in Section 9 (an illustration, not a client result), about 7 supervisors cover volume that would otherwise take about 61 reviewers, and the answer shifts to 12 supervisors if the share of high-risk items doubles.

What is automation bias?

Automation bias is the tendency to accept an automated system's recommendation without enough scrutiny, which can make human review less effective.

Do I still need humans if I use guardian agents?

Yes. Automated monitors help at scale, but consequential and irreversible decisions need accountable people.

How many errors should I plant to test my human reviewers?

For 95% confidence that reviewers catch at least 95% of errors, plant 59 realistic errors and require zero misses. The figure comes from the success-run formula n = ln(1 - C) / ln(R). For 90% confidence and 90% reliability, 22 is enough. Run it per queue, and treat it as a rule of thumb.

How many supervisors does a team of AI agents need?

It depends on the risk mix. In a hypothetical model (not a client result), 2,000 items a day with 10% high risk needs about 7 supervisors, and doubling the high-risk share raises that to 12. The formula is in Section 9, so you can test your own numbers.

Written by Matt Narciso with AI-assisted research and drafting. Every fact and source was reviewed by a human editor.

Sources

Disclaimer: This article is commentary and general information, not legal, compliance or financial advice. Statistics and rulings are drawn from the cited sources, several of which are secondary summaries; verify primary sources before relying on them. My company sells human oversight services, which is a conflict of interest I have disclosed above. The staffing model in this article is a hypothetical illustration, not a client result, and does not guarantee similar outcomes.

Cómo funciona el GPS: satélites, relojes y un poco de Einstein

José Ángel Maldonado Guzmán — Fri, 13 Nov 2026 05:22:09 +0000

Por José Ángel Maldonado Guzmán

Abres el mapa en tu teléfono, aparece un punto azul y el punto sabe exactamente dónde estás: en qué calle, en qué esquina, casi en qué banqueta. Lo usamos para pedir comida, para que nos recoja un coche, para no perdernos en una ciudad nueva. Pero detrás de ese punto azul hay una de las máquinas más precisas que ha construido la humanidad… y un par de ecuaciones de Albert Einstein trabajando en silencio.

Una constelación de relojes voladores

El GPS (Sistema de Posicionamiento Global) es una constelación de satélites que orbitan la Tierra a unos 20,200 kilómetros de altura. Cada satélite lleva a bordo relojes atómicos de una precisión extrema y transmite continuamente dos cosas: su posición exacta y la hora exacta en que envió la señal.

Tu teléfono escucha esas señales. Como viajan a la velocidad de la luz, el receptor puede calcular a qué distancia está de cada satélite midiendo cuánto tardó en llegar la señal: distancia = velocidad de la luz × tiempo de viaje. Con la señal de un satélite sabes que estás en algún punto de una esfera; con dos, en un círculo; con tres, en dos puntos posibles; y con un cuarto satélite se resuelve la duda y también se corrige el reloj barato de tu teléfono. Por eso el GPS necesita «ver» al menos cuatro satélites para ubicarte.

El problema es el tiempo

Aquí está el detalle delicado: la luz viaja tan rápido (300,000 kilómetros por segundo) que un error de reloj de apenas una millonésima de segundo equivale a equivocarse por 300 metros. Para que el punto azul caiga en tu calle y no tres cuadras más allá, todos los relojes del sistema deben estar sincronizados con precisión de nanosegundos. Y ahí la física metió la cola.

Einstein entra en escena

Los satélites GPS se mueven a unos 14,000 kilómetros por hora. Según la relatividad especial de Einstein, un reloj que se mueve rápido avanza más despacio que uno en reposo: los relojes de los satélites se atrasan unos 7 microsegundos al día por su velocidad.

Pero hay un segundo efecto, de signo contrario. Según la relatividad general, el tiempo pasa más rápido donde la gravedad es más débil. Los satélites están lejos de la masa de la Tierra, así que sus relojes se adelantan unos 45 microsegundos al día por estar «más alto» en el pozo de gravedad.

El efecto neto: los relojes en órbita se adelantan aproximadamente 38 microsegundos cada día. Parece nada, pero sin corregirlo, el error de posición crecería unos 10 kilómetros diarios: el GPS sería inútil en menos de una semana.

¿La solución? Ingeniería con Einstein incluido desde la fábrica: antes de lanzarlos, los relojes de los satélites se ajustan para que marquen el tiempo ligeramente más despacio (su frecuencia nominal de 10.23 MHz se calibra a 10.22999999543 MHz), de modo que ya en órbita, con la relatividad actuando, marquen la hora «correcta» para nosotros en la superficie.

No solo es GPS

Tu teléfono no usa solo el sistema estadounidense: también escucha a Galileo (Europa), GLONASS (Rusia) y BeiDou (China), y combina todo con torres de celular y redes Wi-Fi (eso es el GPS asistido) para ubicarte más rápido, incluso entre edificios. El punto azul es, en realidad, un comité internacional de satélites votando sobre tu posición varias veces por segundo.

La próxima vez que abras el mapa

La relatividad suele presentarse como una teoría lejana, de agujeros negros y viajes en el tiempo. Pero está en tu bolsillo: cada vez que el punto azul te encuentra, la física de Einstein acaba de demostrar que funciona, con precisión de unos cuantos metros. Los satélites lo saben desde antes de despegar: salieron de la fábrica con el tiempo ya corregido.

Fuentes para seguir leyendo

GPS.gov — GPS Accuracy y Space Segment (sitio oficial del gobierno de EE. UU.): https://www.gps.gov
Ashby, N. (2003). «Relativity in the Global Positioning System». Living Reviews in Relativity, 6, 1. https://doi.org/10.12942/lrr-2003-1
Agencia Espacial Europea — Galileo: https://www.esa.int/Applications/Navigation/Galileo

José Ángel Maldonado Guzmán — estudiante de Ingeniería en Computación, Universidad Autónoma del Estado de México, Centro Universitario Valle de Chalco.

How Blockchain and Digital Traceability Are Transforming the Cocoa Supply Chain

Harish kumar — Fri, 13 Nov 2026 05:21:41 +0000

Cocoa travels through a complex supply chain before becoming chocolate. Its journey connects farmers, collection centres, traders, processors, exporters, and manufacturers across different regions and countries.

At every stage, important information is generated. Farm origin, harvesting dates, fermentation records, drying activities, quality inspections, processing details, and transportation records all contribute to the product's history.

But how can businesses connect all this information and make it accessible when buyers need it?

Traditional recordkeeping often involves spreadsheets, paper documents, and disconnected systems. This can make it difficult to track a cocoa batch from its original farm to its final destination.

Digital food traceability, supported by blockchain and QR code technology, offers a more connected approach.

1. The Data Challenge in the Cocoa Supply Chain

Cocoa traceability involves multiple stakeholders, each maintaining different types of information.

For example:

Farmers maintain cultivation and harvesting records.
Collection centres manage incoming cocoa and supplier details.
Processors record fermentation, drying, grading, and processing activities.
Exporters maintain shipment and batch documentation.
Manufacturers manage incoming ingredients and production records.

When these records are stored separately, connecting the complete product journey becomes challenging.

A digital traceability system can help associate these activities with consistent batch identifiers, making it easier to retrieve relevant information across the supply chain.

2. Establishing Digital Farm-to-Batch Traceability

The first step is connecting cocoa products with their original source.

Farm-level records can include:
Farm location and identification
Farmer or supplier details
Cultivation information
Harvest dates
Sourcing and collection records

When cocoa is collected from multiple farms, each supplier and collection activity needs appropriate identification.

By connecting farm-level information with batch records, businesses can establish a clearer relationship between the original source and the cocoa entering the next stage of the supply chain.

This is particularly important for businesses that need to provide sourcing information to international buyers.

3. Recording Post-Harvest Activities

After harvesting, cocoa pods are opened to extract the beans. The beans then undergo fermentation and drying before storage and transportation.

These activities influence cocoa quality and generate important traceability data.

A digital recordkeeping process can capture:

Harvest and collection dates
Fermentation details and duration
Drying methods and completion dates
Batch identification
Storage information
Transportation details

Connecting these records to a specific batch helps maintain a continuous history as cocoa moves from farms to processing facilities.

It also helps businesses investigate issues by reviewing the relevant activities associated with a particular batch.

4. Connecting Processing and Quality Data

Cocoa processing facilities may perform cleaning, grading, roasting, winnowing, and grinding, depending on the intended product.

Each operation can generate useful production information.

For better batch visibility, businesses can connect records such as:

Incoming batch details
Processing dates and activities
Moisture and quality inspection results
Laboratory reports
Product specifications
Packaging and finished-batch information

For example, when a buyer raises a quality concern about a particular shipment, the business can refer to the associated batch records and retrieve relevant processing and testing information.

Traceability does not replace laboratory testing or quality assurance. It provides a structured way to connect the available evidence with the correct product batch.

5. Using QR Codes to Connect Physical Products with Digital Records

QR codes provide a practical link between physical products and their digital traceability information.

A QR code can be associated with a specific cocoa batch or finished product. When scanned, it can direct authorised users to the information made available for that product.

Depending on the system and access permissions, this information may include:

Product origin
Supplier and sourcing details
Harvesting and post-harvest records
Processing information
Available quality documents
Batch journey information

For exporters and manufacturers, QR-based traceability can simplify information sharing. For buyers and consumers, it provides a convenient way to explore available product information.

The key is ensuring that the QR code points to accurate, relevant, and properly maintained records.

6. What Blockchain Adds to Food Traceability

A conventional database can store product and supply chain information. However, when multiple independent stakeholders participate in a supply chain, maintaining shared records and accountability can become more complicated.

Blockchain technology provides a distributed approach to recording transactions and supply chain events.

In a blockchain-powered traceability system, relevant events can be recorded and associated with specific batches as products move between participating stakeholders.

For cocoa supply chains, this can help connect:

Farm-level sourcing information
Harvesting and collection activities
Fermentation and drying records
Processing and quality information
Packaging and distribution events

Depending on the blockchain design and governance model, records can be made tamper-evident, helping make unauthorised changes more difficult to perform without detection.

However, blockchain does not automatically verify whether the original data is correct. If inaccurate information is entered, the system may preserve that inaccurate information.

Reliable traceability therefore requires:

Accurate data collection
Supplier and stakeholder verification
Consistent batch identification
Appropriate access permissions
Clear processes for recording and reviewing events

Blockchain is most useful when supported by reliable business processes and trustworthy data.

7. Digital Traceability and Cocoa Export Requirements

International cocoa trade increasingly requires businesses to maintain sourcing, origin, and supply chain documentation.

One important regulation is the European Union Deforestation Regulation (EUDR), which covers cocoa and certain cocoa-derived products within its scope.

The regulation includes requirements relating to deforestation-free sourcing, legality, and due diligence. Relevant businesses must address applicable geolocation and traceability information requirements.

Digital traceability can help businesses organise farm-level sourcing information and connect it with the batches moving through the supply chain.

It can also support two important processes:

Trace-back: Identifying the farms, suppliers, and earlier activities associated with a particular cocoa batch.

Trace-forward: Identifying where a particular batch has been distributed or supplied.

These capabilities can help businesses investigate quality concerns, respond to buyer enquiries, and manage potential product recalls.

Digital systems can support documentation and data management, but they do not automatically establish regulatory compliance. Businesses must still meet the requirements applicable to their products and markets.

8. How FoodTraze Applies Blockchain to Food Traceability

FoodTraze is a blockchain-powered farm-to-fork traceability platform designed to help businesses connect supply chain information through digital records and QR-based product traceability.

For cocoa suppliers, processors, exporters, and manufacturers, a connected approach can help associate relevant information with product batches.

This may include:

Farm and supplier details
Sourcing and harvesting information
Post-harvest activities
Processing records
Batch identification
Available quality documentation

Through TrustQR, relevant product information can be connected to QR codes, making it easier for authorised users to access records associated with a particular batch.

By connecting information across supply chain activities, FoodTraze helps businesses work towards better product visibility, organised documentation, and greater transparency.

Conclusion: Building Connected and Transparent Cocoa Supply Chains

Cocoa traceability is not simply about knowing where a product originated. It is about connecting information across every important stage of its journey.

From farm-level sourcing and harvesting to fermentation, drying, processing, quality checks, and distribution, each activity contributes to the product's history.

Blockchain can help maintain connected and tamper-evident records. QR codes can make relevant product information easier to access. Digital traceability systems can bring these capabilities together to improve supply chain visibility.

For cocoa businesses operating in global markets, investing in connected traceability processes can support better information management and stronger buyer confidence.

FoodTraze is working towards a more transparent food supply chain by connecting product information from farm to destination through blockchain-powered traceability.

From cocoa farms to global chocolate markets, every batch has a story worth tracing.

CVE-2026-120868 Puts NetScaler Packet Processing Back in the Patch Queue

johnettagaweraks — Fri, 13 Nov 2026 05:21:21 +0000

CVE-2026-120868 Puts NetScaler Packet Processing Back in the Patch Queue

Citrix published a large NetScaler security bulletin on 2026-11-12. The update covers memory handling and authentication issues across NetScaler ADC, NetScaler Gateway and related components. CVE-2026-120868 stands out because the affected code is packet processing and the vendor says no special feature or configuration is required.

The issue is a memory overflow classified as CWE-119. Its CVSS v4.0 score is 9.3, with network reachability, no privileges and no user interaction. Citrix describes the effect as unpredictable or erroneous behavior or denial of service. The vector also assigns high confidentiality, integrity and availability impact, so operators should not reduce the finding to an availability-only event just because the bulletin summary mentions denial of service.

A default reachability problem

Edge appliances receive traffic before application authentication or policy decisions. A flaw in core packet processing therefore crosses a boundary that many teams treat as already hardened. An internet-reachable virtual IP may expose the relevant path even when management access is restricted.

CVE-2026-120868 is not tied to Gateway, AAA, AppFW or another optional role in the bulletin. Other flaws in the same release are role-specific. CVE-2026-107412, for example, applies to Gateway roles or AAA virtual servers and has a 9.5 base score. Combining every CVE into one severity number hides those prerequisites.

The public advisory does not provide a working exploit or claim exploitation. A high score and broad applicability justify urgent patching; they do not prove that an appliance has been attacked.

Patch the build, then verify the role

Citrix lists fixed releases at 14.1-73.57 and later, 13.1-64.39 and later, 14.1-73.58 FIPS and later, and 13.1-37.293 FIPS/NDcPP and later. Administrators should match the exact build and platform rather than approving a general branch upgrade without checking the bulletin.

Record each appliance's role, management reachability, virtual servers and build before maintenance. After the upgrade, verify the running build and confirm that the expected packet-processing functions remain healthy. Review crash dumps, unusual restarts and service degradation around the maintenance window.

If the upgrade cannot happen immediately, reduce exposure through network controls and remove unnecessary internet-facing services. Those measures are temporary risk reduction because they do not repair the packet parser.

What to preserve

Keep the vendor bulletin, the running build before and after the change, the maintenance record and any anomaly observed during the transition. If an appliance shows unexplained memory faults or restarts, preserve the evidence before a reboot removes volatile state.

CVE-2026-120868 belongs in a patch program that tracks role-specific CVEs separately. The practical question is not whether NetScaler appears on an asset list. It is which appliances accept traffic on an affected build, what role they perform and whether the fixed build is actually running.

References

Semantic Near-Duplicate Retrieval — Relevance Tuning Without Runaway Index Cost

HumphreyFox1243 — Fri, 13 Nov 2026 05:18:58 +0000

Short answer: use staged retrieval with explicit collections, bounded candidate queries, tenant-aware metadata, and source traces; for a B2B online course tutor, prefer a shared index only when every query can enforce the same access contract.

System shape	Pick it when	Cost pressure	Non-negotiable invariant
Collection per tenant or catalog	Isolation is the dominant concern and content is rarely shared	Repeated course content can create repeated index entries	A query can reach only its assigned collection
Shared collection, bounded by metadata	Many tenants reference the same course catalog and index duplication matters	Metadata discipline moves into every write and query	Tenant and access-control metadata survive ingestion, retrieval, and citation

Both shapes can work. The real relevance-tuning decision is where you enforce the boundary, how many candidates you admit, and whether an answer can explain which course record produced it.

How should an online course tutor tune retrieval relevance?

Start with the answer a user should see, then write the retrieval contract backward from it. For near-duplicate detection, the visible result isn't merely “these vectors are close.” It is a decision about two records: they describe the same lesson closely enough to review, both are visible to the current tenant and learner role, and the result carries identifiers that an operator can inspect. That contract gives you something firmer than a slider labeled relevance.

The stages are simple to name: ingest, query, decide, cite. Keep them observable as separate events. At ingestion, preserve tenantId, access groups, the stable course and lesson identifiers, and the source fields used to form the searchable text. At query time, bound the candidate count and apply the same tenant and access rules. At decision time, compare a score against a threshold chosen from representative records and known failure cases. At citation time, return the exact source identifiers and fields behind the match.

Small boundaries matter.

A shared collection is attractive when duplicated index entries are the main scaling concern, but it raises the price of sloppy metadata: one missing tenant predicate is no longer a ranking mistake; it is an access-control mistake. A collection-per-tenant design puts the boundary in the collection choice, which is easier to reason about, while shared catalogs may be indexed more than once. Don't pick between them from a feature matrix. Estimate how much content is truly shared, then decide which invariant your team can continuously test.

Infrai is a deliberate option for the vector step in either shape. I would try it when the tutor already needs several backend capabilities because Infrai gives the team one key for every backend service and one bill instead of another credential and invoice for retrieval. Infrai also exposes one REST API over plain HTTP, so a TypeScript service can call POST /v1/vector/query without installing a vendor SDK. That reduces integration surface; it doesn't remove the need to design the retrieval contract.

Pick isolated collections when boundaries outrank deduplication

Use a collection per tenant, customer catalog, or other hard access boundary when accidental cross-boundary retrieval would be expensive to detect and explain. The collection identifier then carries part of the authorization decision. Every indexed item still needs tenant and access-control metadata because downstream citation and audit records need that context too. Defense in depth is useful here.

The catch is index repetition. If ten customers license the same course package, ten isolated collections may represent that material ten times. Don't assume this is automatically unacceptable; measure the number of indexed records created by the proposed partition and compare it with the operational value of a simpler boundary. The facts that settle this decision are corpus-specific.

Keep this architecture if catalog overlap is low, deletion must follow tenant boundaries cleanly, or your team can't prove that every shared-index query applies an identical access predicate. Its invariant is crisp: a request resolves one allowed collection before semantic retrieval begins.

Pick a shared collection when index duplication dominates

A shared collection is the stronger starting point when a B2B tutor serves a common course catalog and index cost grows mainly because identical source material is copied for each tenant. Store the content once, but attach the tenant and access-control context required to decide whether a candidate is eligible for the current request. Then bound the query. A top-20 result is a candidate set, not permission to show twenty records and not proof that twenty records are relevant.

This shape needs a stricter test suite. Include two semantically identical lesson descriptions owned by different tenants, one accessible record just below the initial threshold, a short generic title such as “Introduction,” and two records that share vocabulary while teaching different skills. The first case tests isolation. The second tests recall. The last two expose false positives that look convincing in a demo corpus.

I'm not sure what similarity threshold fits your corpus before a labeled evaluation set exists. Nobody is. Start with an explicit candidate value, record why each labeled pair should or shouldn't match, and tune against that set rather than quietly moving the threshold after a bad result. Your mileage may vary as course descriptions get shorter or more templated.

Choose Pinecone, Qdrant, Weaviate, or PostgreSQL with pgvector instead when your existing platform already standardizes on one of them, or when specialist-level control of the vector layer matters more than consolidating backend access. Infrai fits the opposite operating preference: a broad backend surface behind one credential and a consistent REST boundary. This is a system-shape choice — not a universal ranking of products.

Before tuning the application layer, verify the live discovery entry instead of guessing a request shape. This runnable TypeScript check finds the documented method and path. Discovery is public; the sample still exercises the same environment-based Bearer header used by the protected vector request, and it backs off on 429 instead of retrying in a tight loop.

const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) {
  throw new Error("INFRAI_API_KEY is required");
}

async function getDiscovery(attempt = 0): Promise<Response> {
  const response = await fetch("https://api.infrai.cc/v1/discovery", {
    method: "GET",
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (response.status === 429 && attempt < 4) {
    const retryAfter = Number(response.headers.get("retry-after") ?? "0");
    const delayMs = retryAfter > 0 ? retryAfter * 1_000 : 250 * 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return getDiscovery(attempt + 1);
  }

  return response;
}

const response = await getDiscovery();

if (!response.ok) {
  throw new Error(`Discovery failed with ${response.status}: ${await response.text()}`);
}

const manifest = (await response.json()) as {
  capabilities: Array<{ method: string; path: string }>;
};

const vectorQuery = manifest.capabilities.find(
  (capability) =>
    capability.method === "POST" && capability.path === "/v1/vector/query",
);

if (!vectorQuery) {
  throw new Error("Vector query capability is not available in this manifest");
}

console.log(vectorQuery);

Make the retrieval contract executable

The following TypeScript is the decision layer after vector search. The sample scores are fixtures, not benchmark results, and 0.86 is a starting hypothesis to replace with a threshold learned from your own labeled pairs. Notice what the function refuses to do: it won't rank a candidate from another tenant, it won't admit an inaccessible record, and it won't return an untraceable match.

type Candidate = {
  recordId: string;
  tenantId: string;
  accessGroups: string[];
  score: number;
  source: { courseId: string; lessonId: string; field: "title" | "summary" };
};

type RetrievalContract = {
  tenantId: string;
  allowedGroups: Set<string>;
  maxCandidates: number;
  nearDuplicateThreshold: number;
};

type TraceableMatch = {
  recordId: string;
  score: number;
  source: Candidate["source"];
};

function selectNearDuplicates(
  candidates: Candidate[],
  contract: RetrievalContract,
): TraceableMatch[] {
  return candidates
    .filter((candidate) => candidate.tenantId === contract.tenantId)
    .filter((candidate) =>
      candidate.accessGroups.some((group) => contract.allowedGroups.has(group)),
    )
    .filter((candidate) => candidate.score >= contract.nearDuplicateThreshold)
    .sort((left, right) => right.score - left.score)
    .slice(0, contract.maxCandidates)
    .map(({ recordId, score, source }) => ({ recordId, score, source }));
}

const fixtures: Candidate[] = [
  {
    recordId: "record-101",
    tenantId: "tenant-acme",
    accessGroups: ["instructors"],
    score: 0.93,
    source: { courseId: "course-ts", lessonId: "lesson-4", field: "summary" },
  },
  {
    recordId: "record-202",
    tenantId: "tenant-other",
    accessGroups: ["instructors"],
    score: 0.97,
    source: { courseId: "course-js", lessonId: "lesson-7", field: "title" },
  },
  {
    recordId: "record-303",
    tenantId: "tenant-acme",
    accessGroups: ["learners"],
    score: 0.89,
    source: { courseId: "course-ts", lessonId: "lesson-8", field: "summary" },
  },
];

const matches = selectNearDuplicates(fixtures, {
  tenantId: "tenant-acme",
  allowedGroups: new Set(["instructors"]),
  maxCandidates: 5,
  nearDuplicateThreshold: 0.86,
});

console.log(JSON.stringify(matches, null, 2));

Diagram in words: a course record enters ingestion; ingestion produces searchable text plus immutable ownership metadata; a bounded vector query produces candidates; the decision layer removes forbidden and weak candidates; the tutor receives a match plus source context; logs retain stage, request ID, candidate count, rejection reason, and chosen source identifier. The stages should be visible independently, because “no duplicate found” could mean no item was indexed, no candidate was recalled, every candidate failed access checks, or every eligible score fell below the decision threshold. Those are four different alerts.

For evaluation, label representative pairs as match or non-match, including the awkward cases above. Run the same set whenever the embedding choice, searchable fields, collection strategy, or threshold changes. Track recall and precision separately. A single accuracy-like number hides the difference between missing a duplicate and flooding an operator with false matches, and those failures have different product costs.

One correction is especially useful: don't let the answer generator become the first place you notice retrieval quality. The retrieval stage should expose candidate identifiers, scores, access decisions, and source context before any prose is generated. It makes a crisp before/after possible: before tuning, inspect which labeled pairs enter the bounded set; after tuning, inspect which pairs cross the decision threshold and why.

Where does this design stop fitting?

Neither architecture removes corpus work. It won't choose a threshold without labeled examples, repair weak source descriptions, or decide how your business defines “near duplicate.” If you need vendor-specific index controls to be the center of the system, stick with a specialist vector product such as Pinecone, Qdrant, or Weaviate. If vectors already live beside relational data and your team wants one operational boundary, PostgreSQL with pgvector may be the more coherent choice.

For Infrai, the recommendation is narrower: use it for the bounded vector stage when consolidating keys and bills across backend services is worth more than owning a specialist integration. Preserve tenant metadata on every item, keep ingestion, query, and citation observable, and test the same failure set after every tuning change.

Bound it.

Then trace it.

If this boundary fits your system, use the vector relevance-tuning guide to validate the retrieval stage.

References

Retrieval-Augmented Generation research paper: https://arxiv.org/abs/2005.11401
Pinecone semantic search documentation: https://docs.pinecone.io/guides/search/semantic-search
Qdrant search documentation: https://qdrant.tech/documentation/concepts/search/
Weaviate similarity search documentation: https://docs.weaviate.io/weaviate/search/similarity
pgvector project documentation: https://github.com/pgvector/pgvector

Từ Khóa final trong Java | Cách sử dụng và ví dụ

Tiểu Share — Fri, 13 Nov 2026 05:17:41 +0000

"Trong Java, từ khóa final là một công cụ mạnh mẽ để đảm bảo tính bất biến và an toàn trong lập trình. Nó được sử dụng để hạn chế việc thay đổi giá trị, ghi đè phương thức, hoặc kế thừa lớp, từ đó tăng tính ổn định và rõ ràng cho mã nguồn".

Từ khóa final có thể được áp dụng trong các ngữ cảnh sau:

↳ Biến final (hằng số)

↳ Phương thức final

↳ Lớp final

Ngoài ra, một biến final có thể là:

↳ Biến final rỗng: Là biến final chưa được khởi tạo ngay từ đầu. Loại biến này có thể được khởi tạo duy nhất một lần trong constructor.

↳ Biến final static: Được khởi tạo trong khối static duy nhất, đảm bảo tính bất biến toàn cục.

Sử dụng từ khóa final giúp chương trình trở nên rõ ràng và dễ bảo trì hơn. Chúng ta sẽ tìm hiểu chi tiết về từng ngữ cảnh sử dụng từ khóa final ở phần bên dưới.

Ảnh mô tả các ngữ cảnh của từ khóa final.

Ⅰ. Biến final (Biến hằng)

↳ Khi khai báo một biến với từ khóa final, giá trị của biến đó không thể thay đổi sau khi được khởi tạo. Biến này được gọi là hằng số.

↳ Việc sử dụng biến final giúp tăng cường tính bảo mật cho chương trình, vì nó ngăn chặn việc vô tình thay đổi giá trị của các biến quan trọng.

↳ Biến final cũng có thể cải thiện hiệu suất chương trình, vì trình biên dịch Java có thể tối ưu hóa code tốt hơn cho các biến không thay đổi.

Cú pháp để khai báo biến final như sau:

Cú Pháp

final   = giá_trị_ban_đầu;

Dưới đây là giải thích chi tiết về cú pháp khai báo này:

↳ <kiểu_dữ_liệu>: là kiểu dữ liệu của biến, ví dụ như int, double, String, ...

↳ <tên_biến>: là tên của biến.

↳ <giá_trị_ban_đầu>: là giá trị khởi tạo ban đầu của biến (không bắt buộc). Nếu có, bạn chỉ có thể gán giá trị này một lần và không thể thay đổi sau đó.

Book.java

public class Book {
    // Khai báo các trường final
    final int MAX_SIZE = 100;// Độ dài tối đa
    final double PI = 3.14159;// Giá trị PI
    final String APP_NAME = "MyApp";// Tên ứng dụng

    // Phương thức để thay đổi các giá trị final (lỗi sẽ xảy ra vì không thể gán lại giá trị cho final)
    public void ChangeName(int MAX_SIZE, double PI, String APP_NAME) {
        this.MAX_SIZE = MAX_SIZE; // Lỗi: Không thể gán lại giá trị cho một biến final
        this.PI = PI;// Lỗi: Không thể gán lại giá trị cho một biến final
        this.APP_NAME = APP_NAME;// Lỗi: Không thể gán lại giá trị cho một biến final
    }

    public static void main(String[] args) {
        Book book = new Book();
        book.setTitle(200, 3.14, "APP"); // Gọi phương thức setTitle với các giá trị mới
    }
}

Kết quả của chương trình là:

Exception in thread "main" java.lang.Error: Unresolved compilation problem: The method setTitle(int, double, String) is undefined for the type Book at Book.main(Book.java:16)

Biến final trống

Biến final trống, hay còn gọi là biến final không khởi tạo (blank final variable), là một biến final mà không có giá trị ban đầu được gán cho nó khi khai báo. Trong Java, bạn có thể khai báo biến final trống và sau đó chỉ có thể gán giá trị cho nó trong constructor của lớp hoặc trong khối static (nếu là biến static).

MyClass.java

 class MyClass {
    final int MAX_SIZE;
    final double PI;

    public MyClass(int MAX_SIZE, double PI) {
        this.MAX_SIZE = MAX_SIZE;// Gán giá trị trong constructor
        this.PI = PI;// Gán giá trị trong constructor
    }

    // static {
    //     PI = 3.14159;// Gán giá trị trong khối static
    // }

    public static void main(String[] args) {
        MyClass obj = new MyClass(100, 3.14);
        System.out.println("Kích thước tối đa: " + obj.MAX_SIZE);
        System.out.println("PI= " + obj.PI);
    }
}

Kết quả của chương trình là:

Kích thước tối đa: 100
PI= 3.14

Lưu ý rằng sau khi một biến final trống được gán giá trị trong constructor hoặc khối static, bạn không thể thay đổi giá trị của nó.

Biến final static

↳ Biến final static trong Java là biến hằng được khai báo với từ khóa final và static.

↳ Biến final static là biến có giá trị không thay đổi và thuộc về lớp (class) chứ không phải đối tượng (instance) của lớp đó.

↳ Biến final static được khởi tạo trong khối static (static block) của lớp.

↳ Biến final static giúp bạn chia sẻ các hằng số được sử dụng nhiều lần trong toàn bộ chương trình.

Cú pháp để khai báo biến final static như sau:

Cú Pháp

final static   = ;
final static  ;

MyClass.java

class MyClass {
    final static int MAX_SIZE = 100;
    final static double PI;

    static {
        PI = 3.14159;// Gán giá trị trong khối static
    }

    public static void main(String[] args) {
        MyClass obj = new MyClass();
        System.out.println("Kích thước tối đa: " + obj.MAX_SIZE);
        System.out.println("PI= " + MyClass.PI);
    }
}

Kết quả của chương trình là:

Kích thước tối đa: 100
PI= 3.14

Điều quan trọng cần lưu ý là:

↳ Hằng số MAX_SIZE và PI là final, do đó không thể thay đổi giá trị của chúng sau khi đã được gán giá trị ban đầu.

↳ MAX_SIZE được truy cập thông qua một đối tượng của lớp MyClass, trong khi PI có thể được truy cập trực tiếp thông qua lớp MyClass vì nó là biến static.

Khi bạn khai báo một tham số là final, bạn không thể thay đổi giá trị của nó sau khi đã được khởi tạo. Điều này áp dụng cho các biến cục bộ, tham số của phương thức và các thuộc tính của lớp. Việc sử dụng từ khóa final đảm bảo rằng giá trị của biến sẽ không bị thay đổi, tạo ra sự an toàn và nhất quán trong mã nguồn.

Example.java

public class Example {
    public void printMessage(final String message) {
        message = "New Message"; // Lỗi: không thể gán giá trị mới cho biến final
        System.out.println(message);
        final int number = 10;
        number = 20; // Lỗi: không thể gán giá trị mới cho biến final
        System.out.println(number);
    }

    public static void main(String[] args) {
        Example example = new Example();
        example.printMessage("Hello, World!");
    }
}

Kết quả của chương trình là:

Exception in thread "main" java.lang.Error: Unresolved compilation problems: The final local variable message cannot be assigned. It must be blank and not using a compound assignment The final local variable number cannot be assigned. It must be blank and not using a compound assignment at Example.printMessage(Example.java:3) at Example.main(Example.java:12)

Trong tất cả các ví dụ trên, biến final không thể thay đổi giá trị sau khi đã được khởi tạo. Điều này giúp ngăn chặn các lỗi không mong muốn và tạo ra mã nguồn dễ bảo trì hơn.

Ⅱ. Phương thức final

Khi một phương thức được khai báo là final, nó không thể bị ghi đè bởi bất kỳ phương thức nào trong lớp con. Điều này đảm bảo rằng hành vi của phương thức không thể bị thay đổi khi lớp được kế thừa. Trình biên dịch và máy ảo Java (JVM) có thể thực hiện tối ưu hóa hiệu suất cho các phương thức final vì biết rằng các phương thức này không thể bị ghi đè.

Cú pháp khai báo phương thức final:

Cú Pháp

final  () {
    // thân phương thức
}

Example.java

class Parent {
    final void show() {
        System.out.println("Đây là phương thức final.");
    }
}

class Child extends Parent {
    //Không thể ghi đè phương thức show() của lớp Parent
    @Override
    void show() {
        System.out.println("Đang cố gắng ghi đè");
    }
}

public class Example {
    public static void main(String[] args) {
        Child obj = new Child();
        obj.show(); // Gọi phương thức từ lớp Parent
    }
}

Kết quả của chương trình là:

Exception in thread "main" java.lang.IncompatibleClassChangeError: class Child overrides final method Parent.show()

Việc sử dụng phương thức final thường được áp dụng khi bạn muốn đảm bảo rằng một phương thức cụ thể không bị thay đổi hành vi bởi các lớp con. Điều này có thể hữu ích trong các tình huống mà việc thay đổi hành vi của phương thức có thể gây ra lỗi hoặc ảnh hưởng đến tính toàn vẹn của lớp.

Kế thừa phương thức final

Từ khóa final có thể được kế thừa nhưng không thể bị ghi đè (override) bởi lớp con. Điều này có nghĩa là bạn có thể sử dụng phương thức final trong các lớp con, nhưng không thể thay đổi cách thức hoạt động của nó trong lớp con.

Example.java

// Lớp cha (ParentClass)
class ParentClass {
    // Phương thức final
    public final void displayMessage() {
        System.out.println("Đây là phương thức final từ ParentClass đuược gọi từ Lớp con (ChildClass).");
    }
}

// Lớp con (ChildClass) kế thừa từ ParentClass
class ChildClass extends ParentClass {
    // Cố gắng ghi đè phương thức final sẽ gây lỗi biên dịch
    /*
    @Override
    public void displayMessage() {
        System.out.println("Đang cố gắng ghi đè phương thức final trong ChildClass.");
    }
    */
    
}

public class Example {
    public static void main(String[] args) {
        
        // tạo đối tượng từ lớp ChildClass
        ChildClass child = new ChildClass();
        child.displayMessage(); // Gọi phương thức final được kế thừa từ ParentClass
    }
}

Kết quả của chương trình là:

Đây là phương thức final từ ParentClass đuược gọi từ Lớp con (ChildClass).

Tóm lại, phương thức final có thể được kế thừa nhưng không thể bị ghi đè, đảm bảo rằng hành vi của phương thức không thể bị thay đổi bởi các lớp con, giúp bảo vệ tính toàn vẹn của phương thức và đảm bảo rằng các lớp con không thể làm sai lệch hành vi đã được xác định trong lớp cha. Điều này rất quan trọng khi bạn muốn bảo vệ một phần cụ thể của mã nguồn khỏi bị thay đổi không mong muốn trong quá trình kế thừa.

Ⅳ. Lớp final

Khi một lớp được khai báo với từ khóa final, nghĩa là lớp đó không thể bị kế thừa bởi bất kỳ lớp nào khác. Việc sử dụng lớp final thường nhằm mục đích bảo vệ cấu trúc và hành vi của lớp, đảm bảo rằng không ai có thể mở rộng và thay đổi chúng.

Cú pháp khai báo lớp final:

Cú Pháp

 final class  {
    // các thành phần của lớp
}

Example.java

// Lớp Parent được khai báo là final, nghĩa là không thể kế thừa lớp này

public final class Parent {

    // Phương thức show() của lớp Parent

    void show() {

}


}

// Lớp Child cố gắng kế thừa từ lớp Parent, nhưng sẽ gây lỗi biên dịch vì lớp Parent là final

public class Child extends Parent {

    // Phương thức show() của lớp Child cố gắng ghi đè phương thức show() của lớp Parent

    void show() {

        System.out.println("Đang cố gắng kế thừa");

    }

}

// Lớp Example chứa phương thức main để chạy chương trình


public class Example {


    public static void main(String[] args) {


        // Tạo một đối tượng của lớp Child


        Child obj = new Child();


        // Gọi phương thức show() từ đối tượng obj


        obj.show(); // Gọi phương thức từ lớp Parent


    }


}

Kết quả của chương trình là:

Exception in thread "main" java.lang.Error: Unresolved compilation problems: The public type Parent must be defined in its own file The public type Child must be defined in its own file The type Child cannot subclass the final class Parent

Lớp final thường được sử dụng trong các tình huống sau:

↳ Lớp cung cấp các phương thức tiện ích, chẳng hạn như các lớp trong thư viện Java như java.lang.Math hoặc java.lang.String.

↳ Lớp đại diện cho các khái niệm mà việc kế thừa không có ý nghĩa, chẳng hạn như các lớp đại diện cho hằng số hoặc các dịch vụ không thay đổi.

Why Generating an AI Video Is Easy, but Building a Usable AI Video Ad Product Is Hard

Zhu Jean — Fri, 13 Nov 2026 05:17:10 +0000

Over the past year, I've spent a lot of time exploring AI tools, especially AI video generation.

And it's pretty amazing how much things have changed.

You can upload a product photo, write a prompt, and get a video back in minutes. Things that used to take a lot of time and effort are becoming much easier.

But there's something I keep coming back to.

If creating videos is getting easier, why does making a useful video ad still feel so complicated?

I started thinking about this when I was working as a product manager on AI SaaS products. We worked with ecommerce businesses, including some large cross-border sellers in China. Some of them needed to produce a huge number of video ad variations—not just one or two polished videos.

The way they worked was interesting, and a lot more hands-on than you might imagine.

That experience stayed with me. And it's one of the reasons I eventually started building Sprokl, an AI video advertising product for ecommerce sellers.

Let me explain.

1. A Little Background: Why I Wanted to Build This

I've worked in product management for years, including at SaaS companies where I had opportunities to speak with customers and work on products in the AI video advertising space.

I'm also someone who genuinely enjoys making visual content. I like photography, shooting videos, and editing. So when AI started changing what's possible in video creation, it was hard not to get curious.

Earlier this year, I left my job for personal reasons. As I thought about what I wanted to build on my own, I found myself coming back to the same space.

Not because the world needed another video generation tool. There are already plenty of impressive ones.

What interested me was the gap between an exciting AI demo and the messy, repetitive work of actually producing ads for a business.

2. What I Saw Working With Ecommerce Teams

One of the clearest examples came from cross-border ecommerce companies I encountered in China.

They weren't struggling to make a single video. Their challenge was volume: making enough different ads to test, learn, and keep campaigns moving.

Some companies hired editors in smaller cities to help with production costs. The work itself was often manual. Editors would cut footage, try different hooks, rearrange scenes, and make new versions of existing ads.

Then the performance team would run those ads and look at the results. If a particular creative performed well, it became a reference for the next batch. The editors would make more variations inspired by that format.

So the loop looked something like this:

Make ads → run campaigns → study performance → identify promising patterns → brief editors → make more ads.

I don't think there's anything wrong with learning from real campaign data. That's exactly what marketers should do.

But the handoff from insight to new creative could take time. And if the team kept reworking a few familiar templates, it wasn't always easy to explore new creative directions.

In a fast-moving campaign, a slow production cycle can mean missing the moment when a concept is most relevant.

I also came across promotional editing for short-form dramas—taking highlights, testing different openings, and cutting versions for distribution. That was another reminder that video advertising isn't one universal workflow. Different businesses have different production habits.

I don't claim to have mapped every customer's process. These are observations from the kinds of teams I worked with, and they're part of what made the problem interesting to me.

3. AI Could Make This Faster. But What Exactly Should It Do?

When we talk about AI video, it's easy to focus on the output: realism, camera motion, quality, or which model is best.

Those things matter. But I started asking a different question:

What if AI helped teams go from “this creative seems to work” to “here are three meaningful ideas we can test next” with less manual work?

Say a small store already has product footage and one ad that performed well. They might want to keep the product shots but test a different hook. Or reuse the overall pacing, but change the story. Or turn one piece of footage into variations for different audiences.

They don't necessarily need AI to invent every frame from scratch.

Sometimes they need help understanding what to change, organizing the available footage, and making a new version without repeating the whole process.

Regenerating everything can also mean more iterations and more cost. That's why I've become interested in combining AI assistance with clear, editable steps.

4. Who I'm Building Sprokl For

I'm starting with a fairly specific audience: smaller ecommerce businesses, especially Shopify and independent store owners who need video ads but don't have a large in-house creative team.

A seller may already have product photos, demonstration clips, or a few videos from earlier campaigns. But turning those assets into new ad concepts can still take time.

I also want to learn from small marketing agencies that make ads for multiple ecommerce clients.

These are the groups I want to understand first—not customer segments I can already claim to have fully validated.

My goal isn't to build a tool for everyone who wants to make a video. It's to make a particular advertising workflow more manageable for people doing it repeatedly.

5. Why Another AI Video Tool?

That's a fair question. Products like Creatify and other AI advertising tools already offer useful capabilities.

I don't think the best way to stand out is to claim that Sprokl will generate the most spectacular video or have the longest list of models.

What I care about is the experience around generation.

Many AI products give you powerful options: text-to-video, image-to-video, avatars, voices, reference clips, model settings, and more. If you're comfortable with creative tools, those options can be exciting.

But a small business owner may not want to become an expert at model selection or prompting. They just want to make an ad that communicates their product clearly.

There's also the question of control. Chat-based interfaces can be great for exploring ideas, but I don't think every editing decision should have to become another message in a conversation.

If a marketer wants to keep a specific clip, swap the hook, or review the script before rendering, a structured interface can make those choices easier to see.

So the direction I'm exploring is a familiar graphical workflow with AI helping at the right moments.

AI can suggest and analyze. The user can review, choose, and adjust.

To me, that's a more practical starting point than asking someone to hand the whole process to a black box.

6. From a Prompt to a Real Creative Workflow

In Sprokl, I'm building around something sellers already have: their own product materials.

The core workflow is designed to move through four stages:

Product assets: Start with existing product photos and video clips.
Creative concepts: Explore advertising angles before committing to a final video.
Script and visual review: See how the message, scenes, and available footage fit together.
Production: Turn the chosen direction into a finished video, including editing elements such as captions and voiceover.

What matters to me is that users have a chance to understand the creative direction before spending time and money on production.

I'm also developing an Ad Clone workflow. The idea is to study a reference ad's creative structure—its opening, pacing, scenes, and narrative—and adapt those patterns using the seller's own product assets. It's about learning from a creative approach, not simply copying someone else's finished ad.

Ad Clone is still in development, so I'm not presenting it as a released or proven feature. But it represents the kind of control I want the product to offer.

7. The Hard Part Isn't Just the Video Model

Working on Sprokl has reminded me that a good AI model is only one piece of a usable product.

What happens when an analysis step fails? How do you explain an AI-generated creative suggestion? What if a user likes the script but wants a different shot? Can they reuse the assets they already uploaded?

And most importantly: can someone finish the task without having to understand the technology behind it?

These aren't just model-quality questions. They're product-design questions.

I used to think a lot about adding capabilities. Now I spend more time asking which decisions the product should simplify—and which decisions users should still control.

I don't have every answer yet. But the more I work on this, the more I believe that making AI usable is a different challenge from making AI impressive.

8. What I'm Learning Next

Sprokl is still a work in progress. I'm improving the existing experience, developing the new Ad Clone workflow, and working toward a more reliable end-to-end process.

I'm also trying to spend more time listening to actual sellers and marketers.

It's easy to design a neat workflow on a whiteboard. Real businesses rarely work that neatly. Different teams have different bottlenecks, from coming up with concepts to finding footage to producing enough variations.

I'm interested in understanding where a more flexible workflow could help. That may eventually mean adapting parts of the product to particular needs, but I don't want to promise custom integrations or APIs before I've learned what users actually need.

If you're an ecommerce founder, marketer, or someone building AI creative tools, I'd love to ask you one question:

Which part of making video ads takes the most time for you right now?

Is it generating ideas, writing scripts, choosing footage, editing variations, or turning campaign insights into your next round of creatives?

I'd genuinely love to hear how you're doing it today.

I'm sharing what I learn while building Sprokl. If this problem sounds familiar, feel free to leave a comment or reach out.

For me, the interesting future of AI video advertising isn't just about producing more videos. It's about making the creative process easier to understand, control, and improve.

I'm an independent founder with a background in SaaS product management and AI products. I enjoy photography, video editing, and building simpler experiences for complicated workflows.

Disclosure: I'm the founder of Sprokl, the product discussed here. This article reflects my own professional experiences and product thinking, and was drafted with AI writing assistance.

How we cut our homepage from 4 MB to 179 KB and reached Lighthouse 100

Muhammad Ali Raza — Fri, 13 Nov 2026 05:15:59 +0000

Two PNG images made up almost all of quantumines.com's 4 MB homepage. Serving them as AVIF and WebP at the size each screen needs cut the page to 179 KB and the mobile Largest Contentful Paint (LCP) from about 17 seconds to 1.8 seconds. Self-hosted fonts with size-matched fallbacks, two colour fixes and an accessible-name fix took the remaining Lighthouse scores to 100. We made all of these changes on 10 November 2026 in one commit. This write-up lists each one, with the code, so another small team can repeat it in an afternoon.

Where did the 4 MB come from?

The network list in Lighthouse and Chrome DevTools answered that quickly. The homepage loaded a 2.0 MB PNG for the hero sculpture and a 2.1 MB PNG for the product artwork, both exported straight from a design tool at full quality. Everything else on the page, HTML, CSS, JavaScript and icons, was small. A 1.6 MB logo PNG was also referenced from our structured data, though not displayed.

On a phone over a throttled mobile connection, which is what Lighthouse simulates, two megabytes take many seconds to arrive. And because the hero is the largest thing on screen, it is the element LCP measures: until it finishes, the page counts as not loaded.

quantumines.com homepage before and after (Lighthouse mobile, 10 November 2026)

Measure	Before	After
Total page weight	about 4 MB	179 KB
Largest Contentful Paint (mobile)	about 17 s	1.8 s
Accessibility score	96	100
All four Lighthouse categories	not all 100	100 / 100 / 100 / 100
Cumulative Layout Shift	not recorded	0

Step 1: serve images as AVIF and WebP, at the right size

We exported each large image three times (480, 768 and 1,024 pixels wide for the hero) in AVIF and in WebP, and let the browser pick with <picture>, srcset and sizes. The 1,024-pixel hero dropped from 2.0 MB as PNG to 44 KB as AVIF; a phone downloads the 480-pixel AVIF, which is 12.5 KB.

<picture>
  <source type="image/avif"
    srcset="assets/hero-480.avif 480w, assets/hero-768.avif 768w, assets/hero-1024.avif 1024w"
    sizes="(max-width: 760px) 100vw, 55vw">
  <source type="image/webp"
    srcset="assets/hero-480.webp 480w, assets/hero-768.webp 768w, assets/hero-1024.webp 1024w"
    sizes="(max-width: 760px) 100vw, 55vw">
  <img id="hero-image" src="assets/hero-1024.webp"
    alt="Sculpture of mint metal, glass and textured stone"
    width="1024" height="1280" fetchpriority="high">
</picture>

Three details matter. The width and height attributes let the browser reserve the space before the image arrives, so nothing jumps. fetchpriority="high" tells it to fetch the LCP image before other images. And the hero is never lazy-loaded: lazy loading the largest image on screen delays exactly the thing LCP measures. The product artwork, further down the page, got the same AVIF and WebP treatment at 768 and 1,536 pixels.

The 1.6 MB logo in our Organization schema was replaced with a 512-pixel PNG of 137 KB. Search engines don't need more than that, and it no longer turns up in audits.

Step 2: self-host the fonts and stop the text from jumping

The site used Manrope and DM Sans from Google Fonts. That meant a render-blocking stylesheet request to another domain, then the font files from a third. We downloaded the variable versions of both (they are under the SIL Open Font License), serve them as WOFF2 from our own domain and preload them:

<link rel="preload" href="/fonts/manrope-var.woff2" as="font" type="font/woff2" crossorigin>
<link rel="preload" href="/fonts/dm-sans-var.woff2" as="font" type="font/woff2" crossorigin>

With font-display: swap, text appears at once in a fallback font and switches when the web font arrives. The switch can move text, because Arial is wider or taller than the real font. So we defined fallback faces measured against Arial, with size-adjust and the ascent and descent overrides, and listed them right after the real font:

@font-face {
  font-family: 'Manrope Fallback';
  src: local('Arial'), local('Liberation Sans'), local('Helvetica');
  size-adjust: 94.9%;
  ascent-override: 112.4%;
  descent-override: 31.6%;
  line-gap-override: 0%;
}
--display: 'Manrope', 'Manrope Fallback', sans-serif;

Together with the image dimensions, this is why Cumulative Layout Shift is 0.

Step 3: fix the last accessibility points

Accessibility was at 96. Lighthouse flagged two things. Some muted text in the light theme was below the 4.5:1 contrast ratio that WCAG requires for normal text, so we darkened those colours until each passed. And the mobile menu button's accessible name didn't match its visible label "Menu", which confuses people who use voice control: they say what they see. Making the name match the label fixed it. Both changes took minutes; finding them is what the audit is for.

Step 4: cache by file type

Our Node server sets Cache-Control from the file extension. Fonts never change under the same name, so browsers may keep them for a year. Images can be kept for a week and refreshed in the background. HTML, CSS and JavaScript are checked again after an hour, so a deploy shows up quickly:

ext === '.woff2' ? 'public, max-age=31536000, immutable'
: /^(\.avif|\.webp|\.png|\.jpe?g|\.svg|\.ico)$/.test(ext)
  ? 'public, max-age=604800, stale-while-revalidate=86400'
  : 'public, max-age=3600'

Step 5: make the next page feel instant

Two newer browser features cost a few lines each. Speculation Rules tell Chrome to prefetch a same-site page when the visitor hovers over its link, so the click usually lands on a page that is already downloaded. We exclude anything with side effects or private data, such as log-in, the app, admin pages and the API:

<script type="speculationrules">
{"prefetch":[{"source":"document","where":{"and":[
  {"href_matches":"/*"},
  {"not":{"href_matches":["/login","/app/*","/admin/*","/api/*","/logout"]}}
]},"eagerness":"moderate"}]}
</script>

Cross-document view transitions add a short cross-fade between pages with one CSS rule, turned off for people who ask their system for reduced motion:

@view-transition { navigation: auto; }
@media (prefers-reduced-motion: reduce) {
  @view-transition { navigation: none; }
}

Browsers that don't support either feature ignore them, so there is no downside for anyone.

How do we keep it at 100?

Scores drift as pages are added. Every time the site is rebuilt, we run Lighthouse on the homepage, the newest post and one product page, and fix anything below 95 before it goes live. New images must be AVIF or WebP with width, height and srcset. Each page's preview image for social media is generated at build time, so nobody uploads a multi-megabyte PNG by hand. The same discipline carried over to adding WebMCP for AI agents: the site still scores 100 in all four categories with it.

What would we tell another small team?

Open the network list before touching code. On most small sites one or two images are most of the weight.
Fix the LCP image first: modern format, right size, fetchpriority="high", never lazy.
Give every image width and height, and give web fonts a size-matched fallback. That is most of CLS.
Treat accessibility warnings as bugs. They are usually quick to fix and they affect real people.
Re-run the audit on every build, not once a quarter.

Frequently asked questions

Is AVIF supported in all browsers?

AVIF works in current versions of Chrome, Edge, Firefox and Safari. The <picture> element falls back to WebP and then to the <img> source, so older browsers still get an image.

What is a good Largest Contentful Paint?

Google's Core Web Vitals treat an LCP of 2.5 seconds or less as good, measured at the 75th percentile of real page loads. quantumines.com's homepage measures 1.8 seconds in Lighthouse's mobile test.

Does a Lighthouse score of 100 guarantee good Core Web Vitals?

No. Lighthouse is a lab test on one simulated device. Core Web Vitals in Search Console come from real visitors' browsers. A high lab score makes good field data likely, but the field data is what Google uses.

Quantumines is a technology and product studio in Lahore, Pakistan, founded by Muhammad Ali Raza (Ali Arbi). We build websites and web apps for clients with the same standards; see our services.

Originally published on quantumines.com.

Spring Boot MCP Server Security: 2026-07-28 Spec Guide

Krishna Yadav — Fri, 13 Nov 2026 05:15:35 +0000

To secure a Spring Boot MCP server under the 2026-07-28 spec, treat it as an OAuth 2.1 resource server: keep the endpoint stateless, validate the JWT signature, issuer and audience, authorize each tool by scope, and demand step-up authentication for payment tools. On the login-server side, Client ID Metadata Documents (CIMD) replace Dynamic Client Registration.

I previously covered exposing a Java backend as an MCP server with Spring AI, which dealt with getting tools in front of an agent. Here the question is different: what changes once that agent can reach a payment API, and what the 2026-07-28 revision of the protocol means for whoever carries the pager for the server.

The authorization half of this is not news. The spec has framed MCP servers as OAuth resource servers since the 2025-06 revision. What the new revision changes is operational: it removes the session handshake and the open-registration fallback, the two things that made a remote MCP server painful to run behind a normal load balancer and a normal identity provider. If you have built PSD2 APIs, a lot carries over directly. Strong customer authentication step-up becomes an acr/auth_time challenge (RFC 9470). TPP consent scopes become tool scopes. The "which TPP is this?" question becomes the CIMD client ID. The mapping is almost one-to-one, and I use it below.

The plain-language version

If OAuth and MCP vocabulary is new to you, this section is the short glossary. Otherwise skip to the architecture.

MCP (Model Context Protocol) lets an AI assistant ask another system "what can you do?" and get back a list of tools, for example "look up a payment" or "create a refund", which it can then call.

OAuth lets an application act for a user without ever seeing the user's password, the mechanism behind every "Sign in with Google" button. It involves a client (here, the AI application), an authorization server (the login system that hands out access tokens), and a resource server (the system that holds the data and inspects those tokens). Your MCP server is the resource server.

An access token is usually a JWT: a signed blob of claims saying who the user is, which scopes (named permissions such as payments:read) were granted, and which service the token was issued for. That last claim is the audience, and it is the one people forget. A token issued for the billing service must bounce off the payments service.

Two problems drove the 2026-07-28 changes.

Memory. Older remote MCP servers started a session: the client sent an initialize call, received a session ID, and every follow-up request had to land on the replica that remembered it. In practice that meant sticky sessions on the load balancer, and a user whose pod got rescheduled lost their conversation. The new revision drops the initialize handshake and the session ID, so each request is self-contained and any replica can serve it.

Introductions. Before an authorization server can show a consent screen, it has to know who the app is. The old fallback was Dynamic Client Registration (DCR, RFC 7591), where any app registers itself unattended. Across thousands of AI apps and one shared login server, that produces thousands of records nobody can vouch for. The revision deprecates DCR in favour of Client ID Metadata Documents (CIMD): the app publishes a JSON file on its own domain and uses that file's URL as its client ID. The login server fetches it, reads the name and redirect addresses, and applies its own trust policy. No record exists on the login server until a human or a policy says yes.

What the changelog confirms, and what it leaves open

I read the official 2026-07-28 changelog on modelcontextprotocol.io and compared it with the project's release post. These points are firm:

The initialize handshake and session ID are gone from the core, which is the basis for the stateless transport.
DCR (RFC 7591) is deprecated in favour of CIMD (the changelog tracks this as PR #2858). It keeps working for backward compatibility and is slated for removal in a later version.
Issuer validation per RFC 9207 is added, so a client can tell whether an authorization response really came from the server it called.

Two things are not firm. The changelog gives no removal date for DCR, so I plan around "deprecated, not removed" rather than any calendar. And a few secondary write-ups list a registration priority order (pre-registered credentials, then CIMD, then DCR, then ask the user); I have not seen that order stated in the spec text, so I do not rely on it.

On Spring AI, my working position is this. Spring Security gives you everything in the OAuth half for free: resource-server JWT validation, SCOPE_ authorities, method security. Everything MCP-specific that I describe below as custom (protected resource metadata, audience binding, step-up guard, CIMD resolution) is code I wrote and run myself, because I did not find a Spring AI starter that provides it for me. If a newer release of the starters covers one of them, delete mine; the Spring AI changelog for your exact version settles that in a few minutes. For a broader view of what Java teams get when building agents on top of this, see my notes on Spring AI's new Agents project.

Architecture

Four moves. The client calls the MCP endpoint with no token and gets a 401 pointing at the server's protected resource metadata (RFC 9728), a JSON document naming the authorization server. The client then goes to that authorization server and presents its CIMD URL as its client ID. It returns with a token. Finally it calls whichever replica the load balancer picks, and that replica validates the token locally. Nothing on any instance remembers the client, which is what keeps scaling out dull, the quality I want most from infrastructure.

Step 1: a stateless endpoint behind a plain load balancer

At AirAsia we served around 130 million requests a day, and the rule that paid off most was refusing instance-local state. I have watched sticky sessions mask a capacity problem: one node runs hot while its neighbours idle, the dashboards average it out, and nobody notices until that node is replaced during a deploy and its users all get logged out at once. A stateless MCP endpoint lets you keep the same rule.

The security configuration is where statelessness shows up. No session, no CSRF cookie ritual, only bearer tokens:

@Configuration
@EnableMethodSecurity
class McpSecurityConfig {

    @Bean
    SecurityFilterChain mcp(HttpSecurity http,
                            McpAuthEntryPoint entryPoint) throws Exception {
        http
            .securityMatcher("/mcp/**", "/.well-known/oauth-protected-resource")
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .csrf(csrf -> csrf.disable())          // bearer-only, no cookies
            .authorizeHttpRequests(a -> a
                .requestMatchers("/.well-known/oauth-protected-resource").permitAll()
                .anyRequest().authenticated())
            .oauth2ResourceServer(o -> o
                .jwt(Customizer.withDefaults())
                .authenticationEntryPoint(entryPoint));
        return http.build();
    }
}

Turning CSRF off is defensible only because this path takes nothing but an Authorization header and never reads cookies. The day someone adds cookie auth to the same prefix, switch it back on.

Whether the MCP transport itself is stateless is a separate question from whether your security chain is. Spring AI has had a stateless Streamable HTTP server mode for a while, and that is where I would start. I could not match it against the final 2026-07-28 wire format from the release notes alone, so I test instead of trusting: run two replicas, alternate requests between them in an integration test, and treat any failure as hidden state. It is a ten-line test and it has caught session leaks for me more than once.

Step 2: publish protected resource metadata

The client needs to learn where to log in. RFC 9728 defines a well-known document for exactly that. This is custom code, and it is small:

@RestController
class ProtectedResourceMetadataController {

    private final McpSecurityProperties props;

    ProtectedResourceMetadataController(McpSecurityProperties props) {
        this.props = props;
    }

    @GetMapping(value = "/.well-known/oauth-protected-resource",
                produces = MediaType.APPLICATION_JSON_VALUE)
    Map<String, Object> metadata() {
        return Map.of(
            "resource", props.resourceUri(),                 // e.g. https://mcp.example.com/mcp
            "authorization_servers", List.of(props.issuer()),
            "scopes_supported", List.of("payments:read", "payments:write", "mandates:read"),
            "bearer_methods_supported", List.of("header"));
    }
}

resource does double duty. It is also the identifier your tokens must carry as their audience, which the next step enforces.

Step 3: JWT validation with audience binding

This is the step where I have seen real damage. A resource server that checks signature and issuer but not audience will happily accept a token that was minted for a different service in the same realm. In open banking we called it a confused-deputy bug and it failed pen-tests. The typical way it arrives: a team reuses one realm for the internal admin API and the new agent-facing API, the agent's token is scoped fine, and nobody notices that the admin API never asked who the token was for. With MCP the exposure is wider, because the premise is that many different agents hold tokens.

Spring Security verifies signature and expiry by default. Audience binding takes a few lines of your own, expressed as a proper OAuth2TokenValidator so failures come back as standard invalid_token errors:

@Bean
JwtDecoder jwtDecoder(McpSecurityProperties props) {
    NimbusJwtDecoder decoder = NimbusJwtDecoder
        .withIssuerLocation(props.issuer())
        .build();

    OAuth2TokenValidator<Jwt> issuer =
        JwtValidators.createDefaultWithIssuer(props.issuer());

    OAuth2TokenValidator<Jwt> audience = token ->
        token.getAudience().contains(props.resourceUri())
            ? OAuth2TokenValidatorResult.success()
            : OAuth2TokenValidatorResult.failure(new OAuth2Error(
                "invalid_token", "Token audience does not include this MCP server", null));

    decoder.setJwtValidator(new DelegatingOAuth2TokenValidator<>(issuer, audience));
    return decoder;
}

Two details matter. Compare against the exact resource URI, never a prefix match, or a hostile https://mcp.example.com.evil.net slips through. And the decoder downloads the issuer's signing keys and caches them, so a request does not trigger a network call and replicas share nothing. The flip side is key rotation: when the identity provider rolls its keys, a decoder holding a stale cache rejects good tokens until it refetches, so alert on a burst of signature failures right after a rotation rather than assuming the attack is real.

Step 4: where CIMD fits, and who does the work

This confuses people, so to be explicit: your MCP server never touches CIMD documents. The authorization server does. The client hands the authorization server a client ID that is an HTTPS URL, such as https://agent.example.org/client.json. The authorization server downloads it, checks that the client_id field inside equals the URL it came from, validates the redirect URIs, and shows the user a consent screen carrying the app's name.

For a Java team the work divides like this:

If you operate your own authorization server on Spring Authorization Server, expect to write a small RegisteredClientRepository that turns a URL-shaped client ID into a client by fetching and validating the document. I have not seen URL-form client IDs supported out of the box, so I plan on writing it.
If you use Keycloak, Entra, Auth0 or Okta, ask the vendor for their CIMD date in writing. Some will trail the spec by months, which is why you keep DCR on, behind rate limits, until they ship.
Whoever does the fetching, treat that fetch as hostile. The URL comes from a stranger, so block private address ranges, cap the body size, set short timeouts and refuse redirects. The SSRF mitigation post covers this class of bug, and CIMD is a textbook instance: a login server that downloads arbitrary URLs for people it has never met.

This is the validation I would put in front of that fetch:

record ClientMetadata(String clientId, String clientName, List<String> redirectUris) {}

class CimdResolver {

    private final HttpClient http = HttpClient.newBuilder()
        .followRedirects(HttpClient.Redirect.NEVER)
        .connectTimeout(Duration.ofSeconds(2))
        .build();

    ClientMetadata resolve(URI clientIdUrl) throws Exception {
        if (!"https".equals(clientIdUrl.getScheme()) || clientIdUrl.getPath().isEmpty()) {
            throw new IllegalArgumentException("client_id must be an https URL with a path");
        }
        // Resolve and reject loopback, link-local and private ranges before connecting.
        SsrfGuard.assertPublicAddress(clientIdUrl.getHost());

        var request = HttpRequest.newBuilder(clientIdUrl)
            .timeout(Duration.ofSeconds(3)).GET().build();
        var response = http.send(request, HttpResponse.BodyHandlers.ofByteArray());

        if (response.statusCode() != 200 || response.body().length > 16_384) {
            throw new IllegalArgumentException("Metadata fetch rejected");
        }
        ClientMetadata meta = mapper.readValue(response.body(), ClientMetadata.class);
        if (!meta.clientId().equals(clientIdUrl.toString())) {
            throw new IllegalArgumentException("client_id in document does not match its URL");
        }
        return meta;
    }
}

The client_id equality check carries the whole design. Without it anyone can host a document claiming to be somebody else's app.

On the benefits over DCR: a DCR identity is a random string your server minted, which tells you nothing. A CIMD identity is a domain somebody controls, so you can rate-limit it, block it and put it in a report. For compliance work this is the real gain. I can finally answer an auditor's "who is this client?" with a name and a domain, not "whoever hit the registration endpoint".

Step 5: scope-based tool authorization

Authentication says who; authorization says what. In a tool protocol the natural unit is the tool. Enforce at the method that implements the tool, not at the HTTP path, because MCP routes every call through one endpoint and a path rule cannot distinguish get_payment from create_refund.

@Service
class PaymentTools {

    @Tool(description = "Look up a payment by its id")
    @PreAuthorize("hasAuthority('SCOPE_payments:read')")
    PaymentView getPayment(String paymentId) {
        return payments.find(paymentId);
    }

    @Tool(description = "Create a refund for a settled payment")
    @PreAuthorize("hasAuthority('SCOPE_payments:write')")
    RefundReceipt createRefund(String paymentId, BigDecimal amount) {
        stepUp.require(StepUpLevel.STRONG);   // see next section
        return refunds.create(paymentId, amount);
    }
}

Spring Security converts the token's scope claim into SCOPE_ authorities by default, so the annotation works without extra mapping; no string comparisons in the tool body. The trap is that @Tool discovery and Spring's method-security proxy must apply to the same bean. If the proxy is missing, @PreAuthorize is silently ignored and every call is allowed. So write a test that sends a token without payments:write and expects a refusal. That one test is the only thing standing between you and an open refund tool.

A second layer is easy to miss: the tool list itself. Filter it per caller, so an agent with read-only scope never even sees createRefund. A manipulated model has less to attempt, and agent behaviour gets more predictable.

Step 6: step-up authorization for high-risk tools

A scope granted at login is a blunt instrument. The user said yes to "payments" an hour ago in a chat about something else. Should an instruction injected through a web page be able to move money on the strength of that old yes? No.

Step-up authorization means the server asks for fresher or stronger proof before dangerous actions. The mechanism is a challenge: the server responds with a WWW-Authenticate header, and the client goes back to the authorization server for a token with the extra scope or a stronger authentication level. For "you lack the permission" the code is insufficient_scope, with the scope named in the header. For "log in again, more strongly", RFC 9470 defines the insufficient_user_authentication error built on the acr (authentication context class) and auth_time claims.

In PSD2 terms, this is SCA dynamic linking applied to an agent: the bank re-checks the customer at the moment of the risky act, not at session start. The mandate flows I built for recurring payments (see the Commercial VRP post) work the same way. An agent calling a payment tool is just a new caller of an old rule.

This part is custom code; I have not seen Spring AI ship a step-up primitive, so here is the guard I use:

@Component
class StepUpGuard {

    private static final Duration MAX_AGE = Duration.ofMinutes(5);

    void require(StepUpLevel level) {
        Jwt jwt = (Jwt) SecurityContextHolder.getContext()
            .getAuthentication().getPrincipal();

        boolean strongEnough = level.acceptedAcr().contains(jwt.getClaimAsString("acr"));
        Instant authTime = Instant.ofEpochSecond(
            ((Number) jwt.getClaim("auth_time")).longValue());
        boolean fresh = authTime.isAfter(Instant.now().minus(MAX_AGE));

        if (!strongEnough || !fresh) {
            throw new StepUpRequiredException(level, MAX_AGE);
        }
    }
}

@RestControllerAdvice
class StepUpAdvice {

    @ExceptionHandler(StepUpRequiredException.class)
    ResponseEntity<Void> challenge(StepUpRequiredException ex) {
        String header = "Bearer error=\"insufficient_user_authentication\","
            + " error_description=\"A stronger or more recent login is required\","
            + " acr_values=\"" + ex.level().primaryAcr() + "\","
            + " max_age=\"" + ex.maxAge().toSeconds() + "\","
            + " resource_metadata=\"" + props.metadataUrl() + "\"";
        return ResponseEntity.status(HttpStatus.UNAUTHORIZED)
            .header(HttpHeaders.WWW_AUTHENTICATE, header).build();
    }
}

Use whichever error code your authorization server and chosen MCP client both understand, and test the full round trip, since client behaviour on challenges is the least uniform part of this ecosystem. Keep the five-minute window in configuration so risk and compliance can change it without a deploy.

One rule I do not bend: the model never decides whether step-up happened. The guard reads the verified token and nothing the agent says.

Step 7: audit logging you can hand to a regulator

Each tool call by an agent is a decision taken on someone's behalf, and in a regulated setting somebody will later ask you to reconstruct it. DORA-style expectations boil down to: which user, which client, which tool, which arguments, what happened. The evidence side is in the DORA and NIS2 policy-as-code post.

An aspect over the tool methods keeps this out of business code:

@Aspect
@Component
class ToolAuditAspect {

    private static final Logger audit = LoggerFactory.getLogger("mcp.audit");

    @Around("@annotation(org.springframework.ai.tool.annotation.Tool)")
    Object record(ProceedingJoinPoint pjp) throws Throwable {
        Jwt jwt = (Jwt) SecurityContextHolder.getContext()
            .getAuthentication().getPrincipal();
        String tool = pjp.getSignature().getName();
        long started = System.nanoTime();
        String outcome = "ALLOWED";
        try {
            return pjp.proceed();
        } catch (AccessDeniedException | StepUpRequiredException e) {
            outcome = "DENIED";
            throw e;
        } catch (Exception e) {
            outcome = "FAILED";
            throw e;
        } finally {
            audit.info("tool={} sub={} client={} acr={} outcome={} ms={} trace={}",
                tool, jwt.getSubject(), jwt.getClaimAsString("client_id"),
                jwt.getClaimAsString("acr"), outcome,
                (System.nanoTime() - started) / 1_000_000,
                Span.current().getSpanContext().getTraceId());
        }
    }
}

Log the tool name and identifiers, but hash or mask arguments that contain account numbers. The trace ID links the audit line to the distributed trace, which is how a strange agent run actually gets debugged (see distributed tracing with OpenTelemetry). Ship the audit logger to an append-only store apart from application logs. For metrics and alerting on agent behaviour, see observability and guardrails for agentic AI backends.

Failure modes I test before launch

Authorization code is easy to get subtly wrong, so these negative tests run in CI:

A validly signed token for a different audience is rejected with 401.
A payments:read token calling createRefund is rejected with 403.
A token with the right scope but a stale auth_time gets the step-up challenge, not a success.
A CIMD document whose client_id differs from its URL is refused.
A CIMD URL pointing at 169.254.169.254 or a private range is refused before any connection opens.
Two replicas, alternating requests, behave identically.

If one of these cannot be written as a test, some state is still hiding in the design.

What I would do on Monday

For a team that already has an MCP server built the earlier Spring AI way:

Week one: add audience validation and the protected resource metadata. Both are small, they close the most dangerous hole, and they do not depend on any vendor catching up.
Week two: move tool authorization onto scopes with @PreAuthorize and filter the tool list per caller.
Week three: add the step-up guard to the two or three tools that move money or change a mandate, plus the audit aspect.
In parallel: ask your identity team for their CIMD plan with dates, and keep DCR enabled behind rate limits until it lands. DCR is deprecated, not removed, so there is a clock but no emergency.
Last: compare your Spring AI release notes with this list and delete whichever custom code the starters now cover.

None of this is exotic. I spent years on PSD2 consent flows and mandate APIs, and an AI agent is the newest kind of third-party provider: faster and less predictable than a human. The old controls (audience, scope, freshness, audit) still hold, and the 2026-07-28 spec lets you apply them without fighting the transport. More of my payments and AI backend work is under projects, with my background at experience.

If you are planning this migration and want a second pair of eyes on the threat model, send me the architecture through the contact section. If staffing is the open question, my remote developer hiring guide covers hiring a senior Java engineer for EU and ASEAN teams.

FAQ

What is an MCP server?

An MCP server is a program that offers a list of actions and data to an AI assistant through the Model Context Protocol. The assistant asks what the server can do, then calls those actions on a user's behalf.

How do I secure a Spring Boot MCP server?

Treat it as an OAuth 2.1 resource server. Use Spring Security's JWT resource-server support, add an audience validator, guard each tool with a @PreAuthorize scope, require step-up authentication on payment tools, and audit-log every tool call.

What is a Client ID Metadata Document?

A JSON file an AI application hosts at an HTTPS address, with that address serving as its client ID. The authorization server reads the file to learn the app's name and redirect addresses rather than requiring registration first.

Why is Dynamic Client Registration being replaced?

Open registration produces anonymous client records that are hard to trust or clean up. A metadata document ties the client to a domain you can check. DCR is deprecated, not yet removed.

CryptoPulse: Build a Real-Time Cryptocurrency Intelligence Platform on AWS

Muhammad Umair Ashraf — Fri, 13 Nov 2026 05:15:12 +0000

What if your application could monitor Bitcoin, Ethereum, and other cryptocurrencies, detect unusual market activity, analyze historical trends, and send alerts automatically?

Cryptocurrency markets never sleep.

Bitcoin can experience a sudden price movement while Ethereum trading volume increases. Another cryptocurrency might attract unusual market activity within minutes.

For traders, analysts, and crypto enthusiasts, monitoring multiple exchanges and dashboards manually can quickly become overwhelming.

The challenge isn't simply collecting cryptocurrency prices. It's identifying meaningful market movements, preserving historical data, and notifying users when configured conditions are met.

That's the idea behind CryptoPulse – Cryptocurrency Intelligence, a serverless market-monitoring and analytics platform built using AWS.

In this project, we'll explore how to connect real-time market data ingestion, event processing, historical storage, SQL analytics, and automated notifications using AWS services.

1. What Are We Building?

CryptoPulse is designed to monitor cryptocurrency market activity and generate useful insights.

Its core capabilities include:

Real-time monitoring of Bitcoin, Ethereum, and other supported cryptocurrencies.
Detection of configurable price fluctuations.
Identification of unusual trading-volume spikes.
Historical market data storage and analysis.
Automated email notifications when configured conditions are triggered.

For example, imagine these events:

Bitcoin moves more than 2% within 15 minutes.
Ethereum trading volume becomes three times its recent average.
Solana experiences an unusual price fluctuation.
A supported cryptocurrency experiences a sudden increase in trading activity.

CryptoPulse can evaluate these conditions and notify subscribed users.

The platform is designed for market monitoring and analytics, not guaranteed price prediction or automated trading.

2. AWS Architecture

The architecture follows an event-driven, serverless design.

       Cryptocurrency Exchange APIs
                    |
                    v
          Market Data Producer
        (Python / WebSocket Client)
                    |
                    v
          Amazon Kinesis Data Streams
                    |
                    v
               AWS Lambda
             Data Processing
                    |
          +---------+----------+
          |                    |
          v                    v
    Amazon S3             Amazon DynamoDB
    Raw Market Data       Latest Market State
          |                    |
          v                    v
    AWS Glue Catalog     DynamoDB Streams
          |                    |
          v                    v
    Amazon Athena         AWS Lambda
          |                    |
          v                    v
    S3 Query Results      Amazon SNS
                               |
                               v
                       Email Notifications

The main components are:

AWS Service	Responsibility
Amazon Kinesis Data Streams	Real-time market data ingestion
AWS Lambda	Event processing and market calculations
Amazon S3	Raw and processed historical data
Amazon DynamoDB	Latest market state and alert records
DynamoDB Streams	Trigger downstream alert processing
Amazon SNS	Notification delivery
AWS Glue Data Catalog	Dataset metadata and schemas
Amazon Athena	Historical SQL analytics

The diagram represents the logical architecture. Each integration needs appropriate AWS configuration, IAM permissions, and event source mappings.

3. Step One: Collect Cryptocurrency Market Data

The first component is a market data producer.

We can build it using Python and connect it to supported cryptocurrency exchange APIs.

For continuous updates, WebSocket connections are useful because they allow the producer to receive market events without repeatedly polling an endpoint.

For example, CryptoPulse could monitor:

BTCUSDT
ETHUSDT
SOLUSDT
BNBUSDT
XRPUSDT

The exact feed depends on the metrics required.

Ticker streams can provide price and rolling market statistics. Individual trade streams can provide transaction-level information for custom volume calculations.

Before publishing events, normalize exchange-specific messages into a common structure.

Example event:

{
  "exchange": "example-exchange",
  "symbol": "BTCUSDT",
  "event_type": "ticker",
  "price": 68500.25,
  "volume_24h": 12500.75,
  "price_change_percent_24h": 2.85,
  "event_timestamp": "2026-11-13T09:30:00Z"
}

These values are illustrative, not live market data.

A consistent event format makes downstream processing easier, especially when supporting multiple exchanges.

4. Step Two: Amazon Kinesis Data Streams

Once the producer collects market events, it publishes them to Amazon Kinesis Data Streams.

Kinesis acts as the central ingestion layer.

Instead of connecting the producer directly to every processing component, events are published to a stream and consumed by downstream applications.

A useful partition key is the trading symbol:

BTCUSDT
ETHUSDT
SOLUSDT

This helps keep related records associated with the same shard and supports ordering within that shard.

Kinesis allows ingestion and processing capacity to be managed independently.

For production, consider:

Stream capacity and throughput.
Data retention requirements.
Consumer lag and iterator age.
Throttling and failed writes.
Producer retry and reconnection logic.

Exchange WebSocket connections can be interrupted, so the producer should be designed to reconnect and recover gracefully.

5. Step Three: AWS Lambda for Market Processing

AWS Lambda can consume Kinesis records through an event source mapping.

The processing function validates, transforms, and analyzes incoming market events.

Its responsibilities include:

Validating incoming records.
Normalizing exchange-specific fields.
Calculating price changes and volume indicators.
Updating the latest market state.
Storing raw and processed information.

For example, a simple percentage price-change calculation looks like this:

def calculate_price_change(previous_price, current_price):
    if previous_price <= 0:
        return 0

    return (
        (current_price - previous_price)
        / previous_price
    ) * 100

Suppose Bitcoin's previous reference price was $65,000 and the current price is $66,300.

((66,300 - 65,000) / 65,000) × 100

= 2%

CryptoPulse can evaluate this result against a configured threshold.

One important detail: the system must define its monitoring window. A 2% change over one minute is different from a 2% change over 24 hours.

Use event timestamps and appropriate reference prices when calculating indicators.

6. Step Four: Amazon S3 for Historical Data

Real-time processing is useful, but historical information is equally important.

Amazon S3 provides durable storage for raw and processed market data.

A possible bucket structure:

cryptopulse-market-data/

    raw/
        exchange=binance/
            symbol=BTCUSDT/
                year=2026/
                    month=11/
                        day=13/

    processed/
        exchange=binance/
            symbol=BTCUSDT/
                year=2026/
                    month=11/
                        day=13/

    athena-results/

The raw zone preserves original or minimally transformed events. This is useful for auditing and reprocessing.

The processed zone contains normalized records for analytical queries.

Partitioning by exchange, symbol, and date can help reduce the amount of data scanned by Athena.

For larger datasets, consider Apache Parquet. Its columnar format can improve analytical query efficiency and help reduce scan costs.

Keep raw data, processed data, and Athena query results in separate prefixes.

7. Step Five: Amazon DynamoDB for Latest Market State

S3 is suitable for historical storage, but retrieving the latest price should not require scanning historical files.

Amazon DynamoDB can maintain the latest market state for each trading pair.

For example:

{
  "PK": "ASSET#BTCUSDT",
  "SK": "LATEST",
  "price": 66300.00,
  "volume_24h": 14500.50,
  "price_change_24h": 2.0,
  "updated_at": "2026-11-13T09:30:00Z"
}

The values are illustrative.

DynamoDB can also store alert records, including:

Asset symbol.
Alert type.
Observed value.
Configured threshold.
Event timestamp.
Notification status.

This makes it easier for the application to retrieve recent market information and alert history.

For production, design partition and sort keys around access patterns. Use conditional writes or other concurrency controls when multiple processing attempts could update the same market state.

8. Step Six: Detect Price Fluctuations and Volume Spikes

This is where CryptoPulse becomes more than a data collection pipeline.

Price movement detection

Suppose a user wants an alert whenever Bitcoin moves more than 2% within 15 minutes.

An illustrative rule:

IF 15-minute price change >= +2%
THEN create an upward movement alert

A downward movement rule could be:

IF 15-minute price change <= -2%
THEN create a downward movement alert

Thresholds should be configurable according to user preferences.

Trading-volume spike detection

A sudden increase in trading volume can indicate unusual market activity.

CryptoPulse can compare recent volume with a historical baseline.

Volume Ratio =
Recent 5-minute volume
/
Average 5-minute volume over baseline period

An illustrative rule:

IF Volume Ratio >= 3
THEN create a volume spike alert

This means recent volume is at least three times the selected baseline.

The comparison should use equivalent time windows and account for missing or incomplete data.

Historical indicators

The platform can also calculate:

Moving averages.
Percentage price changes.
Rolling trading volume.
High and low prices over selected periods.
Volatility measures.

These indicators help users explore market behavior, but they do not guarantee future price movements.

9. Step Seven: DynamoDB Streams and Lambda for Alerts

The architecture uses DynamoDB as the trigger for a second Lambda function.

This can be implemented using DynamoDB Streams.

When a market-state or alert record changes, DynamoDB Streams makes that change available to a downstream consumer.

A configured Lambda event source mapping invokes the alert-processing function.

Market Processing Lambda
          |
          v
     DynamoDB Update
          |
          v
    DynamoDB Streams
          |
          v
      Alert Lambda
          |
          v
       Amazon SNS
          |
          v
    Email Notification

The alert Lambda checks whether the event represents a valid notification.

It should verify:

The threshold condition was satisfied.
The alert is relevant to the user.
The notification has not already been sent.
The event is not an outdated update.

Use an idempotency key to reduce duplicate notifications. It could include the asset, alert type, monitoring window, and threshold configuration.

A cooldown period can also prevent repeated alerts for the same continuing market condition.

10. Step Eight: Amazon SNS for Automatic Notifications

Once the alert Lambda confirms that a notification should be delivered, it can publish a message to Amazon Simple Notification Service (SNS).

SNS supports notification delivery to configured subscribers, including email endpoints.

Example notification:

CryptoPulse Market Alert

Asset: BTCUSDT

Alert Type: Price Movement

Observed Change: +2.0%

Monitoring Window: 15 Minutes

Event Time: 09:30 UTC

Status: Threshold Triggered

This is an illustrative message.

Users can receive alerts about significant price movements, unusual volume spikes, or other configured market conditions.

SNS handles notification delivery. The application logic determines whether a market event deserves an alert.

11. Step Nine: AWS Glue and Amazon Athena for Historical Analytics

Real-time notifications tell users when something happens. Historical analytics help them understand market behavior over time.

AWS Glue Data Catalog maintains metadata about datasets stored in S3.

A Glue crawler can inspect supported data and infer table metadata. Alternatively, teams can define schemas explicitly.

Amazon Athena uses the Glue Data Catalog to discover tables and query the underlying S3 data using SQL.

This allows CryptoPulse to analyze historical cryptocurrency data without managing a separate database cluster for every analytical workload.

Query recent Bitcoin records

SELECT
    event_timestamp,
    symbol,
    price,
    volume_24h
FROM cryptopulse_market_db.market_data
WHERE symbol = 'BTCUSDT'
  AND year = '2026'
  AND month = '11'
  AND day = '13'
ORDER BY event_timestamp DESC
LIMIT 100;

The table and partition names are examples and must match the actual dataset registered in Glue.

Find records with high reported volume

SELECT
    symbol,
    event_timestamp,
    volume_24h
FROM cryptopulse_market_db.market_data
WHERE volume_24h > 10000
ORDER BY volume_24h DESC;

This query uses an illustrative absolute threshold. A proper volume-spike analysis should compare recent volume against a historical baseline.

Where are Athena results stored?

Athena writes query results to a configured S3 output location, for example:

s3://cryptopulse-market-data/athena-results/

Remember the different responsibilities:

S3 stores market datasets.
Glue Data Catalog stores metadata and table definitions.
Athena queries S3 datasets using SQL.
S3 stores Athena query output in the configured results location.

Glue does not automatically transform the market records. It provides metadata that helps analytical services understand the data.

12. Production Readiness: What Should We Consider?

A production market-monitoring platform must handle interruptions, duplicate events, delayed records, and sudden increases in market activity.

Some important engineering considerations include:

Data validation: Validate prices, volumes, timestamps, symbols, and event formats before processing.

Duplicate handling: Use exchange trade IDs or event identifiers where available. Make processing idempotent so retries do not double-count trades or create repeated alerts.

Event ordering: Events can arrive late or out of order. Use exchange timestamps and sequence identifiers where available instead of assuming arrival order represents event order.

Failure handling: Configure Kinesis/Lambda retry behavior, record-age limits, and an on-failure destination where appropriate. Monitor iterator age and processing errors.

Alert reliability: Store alert state and notification status. Use idempotency keys and cooldown periods.

Security: Apply least-privilege IAM roles, encrypt stored data, and use AWS Secrets Manager for exchange credentials when authenticated APIs are required.

Cost management: Monitor Kinesis capacity, Lambda execution, S3 storage, Glue activity, and Athena data scanned. Use partitioning and columnar formats to help control analytical costs.

13. Implementation Roadmap

CryptoPulse can be developed in manageable stages.

Phase 1: Market Data Ingestion

Select supported exchanges.
Build a Python producer.
Connect to WebSocket market streams.
Normalize incoming events.
Publish records to Kinesis Data Streams.

Phase 2: Real-Time Processing

Configure Kinesis-to-Lambda integration.
Validate and process records.
Calculate price and volume indicators.
Store raw and processed events in S3.
Update DynamoDB market state.

Phase 3: Alert Engine

Configure DynamoDB Streams.
Build the alert-processing Lambda.
Add configurable thresholds and cooldowns.
Integrate Amazon SNS.
Test duplicate-event handling.

Phase 4: Historical Analytics

Organize S3 datasets.
Create Glue database and table definitions.
Configure crawlers or explicit schemas.
Run historical SQL queries using Athena.
Store query results in a dedicated S3 prefix.

Phase 5: Production Hardening

Add monitoring and alarms.
Configure retries and failure handling.
Secure credentials and permissions.
Implement data retention policies.
Test recovery and load behavior.

14. Future Enhancements

Once the core pipeline is operational, CryptoPulse can evolve with additional capabilities.

Multi-exchange comparison: Compare the same trading pair across supported exchanges.
Custom user alerts: Allow users to configure assets, thresholds, and monitoring windows.
Market dashboards: Display current prices, historical movements, volume trends, and alerts.
Advanced analytics: Add volatility analysis, moving averages, and other indicators.
Machine learning experiments: Explore anomaly detection using historical market data and validated models.
Portfolio monitoring: Add optional user-configured asset watchlists with secure authentication and privacy controls.

These are potential extensions, not features automatically provided by the initial architecture.

Conclusion

Cryptocurrency markets generate enormous amounts of continuously changing information.

Collecting that information is only the first step. The real value comes from processing it, identifying unusual activity, preserving historical records, and making useful insights accessible.

CryptoPulse demonstrates how AWS services can work together to build this type of platform.

Amazon Kinesis Data Streams provides real-time ingestion. AWS Lambda processes incoming events. Amazon S3 stores historical data. DynamoDB maintains the latest market state. DynamoDB Streams supports event-driven alert processing. Amazon SNS delivers notifications. AWS Glue and Amazon Athena make historical analysis possible.

Together, these services provide a serverless foundation that can evolve as market-data volume and user requirements grow.

The goal of CryptoPulse is simple: don't just watch cryptocurrency prices—understand the market activity behind them.

Disclaimer: CryptoPulse is a conceptual market-monitoring and analytics project. It does not provide investment advice, guarantee price predictions, or execute trades.

References

How to Turn Your API into an MCP Server Without Writing Server Code

Docstar — Fri, 13 Nov 2026 05:14:57 +0000

More of your users now try your product from inside an AI assistant. They ask Claude, ChatGPT or Cursor to "create an invoice" or "send a test message" before they ever open your dashboard. If the assistant can't reach your API, it guesses, gives up, or suggests a product it can reach.

The fix is an MCP server for your API. This guide shows the two ways to get one, and how to have a working server in an afternoon without writing or hosting any server code.

What an MCP server for your API has to do

The Model Context Protocol (MCP) is the open standard AI assistants use to discover and call outside tools. An MCP server for an API needs to:

Describe each action as a tool, with a name, a description and a schema for its inputs.
Authenticate as the user, so every call runs with that person's own permissions.
Make the real HTTP request and return the result to the assistant.
Stay in sync with your API as endpoints change.
Be hosted somewhere with a URL users can paste into their assistant.

New to MCP? Start with What Is an MCP Server?

Option 1: Build it yourself

You can write a server with an MCP SDK, define every tool by hand, add OAuth, deploy it and keep it updated whenever your API changes.

This makes sense when you need custom logic between the assistant and your API, such as combining several calls into one tool. The cost is a second codebase: every new endpoint, renamed field or auth change has to be made twice, once in the API and once in the MCP server.

Option 2: Generate it from your API docs

Your API docs already contain everything an MCP server needs: endpoints, methods, parameters, body fields, auth headers and descriptions. If the docs are the source, the server can be generated from them and stays current every time you publish.

That is how DocStar works. Every published collection gets its own hosted MCP server. You write docs once and get:

a public API docs site for humans,
an MCP server AI assistants can use to search your docs and call your API,
a CLI that turns each endpoint into a terminal command.

Step by step: from API to MCP server with DocStar

1. Create an API collection

Create a collection of type API and choose its slug. The slug is permanent and becomes part of your MCP URL, so pick your product name, for example acme.

2. Bring in your endpoints

Use whatever you already have:

An OpenAPI or Postman file. Import it into the collection.
cURL commands. Paste them and DocStar fills in the method, URL, headers and body.
Only code. Connect your coding agent to DocStar's own MCP server (https://mcp.docstar.io/mcp) and ask it to read your routes and document every public endpoint. It creates the pages and endpoints for you.

3. Write descriptions for the assistant, not just for people

The assistant decides which tool to call from the words you write. For each endpoint:

Name it verb-first, the way a user would ask: Create Order, List Invoices.
Say when to use it and what it changes, including any required order ("call Create Cart first").
Give a body example with every accepted field, and describe each field. Fields missing from the example are hard for an assistant to use.
Add a sample success response and the common errors.
Never put real keys or customer data in the docs.

4. Publish

Publish the module pages and endpoints. Unpublished endpoints don't appear in the MCP server.

5. Copy your MCP URL

Open the collection's MCP tab. Your server is already running at:

https://mcp.docstar.io/connector/acme

The tab also gives ready-made setup snippets. For Claude Code, for example:

claude mcp add --transport http acme https://mcp.docstar.io/connector/acme

6. Turn on sign-in

If your API needs a user token, add your OAuth details (login URL, token URL, client ID and secret) in the MCP tab and add DocStar's callback URLs to your OAuth app. The first time an assistant calls your API, the user signs in, and their token is attached to every later call. The assistant never sees the credential.

API-key based? The server includes a key tool, so a user enters their key once instead of pasting it into prompts.

For private APIs, switch on Require sign-in when connecting so nobody can even search the docs without signing in. More in Securing Your DocStar MCP Server.

7. Tune it for your product

The generated server works out of the box. Four settings make it noticeably better:

Dedicated tools. Give your 5 to 10 most-used endpoints their own named tools. Everything else stays reachable through the built-in API tools.
The skill. Rewrite the generated quickstart with your product's main workflows and rules, such as "always confirm before deleting".
Tool descriptions. Say what your product is and when to use each built-in tool.
A custom domain. Serve the server from mcp.yourcompany.com.

Test it like a user would

Add the URL to Claude or Cursor and ask a real question in plain words: "show my last five orders" or "create a test customer named Jane". Watch which tool the assistant picks and which fields it sends. If it picks the wrong endpoint or misses a field, fix the description or the body example and publish again. There is nothing to redeploy.

Build or generate?

	Build it yourself	Generate it from docs (DocStar)
Time to first working server	Days to weeks	An afternoon
Hosting	You run it	Hosted for you
Stays in sync with the API	Manual, in a second codebase	Every time you publish docs
End-user sign-in	You implement OAuth	Configure OAuth or API keys
Also gives you	Just the server	Docs site, MCP server and CLI
Custom multi-step logic	Full control	Through the skill and instructions

FAQ

Do I need an OpenAPI spec? No. You can import one, paste cURL commands, write endpoints in the editor or let a coding agent document them from your code.

Which assistants can use the server? Any client that supports remote MCP servers over HTTP, including Claude, Claude Code, Cursor, VS Code and ChatGPT where custom connectors are enabled. See How to Connect Your API to ChatGPT, Claude and Cursor.

Can the assistant change data? Only if you allow it. Reads and writes are separate tools, so clients that ask for approval on writes can let reads through. With sign-in, every call runs with the user's own permissions.

What happens when my API changes? Update the endpoint in DocStar and publish. The MCP server reads the published docs, so the change is live without a deploy.

Get your MCP URL

Create a free DocStar collection, import your API and publish. Your MCP server is ready the moment you do.

Originally published on the DocStar blog.