03. Start the local QVAC service

In lesson 02 a script read the chat image from the terminal. But Redact is a web app: the page you upload lives in the browser, and the browser can’t run the OCR model. So before the model can help, we need something that sits between the two. Checkpoint: redact-03-local-service, after redact-02-first-ocr

Why can’t the browser just run the model?

QVAC’s engines are native code: compiled programs that use your CPU and GPU directly, plus model files hundreds of megabytes in size. A web page can’t load native code, and you wouldn’t want each browser tab downloading and holding a model of its own. So the model lives in one ordinary Node.js process on your machine, and the page talks to it over HTTP. That process is the local service. It’s the same idea as calling a cloud API, with one difference that matters here: the address is 127.0.0.1, your own computer. The page image goes from one program on your laptop to another, and nowhere else. More on this design: About the local service.

What makes a boundary safe?

Anything that listens for requests can be sent bad ones, so the service gets a few firm rules from the start.

Rule	Why
Listen on `127.0.0.1` only	Other machines on your network can’t reach it
Accept browser requests only from `localhost` pages	A website you happen to have open can’t use it
Check every request against a schema	A malformed request is rejected before any model sees it
Say “unavailable” instead of guessing	A missing model never turns into made-up results

Both sides share one description of the request and response, written with Zod. The browser checks what it receives with the same schemas the service uses to check what it’s sent.

1. Get this lesson’s code

Stop the app if it’s running. From the repository root, redact-course, bring in this lesson’s commit and install the new packages:

git cherry-pick redact-03-local-service
cd redact
npm ci

This lesson adds zod and tsx, so npm ci takes a minute or two. To see every change, open the comparison on GitHub.

File	What it is
`src/features/redact/analysis-contract.ts`	The shared schemas: health, request, response, error
`qvac-service/analyzer.ts`	The interface any analyzer must implement
`qvac-service/server.ts`	The HTTP service and its rules
`qvac-service/index.ts`	Starts the service, with a placeholder analyzer for now
`src/features/redact/analysis-client.ts`	The browser’s side: calls the service and checks the replies
`qvac-service/server.test.ts`, `analysis-client.test.ts`	Tests for both sides
`package.json`	Adds `zod`, `tsx` and the `qvac:service` script

2. Read the contract

Open src/features/redact/analysis-contract.ts. This is the request the browser will send for each page:

export const analyzePageRequestSchema = z.object({
  documentId: z.string().min(1),
  pageId: z.string().min(1),
  pageNumber: z.number().int().positive(),
  width: z.number().int().positive(),
  height: z.number().int().positive(),
  pngBase64: z.string().min(1),
  level: z.enum(["private", "confidential"]),
  direction: z.string().max(500),
});

One page at a time, as a PNG encoded as base64 text, with its size in pixels. level and direction are what you chose on the privacy screen; nothing uses them yet, but they travel with every page from now on. Each OCR block that comes back must look like this:

export const rawOcrBlockSchema = z.object({
  text: z.string(),
  bbox: z.tuple([
    z.number().finite(),
    z.number().finite(),
    z.number().finite(),
    z.number().finite(),
  ]),
  confidence: z.number().min(0).max(1).nullable(),
});

That’s lesson 02’s output, written down as a rule: text, four finite numbers for the box, and a confidence between 0 and 1.

3. Read the analyzer interface

Open qvac-service/analyzer.ts:

export interface DocumentAnalyzer {
  getState(): AnalyzerState;
  analyzePage(input: AnalyzePageRequest): Promise<AnalysisResponse>;
  close(): Promise<void>;
}

The service doesn’t know about QVAC at all. It only knows that something can report its state, analyse a page, and shut down. That lets us test the service with fakes, and swap in the real model next lesson without touching the server. At this checkpoint, qvac-service/index.ts plugs in a placeholder:

const analyzer: DocumentAnalyzer = {
  getState: () => ({
    service: "ready",
    models: [
      { kind: "ocr", id: "qvac-ocr-latin", state: "not_loaded" },
      { kind: "reasoning", id: "not-configured", state: "not_loaded" },
    ],
  }),
  analyzePage: async () => {
    throw new Error("OCR is not connected at this checkpoint");
  },
  close: async () => undefined,
};

It’s honest: the OCR model isn’t loaded, and asking it to analyse a page fails.

4. Read the server’s rules

Open qvac-service/server.ts. The first thing every request meets is the origin check:

function localAppOrigin(request: IncomingMessage): string | null {
  const origin = request.headers.origin;
  if (!origin) return null;
  try {
    const url = new URL(origin);
    return url.protocol === "http:" &&
      (url.hostname === "127.0.0.1" || url.hostname === "localhost")
      ? origin
      : null;
  } catch {
    return null;
  }
}

Browsers send an Origin header saying which site made the request. If it’s there and isn’t a localhost page, the service answers 403 origin_forbidden and stops. Tools like curl send no Origin, which is why you can test from the terminal. Then the analyse route parses the body against the schema before doing anything:

if (request.method === "POST" && request.url === "/v1/analyze-page") {
  let input;
  try {
    input = analyzePageRequestSchema.parse(await readJson(request));
  } catch {
    sendJson(request, response, 400, {
      error: { code: "invalid_request", message: "Invalid analyze-page request" },
    });
    return;
  }

  busy = true;
  try {
    sendJson(request, response, 200, await options.analyzer.analyzePage(input));
  } catch {
    sendJson(request, response, 503, {
      error: { code: "analyzer_unavailable", message: "Local analysis is unavailable" },
    });
  } finally {
    busy = false;
  }
  return;
}

Bad input gets 400. If the analyzer throws, for any reason, the browser gets 503 analyzer_unavailable instead of a half-made result. The busy flag shows up in /health while a page is being analysed; lesson 08 uses it to turn away a second request. readJson also stops reading after 20 MB, so a huge upload can’t fill your memory.

5. Start the service

npm run qvac:service

You should see:

Redact QVAC service listening on http://127.0.0.1:4317

Leave it running. The port comes from REDACT_QVAC_PORT if you set it, otherwise 4317.

6. Ask for its health

In a second terminal:

curl http://127.0.0.1:4317/health

{"service":"ready","models":[{"kind":"ocr","id":"qvac-ocr-latin","state":"not_loaded"},{"kind":"reasoning","id":"not-configured","state":"not_loaded"}],"busy":false}

The service is ready, but the OCR model is not_loaded and there’s no reasoning model at all. A running process and a loaded model are different things, and the service reports them separately.

7. Send a bad request

curl -X POST http://127.0.0.1:4317/v1/analyze-page \
  -H "content-type: application/json" \
  -d '{}'

{"error":{"code":"invalid_request","message":"Invalid analyze-page request"}}

An empty body never reaches the analyzer.

8. Send a well-formed request

curl -X POST http://127.0.0.1:4317/v1/analyze-page \
  -H "content-type: application/json" \
  -d '{"documentId":"doc","pageId":"p1","pageNumber":1,"width":1,"height":1,"pngBase64":"AA==","level":"private","direction":""}'

{"error":{"code":"analyzer_unavailable","message":"Local analysis is unavailable"}}

This one passes the schema and reaches the placeholder, which throws. Instead of inventing OCR results, the service says it’s unavailable.

9. Pretend to be a website

curl -H "Origin: https://example.com" http://127.0.0.1:4317/health

{"error":{"code":"origin_forbidden","message":"Origin is not allowed"}}

Try -H "Origin: http://localhost:3101" instead, and you get the health response back. Stop the service with Ctrl+C.

If something goes wrong

EADDRINUSE when starting: something else is on port 4317, maybe a service from an earlier lesson. Stop it, or start this one with REDACT_QVAC_PORT=4318 npm run qvac:service.
curl: (7) Failed to connect: the service isn’t running, or is on a different port.
tsx: command not found: npm ci didn’t finish; run it again from the redact folder.

10. Check your work

npm run lint
npm run typecheck
npm test

npm test reports Tests 42 passed (42). The new tests in server.test.ts start a real server with fake analyzers and check each rule above.

So what just happened?

The browser now has somewhere to send its pages: a small service on your own machine, with clear rules about who may call it and what it accepts. It doesn’t read anything yet, and it says so instead of pretending.

Try it yourself

Send a request whose level is "secret" instead of "private". Before you run it, decide which error you expect; then check. Then send pageNumber: 0 and see the same rule catch it.

Where to next

Every file in this checkpoint: redact/ at redact-03-local-service
All routes and errors of the finished service: Local service API

Next: Send uploaded pages to local OCR (lesson 04)

​Why can’t the browser just run the model?

​What makes a boundary safe?

​1. Get this lesson’s code

​2. Read the contract

​3. Read the analyzer interface

​4. Read the server’s rules

​5. Start the service

​6. Ask for its health

​7. Send a bad request

​8. Send a well-formed request

​9. Pretend to be a website

​If something goes wrong

​10. Check your work

​So what just happened?

​Try it yourself

​Where to next