Someone adds a field to an interface, and the schema never gets updated. The docs stay stale until a client files a bug. There's no compiler error or failing test. The three sources of truth just drift apart.

In this tutorial, you'll learn how to collapse those three concerns into one definition using Hono and Zod. You'll build the same patterns I use in production, including in ClipForge, an open-source video processing toolkit I built and maintain. They help validation, types, and docs stay in sync by design.

By the end of this article, you should know how to:

• Define one Zod schema that handles runtime validation, TypeScript types, and OpenAPI docs

• Structure routes so the contract and the handler stay separated

• Keep database schemas and HTTP schemas as two deliberate layers

• Return one consistent error shape from every failure path

• Carry those same patterns from a small Tasks API into a real multi-service system

Prerequisites

To get the most out of this article, you'll need to know:

• JavaScript and basic TypeScript

• How REST APIs work (routes, request bodies, status codes)

• A little Node.js (installing packages, running scripts)

You don't need prior experience with Hono, Zod, or Drizzle.

Table of Contents

• Prerequisites

• 1. The Drift Problem

• 2. What Is Hono?

• 3. What Is Zod?

• 4. One Schema, Three Jobs

• 5. How to Set Up the Project

• 6. How to Define Your API Schemas

• 7. How to Separate Database Schemas from API Schemas

• 8. How to Define Routes as Contracts

• 9. How to Keep Handlers Thin

• 10. How to Return One Error Shape Everywhere

• 11. How to Generate Docs That Can't Drift

• 12. How to Make the App Production-Ready

• 13. How These Patterns Scale in a Production App

• Conclusion

1. The Drift Problem

Most TypeScript APIs end up maintaining three separate descriptions of the same data:

1. Runtime validation checks that run when a request arrives

2. TypeScript types shapes the compiler understands at build time

3. API documentation, the contract you show to consumers

Each one lives in a different file and updates on a different schedule. And none of them can see the others.

Figure 1: Three descriptions of the same data, maintained separately and often out of sync.

Hand-written interfaces disappear at runtime. Joi or Yup schemas validate data but don't give you types for free. OpenAPI files are usually edited by hand, if they're edited at all.

The fix is not "be more careful." The fix is one definition that produces all three outputs.

Figure 2: One schema definition produces three outputs.

That is what Hono and Zod give you when you use them together through @hono/zod-openapi.

2. What Is Hono?

Hono is a small, fast web framework built on Web Standard APIs, the same Request and Response primitives that run in Node.js, Deno, Bun, and Cloudflare Workers.

Compared with Express, that difference matters:

Hono's core is about 14kb. On Node it's roughly 5–7× faster than Express for the same workload. On Bun or Cloudflare Workers, the gap widens further because those runtimes are optimized for web standards.

For most CRUD APIs, your database is still the bottleneck. But at high concurrency, or on edge runtimes where cold starts matter, the framework gap is real.

More importantly for this tutorial: Hono's OpenAPI integration lets your route definition be the documentation.

3. What Is Zod?

Zod is a TypeScript-first schema validation library. You describe the shape of your data once. Zod then:

1. Validates that shape at runtime

2. Infers the TypeScript type with z.infer

3. Feeds OpenAPI docs when you attach .openapi() metadata

With Joi or Yup, you usually validate at runtime and then hand-write a matching interface. That's two definitions again. Zod removes the second one.

import { z } from 'zod';

const createTaskSchema = z.object({
  title: z.string().min(1).max(120),
  status: z.enum(['todo', 'in_progress', 'done']).default('todo'),
});

type CreateTaskInput = z.infer<typeof createTaskSchema>;
// { title: string; status?: "todo" | "in_progress" | "done" }

Change the schema, and every callsite that depends on CreateTaskInput updates with it. TypeScript will tell you what broke.

4. One Schema, Three Jobs

Here's the mental model for the rest of the article:

Figure 3: taskSchema is the single source of truth for validation, types, and docs.

1. Runtime validation: bad data is rejected before it reaches your handler, with structured field errors instead of a stack trace

2. TypeScript types: z.infer<typeof schema> is derived from the schema, not maintained beside it

3. OpenAPI docs: .openapi('Name') registers the schema in the generated spec, so /reference stays current

One definition with three outputs. Nothing to keep in sync by hand.

5. How to Set Up the Project

We'll use the companion demo from api-conf-demo. It's a small Tasks API that shows the patterns cleanly. Later, we'll look at how the same ideas show up in ClipForge at a larger scale.

Clone the repo and install dependencies:

git clone https://github.com/otutukingsley/api-conf-demo.git
cd api-conf-demo
npm install

Start the server:

npm run dev

You should see the API on http://localhost:8080, with interactive docs at /reference.

The important folders look like this:

src/
├── db/schema/          # Persistence layer (Drizzle tables)
├── lib/schemas/        # HTTP contract layer (Zod + OpenAPI)
├── lib/errors/         # One error envelope for every failure
├── routes/tasks/       # Route contracts + handlers
├── services/           # Business logic and DB access
├── app.ts              # Middleware, routers, OpenAPI wiring
└── env.ts              # Zod-validated environment config

This is still MVC. The tooling is just better:

Figure 4: Still MVC. Routes and handlers as the controller, schemas as the contract, and services as the model.

• Model services its own business logic and database access

• View / contract schemas define what data looks like at the DB and HTTP boundaries

• Controller routes declare the contract, handlers fulfill it

A request through the demo API looks like this:

Figure 5: Request flow through the demo API, including the validation failure path.

In that diagram, a request flows through the Client, Middleware, Route contract, Handler, Service, and DB. Middleware handles logging and CORS. The route contract validates the body with Zod.

If validation fails, the client gets a 422 ApiError and the handler never runs. If it passes, the handler gets a typed CreateTaskInput, calls TaskService.create(), the service inserts and parses the row, and the client gets 201 with the Task JSON.

6. How to Define Your API Schemas

Start with the HTTP contract in src/lib/schemas/task.ts:

import { z } from '@hono/zod-openapi';

export const taskStatusSchema = z
  .enum(['todo', 'in_progress', 'done'])
  .openapi('TaskStatus');

export const taskSchema = z
  .object({
    id: z.string().uuid().openapi({
      example: '8e2c9f0a-2222-4a5a-9c3e-1a2b3c4d5e6f',
    }),
    title: z.string().min(1).max(120).openapi({
      example: 'Write the talk abstract',
    }),
    description: z.string().max(2000).nullable().openapi({
      example: 'Cover Hono + Zod patterns',
    }),
    status: taskStatusSchema.default('todo'),
    dueDate: z.string().date().nullable().openapi({
      example: '2026-07-15',
    }),
    createdAt: z.string().openapi({ example: '2026-06-28 10:15:00' }),
    updatedAt: z.string().openapi({ example: '2026-06-28 10:15:00' }),
  })
  .openapi('Task');

export type Task = z.infer<typeof taskSchema>;

That one object is now the runtime validator, TypeScript type, and an OpenAPI component named Task.

Request schemas should derive from the same base instead of being redeclared:

export const createTaskSchema = taskSchema
  .pick({ title: true, description: true, status: true, dueDate: true })
  .partial({ description: true, status: true, dueDate: true })
  .openapi('CreateTask');

export const updateTaskSchema = createTaskSchema
  .partial()
  .openapi('UpdateTask');

export type CreateTaskInput = z.infer<typeof createTaskSchema>;
export type UpdateTaskInput = z.infer<typeof updateTaskSchema>;

CreateTask never includes id, because clients don't send one. UpdateTask makes every field optional, because a PATCH can touch any subset.

Figure 6: Request schemas derive from the same base resource schema.

We have three contracts with one source.

7. How to Separate Database Schemas from API Schemas

It's tempting to treat the database row and the API response as the same shape. In a tiny demo, they often look identical. In production, they diverge.

Keep them in separate files on purpose:

Figure 7: Keep database schemas and HTTP schemas as two deliberate layers.

Figure 7 has two panels connected by an arrow labeled "map" in the service.

Left pane src/db/schema/ (persistence):

• Starts from a Drizzle table definition

• That table drives SQL migrations

• It also produces drizzle-zod schemas for parsing rows

• And row insert/select types for TypeScript at the database boundary

Right panel src/lib/schemas/ (HTTP contract):

• Uses Zod + .openapi() as the public contract

• Defines request bodies / params clients may send

• Defines response bodies clients receive

• Registers OpenAPI components used by /doc and /reference

The arrow in the middle matters: the database shape isn't automatically the API shape. The service maps between them. That's why an internal column can exist on the left without becoming part of the HTTP contract on the right.

In short:

• src/db/schema/: what a row looks like in the database

• src/lib/schemas/: what the HTTP contract looks like

Here's the Drizzle table from the demo:

import { sql } from 'drizzle-orm';
import { sqliteTable, text } from 'drizzle-orm/sqlite-core';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { z } from 'zod';

export const taskStatusValues = ['todo', 'in_progress', 'done'] as const;

export const tasks = sqliteTable('tasks', {
  id: text('id').primaryKey(),
  title: text('title').notNull(),
  description: text('description'),
  status: text('status', { enum: taskStatusValues }).notNull().default('todo'),
  dueDate: text('due_date'),
  createdAt: text('created_at')
    .notNull()
    .default(sql`(current_timestamp)`),
  updatedAt: text('updated_at')
    .notNull()
    .default(sql`(current_timestamp)`),
});

export const selectTaskSchema = createSelectSchema(tasks, {
  status: z.enum(taskStatusValues),
});

export const insertTaskSchema = createInsertSchema(tasks, {
  id: () => z.string().uuid().optional(),
  title: () => z.string().min(1).max(120),
  description: () => z.string().max(2000).nullable().optional(),
  status: z.enum(taskStatusValues).optional(),
  dueDate: () => z.string().date().nullable().optional(),
});

One table definition gives you three outputs:

1. TypeScript types inferred from the columns

2. SQL migrations generated with drizzle-kit

3. Zod schemas via drizzle-zod

That's useful at the database boundary. It's not a replacement for your HTTP schemas.

The moment you add an internal archivedAt column, or a computed field the API returns that's not a column, the split pays for itself. Divergence becomes a normal change instead of a painful refactor.

Figure 8: The service decides what the client may see.

8. How to Define Routes as Contracts

In this architecture, a route doesn't "just handle a request." A route declares the contract: method, path, request schemas, and response schemas.

Figure 9: The route declares the contract. The handler fulfills it.

import { createRoute, z } from '@hono/zod-openapi';
import * as HttpStatusCodes from '@/lib/http-status-codes';
import { jsonContent } from '@/lib/openapi/json-content';
import { jsonApiErrorContent } from '@/lib/openapi/error-schema';
import {
  createTaskSchema,
  taskParamsSchema,
  taskSchema,
} from '@/lib/schemas/task';

export const createTask = createRoute({
  tags: ['Tasks'],
  method: 'post',
  path: '/tasks',
  summary: 'Create a task',
  request: {
    body: jsonContent(createTaskSchema, 'The task to create'),
  },
  responses: {
    [HttpStatusCodes.CREATED]: jsonContent(taskSchema, 'The created task'),
    [HttpStatusCodes.UNPROCESSABLE_ENTITY]:
      jsonApiErrorContent('Validation error'),
    [HttpStatusCodes.INTERNAL_SERVER_ERROR]: jsonApiErrorContent(
      'Internal server error',
    ),
  },
});

export const getTask = createRoute({
  tags: ['Tasks'],
  method: 'get',
  path: '/tasks/{id}',
  summary: 'Get a task by ID',
  request: {
    params: taskParamsSchema,
  },
  responses: {
    [HttpStatusCodes.OK]: jsonContent(taskSchema, 'The requested task'),
    [HttpStatusCodes.NOT_FOUND]: jsonApiErrorContent('Task not found'),
    [HttpStatusCodes.UNPROCESSABLE_ENTITY]:
      jsonApiErrorContent('Validation error'),
    [HttpStatusCodes.INTERNAL_SERVER_ERROR]: jsonApiErrorContent(
      'Internal server error',
    ),
  },
});

A small helper keeps response boilerplate readable:

export function jsonContent<T extends z.ZodTypeAny>(
  schema: T,
  description: string,
) {
  return {
    content: {
      'application/json': { schema },
    },
    description,
  };
}

Named status constants replace magic numbers. You use the same constants as object keys in the route and as switch cases in the handler. That makes status codes searchable and consistent.

9. How to Keep Handlers Thin

Once the route defines the contract, the handler only has to fulfill it.

export const getTask: AppRouteHandler<GetTaskRoute> = (c) => {
  try {
    const { id } = c.req.valid('param');
    return c.json(TaskService.get(id), HttpStatusCodes.OK);
  } catch (error) {
    const apiError = ApiError.parse(error);
    switch (apiError.statusCode) {
      case HttpStatusCodes.NOT_FOUND:
      case HttpStatusCodes.UNPROCESSABLE_ENTITY:
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      default:
        return c.json(
          apiError.toResponseBody(),
          HttpStatusCodes.INTERNAL_SERVER_ERROR,
        );
    }
  }
};

export const createTask: AppRouteHandler<CreateTaskRoute> = (c) => {
  try {
    const body = c.req.valid('json');
    return c.json(TaskService.create(body), HttpStatusCodes.CREATED);
  } catch (error) {
    const apiError = ApiError.parse(error);
    switch (apiError.statusCode) {
      case HttpStatusCodes.UNPROCESSABLE_ENTITY:
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      default:
        return c.json(
          apiError.toResponseBody(),
          HttpStatusCodes.INTERNAL_SERVER_ERROR,
        );
    }
  }
};

Notice what's not in the handler:

• No manual parsing of params or bodies

• No casting to any

• No business logic

c.req.valid('param') and c.req.valid('json') are already validated and typed. The service owns the database work:

get(id: string): Task {
  try {
    const row = db.select().from(tasks).where(eq(tasks.id, id)).get();
    if (!row) throw new NotFoundError(`Task ${id} not found`);
    return selectTaskSchema.parse(row);
  } catch (error) {
    throw ApiError.parse(error);
  }
},

The service wraps its body in one try/catch and normalizes every failure through ApiError.parse(). Zod errors, custom domain errors, and unexpected driver errors all become one typed shape.

10. How to Return One Error Shape Everywhere

Clients should never guess whether an error looks like { message }, { error }, or a raw stack trace.

In the demo, every failure becomes one envelope:

Figure 10: Every failure path becomes one predictable error shape.

The factory that creates routers bakes that behavior in with defaultHook:

export function createRouter() {
  return new OpenAPIHono({
    defaultHook: (result, c) => {
      if (!result.success) {
        const apiError = ApiError.parse(result.error);
        return c.json(apiError.toResponseBody(), apiError.statusCode);
      }
    },
  });
}

Every router goes through that factory. A bad UUID in a path param, a missing field in a POST body, or an invalid enum in a query string all produce the same response shape before the handler runs.

ApiError.parse() is the second half of the pattern:

public static parse(error: unknown): ApiError {
  if (error instanceof ApiError) return error;

  if (error instanceof ZodError) {
    return new ApiError('Validation error', {
      statusCode: 422,
      errors: error.flatten().fieldErrors,
    });
  }

  return new ApiError('Internal server error', { statusCode: 500 });
}

Handlers still use an explicit switch on status codes. That's intentional. Each route documents exactly which statuses it can return. A handler that should never emit 403 doesn't have 403 sitting in a shared helper's defaults.

The repetition is the point. Explicit beats clever here.

11. How to Generate Docs That Can't Drift

Because schemas are attached to route definitions, OpenAPI becomes a byproduct of the code instead of a separate chore.

Figure 11: Docs are generated from the same route definitions as the runtime code.

export function configureOpenAPI(app: OpenAPIHono) {
  app.doc('/doc', {
    openapi: '3.0.0',
    info: {
      title: 'Bulletproof Tasks API',
      version: '1.0.0',
    },
  });

  app.get(
    '/reference',
    apiReference({
      spec: { url: '/doc' },
      theme: 'kepler',
      layout: 'modern',
      pageTitle: 'Bulletproof Tasks API',
    }),
  );
}

• GET /doc returns the raw OpenAPI JSON

• GET /reference serves an interactive Scalar explorer

When you change a schema or a response code in the route file, the docs update with it. There's no second docs step to forget.

12. How to Make the App Production-Ready

Type safety at the request boundary isn't enough. Configuration and process lifecycle need the same discipline.

Validate Environment Variables at Boot

import { z } from 'zod';

const envSchema = z.object({
  NODE_ENV: z
    .enum(['development', 'test', 'production'])
    .default('development'),
  LOG_LEVEL: z
    .enum(['silent', 'debug', 'info', 'warn', 'error', 'fatal'])
    .default('info'),
  PORT: z.coerce.number().default(8080),
  DATABASE_URL: z.string().default('tasks.db'),
});

export const env = envSchema.parse(process.env);

If a required value is missing or malformed, the process exits immediately with a clear Zod error. That's much better than discovering undefined three requests into production.

Prefer Structured Logging

The demo uses Pino through hono-pino instead of a one-line console logger. In production you want JSON logs. In development you want something readable. One middleware can do both, and every request can carry a UUID.

Shut Down Cleanly

Docker and process managers send SIGTERM before they kill a process. Handle it. Close the HTTP server, then close the database handle, then exit. Without that, a SQLite file (or a Postgres connection pool) can be left in a dirty state.

Keep the App Runtime-Portable

Hono only depends on Web Standard APIs inside app. That means the same application object can run on Node:

import { serve } from '@hono/node-server';
import { app } from '@/app';

serve({ fetch: app.fetch, port: env.PORT });

Or on an edge runtime with almost nothing else:

import { app } from '@/app';

export default app;

That;s not a simplified example. That's the whole adapter.

13. How These Patterns Scale in a Production App

A Tasks API is a good teaching surface. Production systems are messier: you have uploads, background jobs, multiple packages, and longer-lived workflows.

ClipForge is a helpful example of a production app where those same ideas show up at scale. It's a self-hostable video processing toolkit built with Node.js, Hono, Zod, Drizzle, BullMQ, and Nuxt. You upload a video and get transcription, subtitles, summaries, chapter markers, and thumbnails.

The architecture looks like this:

apps/
├── api/        # Hono REST API
├── worker/     # BullMQ video processor
└── web/        # Nuxt frontend
packages/
├── shared/     # Zod schemas, constants, shared types
└── providers/  # OpenAI, Anthropic, Deepgram integrations

Figure 12: ClipForge keeps the same contract-first core across web, API, and worker packages.

A video job moves through stages like uploading, validating, extracting audio, and so on without inventing new response shapes along the way:

Figure 13: A video job moves through typed stages without inventing new response shapes.

The important part isn't the video pipeline. The important part is that the API still follows the same contract-first rules.

Shared Zod Schemas Across Packages

ClipForge keeps HTTP contracts in packages/shared, so the API, worker, and web app share one vocabulary:

export const processingFeatureSchema = z.enum([
  'transcription',
  'subtitles',
  'summary',
  'chapters',
  'thumbnails',
]);

export const videoUploadSchema = z.object({
  title: z.string().min(3).max(200),
  description: z.string().max(2000).optional(),
  features: z
    .array(processingFeatureSchema)
    .default([
      'transcription',
      'subtitles',
      'summary',
      'chapters',
      'thumbnails',
    ]),
  priority: z.enum(['low', 'normal', 'high']).default('normal'),
});

export const jobStatusSchema = z.object({
  jobId: z.string(),
  title: z.string().optional(),
  state: jobStateSchema,
  stage: jobStageSchema,
  progress: z.number().min(0).max(100),
  result: jobResultSchema.optional(),
  failedReason: z.string().optional(),
  createdAt: z.string(),
  updatedAt: z.string(),
});

When the worker finishes a stage, it doesn't invent a new response shape. It updates state against the same schemas the API returns to the client.

Routes Still Define the Contract

The upload route in ClipForge looks like the Tasks demo, just with multipart form data and rate limiting:

export const uploadVideo = createRoute({
  tags: ['videos'],
  method: 'post',
  path: '/videos/upload',
  middleware: [
    sessionMiddleware,
    apiKeysMiddleware,
    rateLimitMiddleware({
      windowMs: 60_000,
      max: 10,
      keyPrefix: 'ratelimit:upload',
    }),
  ] as const,
  request: {
    body: {
      content: {
        'multipart/form-data': {
          schema: z.object({
            file: z.instanceof(File),
            title: z.string().min(3).max(200),
            description: z.string().max(2000).optional(),
            features: z.string().optional(),
            priority: z.enum(['low', 'normal', 'high']).optional(),
          }),
        },
      },
    },
  },
  responses: {
    [HTTP_STATUS.ACCEPTED]: jsonContent(
      jobStatusSchema,
      'Video accepted for processing',
    ),
    [HTTP_STATUS.BAD_REQUEST]: jsonApiErrorContent('Invalid request'),
    [HTTP_STATUS.UNPROCESSABLE]: jsonApiErrorContent('Validation error'),
    [HTTP_STATUS.TOO_MANY_REQUESTS]: jsonApiErrorContent('Rate limit exceeded'),
  },
});

The handler validates input, writes a job row, enqueues BullMQ work, and returns 202 Accepted with a typed job status. The heavy lifting happens in the worker. The API stays a contract layer.

Figure 14: The API accepts the upload and returns a typed job status while the worker does the heavy lifting.

Figure 14 is a sequence diagram with five participants: Web UI, Hono API, BullMQ, Worker, and Postgres. It shows the async boundary between “accept the upload” and “finish processing.” Here's every step in the diagram:

1. The Web UI sends POST /videos/upload to the Hono API.

2. The Hono API runs Zod + middleware (validate input, session, rate limits, and related checks).

3. The Hono API performs insert job row in Postgres so the job exists before work starts.

4. The Hono API sends enqueue process-video to BullMQ.

5. The Hono API immediately returns 202 + jobStatusSchema to the Web UI. At this point the client has a typed job status, but transcription hasn't finished yet.

6. BullMQ later delivers process job to the Worker.

7. The Worker runs transcribe / analyze / thumbnails as background work.

8. The Worker writes update stage + result back to Postgres as stages complete.

9. The Web UI polls with GET /videos/jobs/{id} against the Hono API.

10. The Hono API reads the latest job from Postgres and returns jobStatusSchema agai the same response shape as step 5, now with updated stage, progress, and eventually result.

So the API stays a fast contract layer: accept, persist, enqueue, and respond. The worker owns the slow pipeline. The UI tracks progress by polling one share status schema.

Database Schemas Still Stay Separate

ClipForge stores jobs in Postgres with Drizzle:

export const jobs = pgTable('jobs', {
  id: varchar('id', { length: 36 }).primaryKey(),
  sessionId: varchar('session_id', { length: 36 }).notNull(),
  state: jobStateEnum('state').notNull().default('waiting'),
  stage: jobStageEnum('stage').notNull().default('uploading'),
  progress: integer('progress').notNull().default(0),
  title: varchar('title', { length: 200 }).notNull(),
  features: jsonb('features').$type<string[]>().notNull(),
  provider: varchar('provider', { length: 50 }).notNull().default('openai'),
  result: jsonb('result').$type<JobResult>(),
  failedReason: text('failed_reason'),
  createdAt: timestamp('created_at', { withTimezone: true })
    .notNull()
    .defaultNow(),
  updatedAt: timestamp('updated_at', { withTimezone: true })
    .notNull()
    .defaultNow(),
});

The table has persistence concerns like filePath and sessionId. The public jobStatusSchema doesn't have to expose all of them. That's the same DB-versus-API split from the Tasks demo, applied to a real workflow.

The Same Production Habits Still Apply

ClipForge validates environment variables with Zod on boot, configures OpenAPI and Scalar at /doc and /reference, normalizes failures through ApiError, and shuts down queues and Redis on SIGTERM.

The lesson is simple: if the small app is structured correctly, the large app doesn't need a different philosophy. It needs more packages, more middleware, and longer-running jobs on top of the same contract-first core.

Conclusion

Type-safe APIs aren't about adding more TypeScript. They're about removing duplicate sources of truth.

With Hono and Zod you can:

• validate requests at runtime

• infer types automatically

• generate OpenAPI docs from the same route definitions

• keep database schemas and HTTP schemas intentionally separate

• return one predictable error shape from every failure path

Start with the api-conf-demo if you want the smallest readable version of these patterns. Then look at ClipForge to see how the same ideas hold up when the API sits in front of uploads, queues, and multi-stage processing.

Once your route definition is the contract, your docs stop drifting, your handlers get thinner, and your clients get an API they can trust.

While these images are easy to view, extracting them individually isn't always simple. Many users rely on screenshots or manual cropping, which can reduce image quality and take unnecessary time.

In this tutorial, you'll build a browser-based PDF Image Extractor using JavaScript. The application lets users upload a PDF, preview its pages, extract embedded images, organize them by page, and download individual images or all extracted images at once.

Everything runs directly inside the browser, so uploaded documents never leave the user's device. This makes the tool fast, private, and easy to use without requiring a backend server.

By the end of this tutorial, you'll have a fully functional PDF Image Extractor capable of recovering embedded images while preserving their original quality.

Table of Contents

• Why Extract Images from PDFs?

• How Images Are Stored Inside PDF Files

• Understanding Embedded Images vs Rendered Pages

• Project Setup

• What Libraries Are We Using?

• Creating the Upload Interface

• Previewing Uploaded PDF Pages

• Finding Embedded Images

• Extracting Images from PDF Pages

• Displaying Extracted Images

• Downloading Individual Images

• Downloading All Images from the PDF

• Demo: How the PDF Image Extractor Works

• Performance Optimization Tips

• Important Notes from Real-World Use

• Common Mistakes to Avoid

• Conclusion

Why Extract Images from PDFs?

Although PDF documents are primarily designed for sharing text-based information, they often contain valuable visual assets. Product catalogs include product photographs, annual reports contain charts and graphs, presentations use icons and illustrations, brochures showcase marketing banners, and technical manuals include diagrams and engineering drawings.

Without a dedicated image extraction tool, users often take screenshots or manually crop pages to save these visuals. Unfortunately, screenshots usually reduce image quality, introduce unwanted page elements, and require significant manual effort when working with large documents.

A PDF Image Extractor automates this process by identifying every embedded image inside the document and separating it from the surrounding page content. Instead of copying an entire page, users receive individual image files that can be downloaded and reused immediately.

This capability is extremely useful across many industries.

Graphic designers frequently receive client brochures, advertisements, and presentation files that contain logos, icons, or promotional graphics. Instead of recreating those assets manually, they can extract the original images directly from the PDF and continue working with high-quality source files.

Marketing teams often work with catalogs, product flyers, promotional leaflets, and campaign reports. Extracting product photographs or promotional graphics saves considerable time when creating social media posts, advertisements, landing pages, or newsletters.

Publishers and content creators regularly receive PDF magazines, ebooks, newsletters, and educational material containing illustrations and infographics. Individual images can be extracted and reused without manually cropping every page.

Researchers frequently download scientific papers containing graphs, charts, microscopy images, satellite photographs, and experimental diagrams. Image extraction allows them to save those visuals separately for presentations, publications, or further analysis.

Educational institutions use image extraction when preparing teaching material. Teachers can reuse diagrams, mathematical figures, scientific illustrations, historical maps, or educational graphics from reference documents without recreating them from scratch.

Government departments often maintain scanned archives containing seals, stamps, signatures, photographs, maps, engineering plans, and official diagrams. Extracting these images individually simplifies document digitization and archival workflows.

E-commerce businesses can also benefit significantly from image extraction. For example, a seller may receive a supplier catalog in PDF format containing hundreds of product photographs. Instead of requesting every image separately, the seller can extract all embedded product images from the catalog within minutes and reuse them while preparing listings for platforms such as Amazon, Flipkart, Meesho, Shopify, or WooCommerce.

Businesses working with invoices and purchase documents can also recover company logos, QR codes, signatures, and barcode images for document verification or automation systems.

Because this application performs every operation locally inside the browser, sensitive business documents remain private while users quickly recover all embedded images from their PDFs.

How Images Are Stored Inside PDF Files

Many people assume that a PDF page is simply a picture of the document. In reality, PDF files are much more sophisticated.

Each page inside a PDF is built from multiple independent objects. Text is stored separately using fonts and character information. Lines and shapes are represented as vector drawing instructions. Images are embedded as independent image objects that are placed at specific positions on the page.

This separation is one of the reasons PDFs remain flexible and efficient. A document may contain dozens of pages while reusing the same company logo or icon multiple times without storing duplicate copies.

When an image is embedded inside a PDF, the file usually preserves information such as the image dimensions, color space, compression method, and image format. Depending on how the document was created, embedded images may use formats such as JPEG, PNG, JPEG2000, CCITT, or other PDF-supported image encodings.

A PDF Image Extractor scans the internal structure of the document to locate these embedded image objects. Instead of capturing the entire page as a screenshot, it retrieves each image individually whenever possible.

This approach preserves much higher quality because the original embedded image is recovered rather than recreating it from the rendered page.

Understanding how PDF files store images also explains why some documents contain dozens of extractable images while others contain none at all. If a PDF consists entirely of vector graphics or text, there may be no embedded raster images available for extraction.

Knowing the difference between these document structures helps developers build more accurate PDF processing tools while helping users understand the capabilities and limitations of image extraction.

Understanding Embedded Images vs Rendered Pages

One of the most common misconceptions about PDF image extraction is that every visible picture on a page can always be extracted as a separate image.

In reality, there is an important difference between embedded images and rendered page images.

An embedded image is an independent object stored inside the PDF document. These images usually retain their original quality and can often be extracted without any loss of resolution.

A rendered page, on the other hand, is simply a visual representation of everything that appears on the page. When PDF.js displays a page inside the browser, it combines text, vector graphics, images, backgrounds, and shapes into a single canvas. Although this rendered page looks identical to the original document, it's no longer separated into individual components.

For example, imagine a product catalog containing a company logo, five product photographs, several icons, and descriptive text.

The PDF page preview displays everything together as one complete page. However, the PDF Image Extractor scans the document internally and identifies the individual logo, each product photograph, and every embedded icon separately. This allows users to download each image individually instead of cropping screenshots from the page preview.

Another important point is that not every visible graphic is actually an image.

Some company logos are created entirely using vector drawing commands. Charts may also be generated using vector graphics rather than bitmap images. Since these objects are not stored as raster images, they can't always be extracted using an image extraction tool.

Understanding this distinction helps explain why image extraction results may differ between documents even when they appear visually similar.

For developers, learning how embedded resources differ from rendered pages provides a much deeper understanding of PDF internals and browser-based document processing.

Project Setup

We'll build the PDF Image Extractor using standard web technologies so that the entire application runs directly inside the browser without requiring a backend server.

The project consists of a simple HTML file for the interface, a CSS file for styling, and a JavaScript file that handles PDF loading, page rendering, image extraction, and downloading.

Create the following project structure:

pdf-image-extractor/

│── index.html

│── style.css

│── script.js

│── assets/

After creating the project, include the required JavaScript libraries inside your index.html file:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.4.168/pdf.min.js"></script>

<script src="https://unpkg.com/pdf-lib"></script>

<script src="script.js"></script>

Once these files are ready, the browser will have everything required to read PDF files, render document pages, inspect PDF objects, locate embedded images, and generate downloadable image files.

Keeping the project lightweight also makes it easier to understand each stage of the image extraction workflow.

What Libraries Are We Using?

Extracting images from PDF documents requires more than simply displaying PDF pages inside the browser. The application needs to load the document, inspect its internal structure, render preview pages, and recover embedded image objects.

To accomplish this, we'll use two JavaScript libraries.

The first library is PDF.js.

PDF.js is Mozilla's open-source PDF rendering engine. It allows browsers to load PDF documents without additional plugins and provides APIs for reading document pages, rendering previews, accessing page objects, and inspecting document resources.

In this project, PDF.js is responsible for loading the uploaded PDF and generating the page preview shown to the user before image extraction begins.

The second library is PDF-lib.

PDF-lib provides low-level access to PDF objects and document resources. Although it's widely used for editing PDF files, it's also useful when working with embedded objects and document manipulation. It complements PDF.js by giving developers additional flexibility when extending the application with future PDF editing features.

Together, these libraries allow us to create a browser-based image extraction workflow that is fast, secure, and completely client-side.

The following code initializes PDF.js:

pdfjsLib.GlobalWorkerOptions.workerSrc =

"https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.4.168/pdf.worker.min.js";

Loading the worker separately keeps PDF rendering responsive while large documents are processed.

Creating the Upload Interface

Every document processing application begins with uploading a file.

The upload interface is responsible for accepting PDF documents, validating the selected file, and preparing it for processing. A clean upload experience is important because it becomes the entry point for the entire application.

In this project, users can either drag a PDF onto the upload area or browse for a document using the standard file picker.

Once the file has been selected, the browser immediately verifies that it's a valid PDF before attempting to load it.

Supporting both drag-and-drop uploads and manual file selection provides a familiar experience across desktop and mobile devices.

The upload section also displays clear instructions so first-time users understand exactly how to begin extracting images.

Create the upload area using the following HTML:

<div id="dropZone" class="drop-zone">

    <div class="upload-icon">

        ☁

    </div>

    <h2>Drag & Drop PDF Here</h2>

    <p>Or click to browse file</p>

    <button id="selectBtn">

        Select PDF

    </button>

    <input

        type="file"

        id="pdfFile"

        accept="application/pdf"

        hidden>

</div>

Next, validate the uploaded document:

const file = pdfFile.files[0];

if(!file){

    return;

}

if(file.type !== "application/pdf"){

    alert("Please upload a valid PDF.");

    return;

}

After validation succeeds, the browser reads the uploaded file:

const buffer =

await file.arrayBuffer();

loadPDF(buffer);

At this point, the PDF has been loaded into memory and is ready for preview generation.

Previewing Uploaded PDF Pages

Before extracting images, users should first verify that they uploaded the correct document.

Instead of immediately scanning the PDF, the application generates thumbnail previews for every page. These previews help users confirm page order, inspect the document contents, and estimate where embedded images are located.

Preview generation is particularly useful for large reports, product catalogs, presentations, magazines, brochures, ebooks, and technical documentation containing dozens of pages.

Each preview is rendered using PDF.js and displayed inside a responsive grid layout.

First, load the uploaded document:

const pdf = await pdfjsLib

.getDocument({

    data:buffer

})

.promise;

Next, loop through every page:

for(

let pageNumber = 1;

pageNumber <= pdf.numPages;

pageNumber++

){

    renderPage(pageNumber);

}

Render the page as a canvas:

const page =

await pdf.getPage(pageNumber);

const viewport =

page.getViewport({

    scale:0.35

});

const canvas =

document.createElement("canvas");

canvas.width = viewport.width;

canvas.height = viewport.height;

await page.render({

    canvasContext:

    canvas.getContext("2d"),

    viewport

}).promise;

Finally, add the preview to the page:

previewContainer

.appendChild(canvas);

Once rendering is complete, every page becomes visible inside the preview area.

Users can scroll through the thumbnails and verify that the correct document has been uploaded before starting the extraction process.

Although the preview displays complete page images, no extraction has occurred yet. The next stage scans the internal PDF structure to locate every embedded image separately.

Why Previewing the PDF Matters

Previewing the uploaded document may seem like a small feature, but it greatly improves the overall user experience.

Without a preview, users have no way to verify that they selected the correct file before extraction begins. This becomes especially important when working with multiple PDFs that have similar filenames.

Page previews also help users estimate where images appear throughout the document. For example, a product catalog may contain photographs only on certain pages, while a technical report might include diagrams only within specific chapters.

By reviewing the page thumbnails first, users gain confidence that the document is correct before the application begins scanning for embedded images.

This simple verification step reduces mistakes, avoids unnecessary processing, and makes the overall workflow feel much more intuitive.

Finding Embedded Images

Once the PDF pages have been rendered and displayed in the preview section, the application is ready to search for embedded images.

This stage is different from generating page previews. The preview simply renders each page as a complete visual image, while the extraction process examines the internal structure of the PDF to locate every embedded image object stored inside the document.

Each page is scanned individually. If embedded images are found, the application records their location, dimensions, image format, and page number before preparing them for extraction.

This page-by-page approach makes it easier to organize the extracted images later and allows users to understand exactly where each image originated within the document.

Scanning only begins after users click the Extract Images button, ensuring that unnecessary processing is avoided if they simply want to preview the document.

First, create the click event for the extraction button:

document

.getElementById(

"extractBtn"

)

.addEventListener(

"click",

extractImages

);

Next, loop through every page inside the uploaded PDF:

for(

let pageNumber = 1;

pageNumber <= pdf.numPages;

pageNumber++

){

    const page =

    await pdf.getPage(

    pageNumber

    );

}

Read the page operator list:

const operatorList =

await page.getOperatorList();

Now inspect every drawing operation to determine whether it contains an embedded image:

operatorList.fnArray

.forEach(operation=>{

    if(

    operation ===

    pdfjsLib.OPS.paintImageXObject

    ){

        console.log(

        "Image Found"

        );

    }

});

After every page has been scanned, the application creates a collection containing all discovered images grouped by page.

This collection becomes the foundation for the extraction process that follows.

Extracting Images from PDF Pages

Once embedded image objects have been identified, the application begins extracting them from the PDF.

Unlike taking screenshots of an entire page, this method retrieves each embedded image individually whenever possible. As a result, the extracted images preserve their original quality, dimensions, and compression rather than inheriting the resolution of the page preview.

Each image is assigned to the page where it was found. Organizing images this way makes it much easier for users to locate graphics inside large reports, magazines, brochures, presentations, catalogs, technical manuals, and research papers.

As each page finishes processing, its extracted images are stored inside a JavaScript array before being displayed inside the browser.

Create an array for storing extracted images:

const extractedImages = [];

Save every discovered image:

extractedImages.push({

    page:

    pageNumber,

    image:

    imageData,

    type:

    imageType

});

Each stored object contains useful information that will later be displayed to the user.

The extraction routine continues until every page inside the uploaded PDF has been inspected.

Once complete, the browser immediately displays the extracted images without requiring another processing step.

Displaying Extracted Images

After extraction finishes, the application presents every recovered image inside an organized gallery.

Instead of displaying one long collection of images, the results are grouped according to the page from which they were extracted. This organization makes it much easier to understand the original document structure.

For every extracted image, the application displays a preview together with useful technical information.

Users can immediately see the image dimensions, image format, and the page where the image originated. This additional information helps determine whether an image is suitable for reuse before downloading it.

For example, a high-resolution product photograph may be useful for marketing material, while a small company logo may only be appropriate for branding purposes.

Loop through every extracted image:

extractedImages.forEach(image=>{

    renderImageCard(

    image

    );

});

Create the preview card:

const card =

document.createElement(

"div"

);

card.className =

"image-card";

Insert the preview:

const img =

document.createElement(

"img"

);

img.src =

image.image;

Display the image information:

details.innerHTML =

`

Dims:

${image.width} × ${image.height}

<br>

Type:

${image.type}

`;

Once every card has been created, the gallery displays all extracted images grouped beneath their respective pages.

This layout provides a clean overview of every image contained inside the uploaded PDF while making individual downloads straightforward.

Downloading Individual Images

Many users don't need every image contained inside a PDF.

For example, a designer may only want the company logo from a brochure, while a researcher may only need one graph from a scientific paper.

To support these workflows, every extracted image includes its own download button.

When clicked, the browser downloads only the selected image without affecting any of the remaining extracted images.

This allows users to quickly save exactly the graphics they need.

Create a download button:

const button =

document.createElement(

"button"

);

button.innerText =

"Download";

Attach the download event:

button.onclick = ()=>{

    downloadImage(

    image

    );

};

Generate the download:

const link =

document.createElement(

"a"

);

link.href =

image.image;

link.download =

image.fileName;

link.click();

Providing separate download buttons makes the application much more flexible because users can save only the images they actually need instead of downloading every extracted asset.

Downloading All Images from the PDF

Large PDF documents often contain dozens or even hundreds of embedded images.

Downloading every image individually would be both slow and repetitive.

To simplify this workflow, the application also includes a Download All Images from PDF button.

After extraction has completed, clicking this button automatically downloads every extracted image from every page.

This feature is particularly useful when working with supplier catalogs, product brochures, magazines, annual reports, technical documentation, ebooks, educational material, and presentation files containing many graphics.

Loop through every extracted image:

extractedImages.forEach(image=>{

    downloadImage(

    image

    );

});

Attach the click event:

downloadAllButton

.addEventListener(

"click",

downloadAllImages

);

Finally, allow users to begin another extraction:

startOverButton

.addEventListener(

"click",

resetApplication

);

After the downloads have completed, users can click Start Over to upload another PDF and repeat the extraction process without refreshing the browser.

Demo: How the PDF Image Extractor Works

Step 1: Upload Your PDF Document

The image extraction workflow begins by uploading a PDF document using either the drag-and-drop area or the file picker.

Once a document has been selected, the browser validates that the uploaded file is a PDF before reading it into memory. Since the application performs all processing locally, the uploaded document never leaves the user's computer, making the tool suitable for confidential business reports, catalogs, presentations, contracts, technical manuals, research papers, and other sensitive documents.

After the PDF has been loaded successfully, the application prepares every page for preview generation before image extraction begins.

Step 2: Preview Uploaded PDF Pages

After the upload is complete, the application renders thumbnail previews for every page inside the document.

Instead of immediately scanning the PDF for images, users first receive a visual overview of the entire document. This allows them to verify that they selected the correct PDF and quickly identify which pages contain photographs, diagrams, illustrations, charts, or other graphics.

Page previews are especially useful when working with large product catalogs, magazines, annual reports, brochures, technical documentation, educational books, and research papers containing dozens or even hundreds of pages.

This verification step helps prevent unnecessary processing and improves the overall user experience.

Step 3: Extract Embedded Images

Once the document has been verified, users click the Extract Images button to begin scanning the PDF.

The application examines every page individually, searching for embedded image objects stored inside the document. Unlike screenshots or page rendering, the extractor retrieves the original image resources whenever possible, preserving their quality and dimensions.

As each page is processed, every discovered image is grouped according to the page where it originally appeared. This organization makes it much easier to browse the extracted results later.

Depending on the size of the PDF and the number of embedded images, extraction may take a few seconds for larger documents.

Step 4: Review the Extracted Images

After extraction is complete, the browser displays every recovered image inside an organized gallery.

Instead of showing one large collection of images, the application groups the results page by page. This allows users to understand exactly where each image came from within the original document.

Every image card displays a preview together with useful information such as the page number, image dimensions, and image format. This helps users quickly identify the graphics they need before downloading anything.

For example, a brochure may contain company logos, banners, icons, and product photographs spread across several pages. Grouping images by page makes navigating these documents much easier.

Step 5: Download Individual Images or Pagewise

Each extracted image includes its own Download Image button.

This feature is useful when users only need one or two graphics from a large document. Instead of downloading every extracted image, they can save only the specific illustrations, charts, product photographs, or logos that are relevant to their work.

For example, a designer may only need a company logo, while a marketing team may only want product images from a supplier catalog. Individual downloads eliminate unnecessary files and simplify the workflow.

After clicking the download button, the browser immediately saves the selected image without requiring any additional processing.

Step 6: Download Every Image

For users who need all graphics contained inside the document, the application also provides a Download All Images from PDF button.

After extraction has finished, clicking this button automatically downloads every recovered image from every page. This saves considerable time compared to downloading each image individually.

This feature is particularly useful when processing large product catalogs, marketing brochures, presentation decks, educational books, technical manuals, magazines, supplier catalogs, or company reports containing dozens of embedded images.

Once the downloads are complete, users can click Start Over to clear the current session and upload another PDF without refreshing the page.

Step 7: Start a New Extraction

After downloading the required images, users can begin working with another PDF document.

Clicking Start Over clears the uploaded document, removes every generated preview, resets the extracted image gallery, and restores the application to its initial state.

This allows users to process multiple PDF files during the same session without reloading the browser or reopening the application.

The reset process is completed instantly, making the workflow smooth and efficient when working with many PDF documents throughout the day.

Performance Optimization Tips

Image extraction is generally faster than OCR because the application recovers existing image objects instead of recognizing characters. But large PDF documents containing hundreds of pages or high-resolution graphics can still require significant processing time.

One simple optimization is to process pages sequentially instead of attempting to analyze every page simultaneously.

for(

let page = 1;

page <= pdf.numPages;

page++

){

    await extractPageImages(page);

}

Loading only the required page into memory reduces browser memory usage and improves stability when processing large documents.

If the application supports page selection, allowing users to extract images from only specific pages can greatly reduce processing time for large catalogs or reports.

const startPage = 10;

const endPage = 25;

After images have been downloaded, release any temporary browser resources:

URL.revokeObjectURL(

imageURL

);

Finally, clear the extracted image collection before processing another PDF:

extractedImages.length = 0;

These small optimizations help the application remain responsive even when working with documents containing hundreds of embedded graphics.

Important Notes from Real-World Use

Not every PDF contains embedded images.

Some documents consist entirely of text and vector graphics, while others may contain scanned pages that appear as a single full-page image. Understanding how the original PDF was created helps set realistic expectations before extraction begins.

Always validate uploaded files before processing.

if(

file.type !== "application/pdf"

){

    alert(

    "Please upload a valid PDF."

    );

}

Some PDF creators compress embedded images heavily to reduce file size. In those situations, the extracted images will match the quality stored inside the PDF, but they can't be improved beyond the original resolution.

Users should also verify extraction results before downloading every image, particularly when processing large reports or catalogs containing hundreds of graphics.

Because the application performs all operations locally inside the browser, confidential documents remain private throughout the extraction process. This makes browser-based image extraction suitable for business reports, engineering drawings, financial documents, legal records, educational resources, and other sensitive PDFs.

Common Mistakes to Avoid

One common mistake is assuming every visible object inside a PDF is an extractable image.

Many diagrams, logos, and charts are actually vector graphics rather than raster images. These elements are rendered by drawing commands and can't always be extracted as standalone image files.

Another mistake is relying on screenshots instead of extracting embedded images.

Screenshots capture only the rendered page displayed on the screen, which often reduces image quality and includes unnecessary page elements.

Always verify that embedded images have been detected before displaying the results.

if(

extractedImages.length === 0

){

    alert(

    "No embedded images found."

    );

}

Some users also forget to organize extracted images by page.

Grouping images according to their original page location makes it much easier to navigate large documents containing dozens or hundreds of graphics.

Finally, always review the extracted images before downloading them.

Checking the preview allows users to confirm image quality, dimensions, and page location before saving the files.

Conclusion

In this tutorial, you built a browser-based PDF Image Extractor using JavaScript.

You learned how to upload PDF files, preview document pages, locate embedded image objects, extract images while preserving their original quality, organize results page by page, download individual images, and download every extracted image directly from the browser.

More importantly, you learned the difference between embedded images and rendered page previews, giving you a better understanding of how PDF documents are structured internally.

Because the entire workflow runs locally inside the browser, users can safely recover graphics from confidential PDF documents without uploading them to external servers.

You can try the complete implementation here:

PDF Image Extractor: https://allinonetools.net/extract-images-from-pdf/

Once you understand this workflow, you can extend the project further by adding duplicate image detection, automatic image compression, AI-powered image tagging, background removal, image format conversion, OCR on extracted images, watermark detection, or bulk asset management features.

Four months later, a four-agent LangChain loop ran for eleven days and cost 47,000 USD. Nobody noticed until the invoice arrived. The pipeline worked correctly in testing, and the agents were doing exactly what they were told. Same pattern.

This tutorial is about that missing instruction.

You'll build five small Python primitives that catch most agent loop failures before they ship:

• A spec writer that forces you to define done before the loop starts

• A circuit breaker that kills the loop when it exceeds hard limits

• A ledger that records every turn in an append-only SQLite audit trail

• An agent loop that ties all three together

• A review surface that forces human attestation before downstream systems receive anything

By the end you'll have a working repo you can drop into any agent project. The full code is at github.com/dannwaneri/production-safe-agent-loop.

Table of Contents

1. Why This Keeps Happening

2. Prerequisites

3. Phase 1: Define Done Before You Build

4. Phase 2: Enforce Done at Runtime

5. Phase 3: Record Everything

6. Phase 4: The Loop That Respects Its Boundaries

7. Phase 5: The Review Surface

8. Phase 6: A Real Example, SEO Audit Agent

9. Pluggable LLM Client

10. Running the Tests

11. What You've Built

12. Next Steps

Why This Keeps Happening

The math that got companies into trouble was simple. A chatbot costs roughly 0.04 USD per interaction. An orchestrated multi-agent workflow costs 1.20 USD. That's a 30x multiplier — and production benchmarks show it can reach 70x on complex tasks.

The problem isn't that agents are expensive. The problem is that most teams budgeted for chatbot costs and deployed agent architectures. Gartner found the token consumption gap between pilot chatbots and production agent workflows sits at 5-30x. The FinOps Foundation's 2026 State of FinOps report found 73% of enterprises say AI costs exceeded original projections.

The mechanism is straightforward once you see it. When an agent fails a task and retries, it doesn't start fresh. It re-reads the entire context window — every prior failed attempt — before trying again. Iteration one costs 100 tokens. Iteration two costs 200. Iteration ten costs thousands. You're paying for every failure, over and over, in milliseconds.

# This is the entire problem in three lines
while True:
    result = agent.run(task)
    # done when...?

That question mark is where the money goes.

The other thing making it worse: agents don't fail loudly. Traditional code hits an undefined state and crashes. An LLM hits ambiguity and tries to be helpful. It retries. It reformats the tool call. It spins up a verification agent. The verification agent finds something. A correction agent fires. Nobody defined what "correct" means. The loop looks beautiful on every dashboard you have — activity, tool calls, completion rate — while quietly burning through your budget.

Gartner predicts that 40% of agentic projects will be scrapped by 2027 due to economic failure. Most of that failure is preventable. Not with better models, but with exit conditions.

Prerequisites

• Python 3.10+

• An Anthropic API key (or any provider — more on that later)

• Basic familiarity with Python classes and SQLite

git clone https://github.com/dannwaneri/production-safe-agent-loop
cd production-safe-agent-loop
pip install -r requirements.txt
export ANTHROPIC_API_KEY=sk-...

Phase 1: Define Done Before You Build

The most expensive mistake in agent development isn't a bad model choice or a missing retry limit. It's starting the build before you can answer one question in one sentence:

What does done look like?

Most teams can't answer it. Not because they're careless, but because nothing forces them to before they open the terminal. The spec writer is that forcing function.

# spec_writer.py
from spec_writer import SpecWriter

spec = SpecWriter(db_path="spec.db").run()

When you call .run(), it won't return until you've answered three questions:

1. What does this do?

2. What does this NOT do?

3. What does done look like in one sentence?

The third question is the one that matters. It's also the hardest. "The agent audits the site" is not an answer. "The agent crawls the target URL, extracts all <title> and <meta description> tags, flags any missing or over-length, and stops" is an answer. One of those gives the circuit breaker something to enforce.

The spec stores to SQLite and returns a SpecResult dataclass with a session_id. That ID becomes the thread connecting your spec, your ledger rows, and your loop result. One session, traceable end to end.

@dataclass(frozen=True)
class SpecResult:
    what_it_does: str
    what_it_does_not: str
    done_looks_like: str
    session_id: str

frozen=True matters. The spec is a commitment, not a draft. Once it's written, the loop runs against it. No mid-run revisions.

For testing, SpecWriter accepts injectable input_fn and output_fn callables. No stdin monkey-patching required. See tests/test_spec_writer.py for working examples — the suite uses a small scripted_input helper that returns answers from a generator, and writes to a per-test SQLite file via pytest's tmp_path fixture. SQLite's :memory: isn't safe here, because SpecWriter opens a fresh connection per method and each :memory: connection is its own isolated database.

Phase 2: Enforce Done at Runtime

Defining the exit condition upstream is discipline. The circuit breaker is enforcement.

# circuit_breaker.py
from circuit_breaker import CircuitBreaker, CircuitBreakerError

breaker = CircuitBreaker(turn_limit=5, token_limit=15000)
breaker.check(turn_count, accumulated_tokens)  # raises on breach

Two ceilings. Both hard.

turn_limit caps how many times the loop can call the LLM. token_limit caps total token consumption across all turns. Either one tripping raises CircuitBreakerError immediately.

The boundary is strict: turn_count == turn_limit is allowed. turn_count == turn_limit + 1 trips. No grace periods or warnings. A hard stop forces a human checkpoint.

from dataclasses import dataclass


@dataclass
class CircuitBreakerError(Exception):
    reason: str          # "turn_ceiling" or "token_ceiling"
    turn_count: int
    accumulated_tokens: int

    def __post_init__(self) -> None:
        super().__init__(
            f"circuit breaker tripped: {self.reason} "
            f"(turn={self.turn_count}, tokens={self.accumulated_tokens})"
        )


class CircuitBreaker:
    def __init__(self, turn_limit: int = 5, token_limit: int = 15000) -> None:
        self.turn_limit = turn_limit
        self.token_limit = token_limit

    def check(self, turn_count: int, accumulated_tokens: int) -> None:
        if turn_count > self.turn_limit:
            self._trip("turn_ceiling", turn_count, accumulated_tokens)
        if accumulated_tokens > self.token_limit:
            self._trip("token_ceiling", turn_count, accumulated_tokens)

    def _trip(self, reason: str, turn_count: int, accumulated_tokens: int) -> None:
        print(
            "\n=== CIRCUIT BREAKER CHECKPOINT ===\n"
            f"reason         : {reason}\n"
            f"turn_count     : {turn_count} / limit {self.turn_limit}\n"
            f"tokens_used    : {accumulated_tokens} / limit {self.token_limit}\n"
            "action         : halt loop, surface to human reviewer\n"
            "=================================="
        )
        raise CircuitBreakerError(
            reason=reason,
            turn_count=turn_count,
            accumulated_tokens=accumulated_tokens,
        )

CircuitBreakerError is an exception, not a return code. That's intentional. A return code can be ignored. An uncaught exception can't. Silent breach is impossible. The human-readable checkpoint banner is printed to stdout by _trip() before the exception is raised, so even if a caller swallows the exception the operator still sees state.

The critical rule: call .check() before every LLM call, not after. Post-flight checking means you've already burned the tokens before you knew the limit was exceeded.

# Wrong — post-flight
result = client.messages.create(...)
breaker.check(turn_count, accumulated_tokens)  # too late

# Right — pre-flight
breaker.check(turn_count, accumulated_tokens)  # raises before any spend
result = client.messages.create(...)

The defaults (5 turns, 15,000 tokens) match a tight tutorial demo. Your production budget is different. Tune at instantiation:

# Production example — tighter token budget, more turns
breaker = CircuitBreaker(turn_limit=10, token_limit=50000)

Phase 3: Record Everything

The circuit breaker protects your bank account. The ledger protects your understanding of what happened.

Most teams log for debugging — they want to know what went wrong after it went wrong. The ledger has a different purpose. It's governance. Every row is proof that the loop stayed within its boundaries, or didn't, and exactly when.

# ledger.py
from ledger import Ledger

ledger = Ledger(db_path="ledger.db")
ledger.write(
    session_id=spec.session_id,
    turn_count=1,
    state_origin="llm",
    input_str=task,
    token_delta=523,
    execution_time_ms=1240,
    pass_fail=True,
)

One row per turn. Append-only, no updates, and no deletes. The immutability is the point: a ledger you can edit isn't a ledger, it's a notebook.

The schema:

CREATE TABLE IF NOT EXISTS ledger (
    id                 INTEGER PRIMARY KEY AUTOINCREMENT,
    session_id         TEXT    NOT NULL,
    turn_count         INTEGER NOT NULL,
    state_origin       TEXT    NOT NULL,
    input_hash         TEXT    NOT NULL,
    token_delta        INTEGER NOT NULL,
    execution_time_ms  INTEGER NOT NULL,
    pass_fail          INTEGER NOT NULL,  -- 1=pass, 0=fail
    breach_reason      TEXT,              -- NULL unless circuit breaker fired
    created_at         TEXT    NOT NULL   -- ISO 8601, UTC
);
CREATE INDEX IF NOT EXISTS idx_ledger_session ON ledger(session_id);

The index makes get_session(session_id) — the primary read path — a constant-time lookup as the ledger grows.

Three decisions worth explaining:

1. input_hash not input_text. The raw input string never persists. Only its SHA-256 hash does. There are two benefits to this: identical inputs across runs are detectable, and PII never enters the audit trail.

2. pass_fail as INTEGER not BOOLEAN. SQLite has no boolean type. 1 and 0 are canonical. Clean Python ergonomics at the API edge, correct SQL types on disk.

3. created_at as datetime.now(timezone.utc).isoformat(). datetime.utcnow() was deprecated in Python 3.12. Timezone-aware timestamps avoid the footgun in any system that crosses timezones.

Retrieve by session:

rows = ledger.get_session(spec.session_id)
for row in rows:
    print(f"Turn {row.turn_count}: {'PASS' if row.pass_fail else 'FAIL'} "
          f"| {row.token_delta} tokens | {row.execution_time_ms}ms")

Phase 4: The Loop That Respects Its Boundaries

The agent loop wires the three primitives together. It's the only component that calls the LLM. Everything else is local.

# agent_loop.py
from agent_loop import AgentLoop

loop = AgentLoop(spec, breaker, ledger, client)
result = loop.run(task)
# LoopResult(success, turns, total_tokens, session_id, breach_reason)

The anatomy of a turn, in order:

1. circuit_breaker.check(turn_count, accumulated_tokens) — raises if either ceiling is exceeded

2. client.messages.create(...) — the actual LLM call

3. ledger.write(...) — one row, append-only

4. If stop_reason == "end_turn", return. Otherwise loop.

Pre-flight checking before every LLM call, with no exceptions.

def run(self, task: str) -> LoopResult:
    session_id = self.spec.session_id
    messages: list[dict] = [{"role": "user", "content": task}]
    turn = 0
    total_tokens = 0

    try:
        while True:
            turn += 1
            self.circuit_breaker.check(turn, total_tokens)

            started = time.perf_counter()
            response = self.client.messages.create(
                model=self.model,
                max_tokens=self.max_tokens,
                system=self._system_prompt(),
                messages=messages,
            )
            elapsed_ms = int((time.perf_counter() - started) * 1000)

            turn_tokens = (
                getattr(response.usage, "input_tokens", 0)
                + getattr(response.usage, "output_tokens", 0)
            )
            total_tokens += turn_tokens

            text = self._text_from(response)
            messages.append({"role": "assistant", "content": text})

            self.ledger.write(
                session_id=session_id,
                turn_count=turn,
                state_origin="llm",
                input_str=task,
                token_delta=turn_tokens,
                execution_time_ms=elapsed_ms,
                pass_fail=True,
            )

            if getattr(response, "stop_reason", "end_turn") == "end_turn":
                return LoopResult(
                    success=True,
                    turns=turn,
                    total_tokens=total_tokens,
                    session_id=session_id,
                )

            messages.append({"role": "user", "content": "continue"})

    except CircuitBreakerError as err:
        self.ledger.write(
            session_id=session_id,
            turn_count=turn,
            state_origin="circuit_breaker",
            input_str=task,
            token_delta=0,
            execution_time_ms=0,
            pass_fail=False,
            breach_reason=err.reason,
        )
        return LoopResult(
            success=False,
            turns=turn,
            total_tokens=total_tokens,
            session_id=session_id,
            breach_reason=err.reason,
        )

def _system_prompt(self) -> str:
    return (
        "You are an agent working on a tightly-scoped task.\n\n"
        f"What this does: {self.spec.what_it_does}\n"
        f"What this does NOT do: {self.spec.what_it_does_not}\n"
        f"Done looks like: {self.spec.done_looks_like}\n"
    )

@staticmethod
def _text_from(response) -> str:
    content = getattr(response, "content", None)
    if not content:
        return ""
    block = content[0]
    return getattr(block, "text", "") or ""

A few choices worth calling out in this body:

• The whole while True: is wrapped in one try/except CircuitBreakerError. The check happens at the top of every turn, so a breach is caught the same way whether it fires on turn 1 or turn 6.

• input_str=task on every ledger row — the original task, not the last assistant message. The input_hash column then groups rows that share the same starting input across the run.

• pass_fail=True for every LLM turn that returns, False only on breach. The pass/fail flag tracks whether the loop reached the row legitimately, not whether the model's output was good. Quality scoring is a separate concern.

• _system_prompt() uses all three spec fields, not just done_looks_like. The model needs the negative scope (what_it_does_not) at least as much as the positive scope.

• time.perf_counter() not time.time() — monotonic, immune to wall-clock adjustments mid-run.

LoopResult.session_id is inherited from spec.session_id. The ledger rows tie back to the spec without a join. One session ID, one traceable run, start to finish.

Phase 5: The Review Surface

The circuit breaker protects your bank account. The ledger records what happened. But neither tells you whether what happened matched what you promised.

That gap is where bad loops get approved. Polished output, green dashboard, missed commitment. A reviewer sees the artifact, decides it looks acceptable, and signs off. Nobody asked whether the original promise was kept.

The review surface closes that gap. It reads the session from SQLite, assembles the five-element frame, and forces a comparison before anything downstream receives the output.

from review_surface import ReviewSurface

rs = ReviewSurface(spec_db_path="spec.db", ledger_db_path="ledger.db")
print(rs.render(session_id))

Here's the five-element frame, in order:

1. Original promise — pulled from the spec table: what it does, what it doesn't do, what done looks like

2. Acceptance criteria — the done_looks_like field rendered as the explicit benchmark

3. Diff — first turn input vs final turn output, turns completed, total tokens, whether the loop breached

4. Evidence — all ledger rows for the session: turn-by-turn pass/fail, token delta, execution time

5. Unresolved assumptions — derived from breach rows and failed turns. Empty when clean.

When the reviewer is satisfied, they attest:

attestation = rs.attest(
    session_id=result.session_id,
    reviewer="daniel",
    notes="Output matches spec. Approved."
)
print(attestation.frame_hash)

.attest() writes to the attestations table in ledger.db. The frame_hash is a SHA-256 of the canonical frame data — deterministic across reviewers attesting the same session. It's the audit receipt. It proves the reviewer saw the exact frame as rendered, not a summary or a paraphrase.

Approval confirms the process ran. Attestation confirms the reviewer compared output to commitment. When the loop touches something regulated, those are different legal documents.

@dataclass(frozen=True)
class ReviewFrame:
    session_id: str
    original_promise: SpecResult
    acceptance_criteria: str
    diff: DiffResult
    evidence: tuple  # tuple[LedgerRow, ...]
    unresolved_assumptions: tuple  # tuple[str, ...]
    created_at: str

ReviewFrame is frozen for the same reason SpecResult is — the frame is evidence, not a draft. evidence and unresolved_assumptions are tuples because lists aren't hashable and frozen dataclasses need hashable fields.

The full end-to-end flow with the review surface lives in examples/review_example.py in the repo. Run it after any completed session: it renders the five-element frame, prompts for attestation, and writes the receipt if you approve.

The loop runs to you. Downstream systems get nothing until someone signs.

Phase 6: A Real Example — SEO Audit Agent

The pattern only makes sense against a real problem. This is the same agent architecture behind my seo-agent project.

SEO audits have a natural cadence: crawl, surface what's broken, fix, wait for reindex. Running the agent continuously doesn't change that cadence. It just burns tokens in the empty space between the moments that matter. A cron job wired to the loop is the honest architecture.

# examples/seo_audit_example.py
import requests
from bs4 import BeautifulSoup
import anthropic
from spec_writer import SpecWriter
from circuit_breaker import CircuitBreaker
from ledger import Ledger
from agent_loop import AgentLoop

def crawl_url(url: str) -> str:
    response = requests.get(url, timeout=10)
    soup = BeautifulSoup(response.text, "html.parser")
    title = soup.find("title")
    meta_desc = soup.find("meta", attrs={"name": "description"})
    h1_tags = soup.find_all("h1")
    return (
        f"URL: {url}\n"
        f"Title: {title.text if title else 'MISSING'}\n"
        f"Meta description: "
        f"{meta_desc['content'] if meta_desc else 'MISSING'}\n"
        f"H1 count: {len(h1_tags)}\n"
        f"H1 tags: {[h.text[:50] for h in h1_tags]}"
    )

def run_seo_audit(url: str) -> None:
    # Step 1: Define done before the loop starts
    spec = SpecWriter(db_path="spec.db").run()

    # Step 2: Initialise circuit breaker and ledger
    breaker = CircuitBreaker(turn_limit=5, token_limit=15000)
    ledger = Ledger(db_path="ledger.db")
    client = anthropic.Anthropic()

    # Step 3: Crawl the URL
    site_data = crawl_url(url)

    # Step 4: Run the loop
    # AgentLoop catches CircuitBreakerError internally and returns
    # LoopResult(success=False, breach_reason=...). Branch on the
    # result — do NOT wrap loop.run() in try/except CircuitBreakerError.
    loop = AgentLoop(spec, breaker, ledger, client)
    result = loop.run(
        f"Audit this page for SEO issues:\n\n{site_data}"
    )

    # Step 5: Print the ledger
    print(f"\nResult: {'SUCCESS' if result.success else 'BREACH'}")
    if not result.success:
        print(f"Breach reason: {result.breach_reason}")
    print(f"Turns: {result.turns} | Tokens: {result.total_tokens}")
    print("\nAudit trail:")
    for row in ledger.get_session(result.session_id):
        status = "PASS" if row.pass_fail else "FAIL"
        print(f"  Turn {row.turn_count}: {status} | "
              f"{row.token_delta} tokens | {row.execution_time_ms}ms")

if __name__ == "__main__":
    import sys
    run_seo_audit(sys.argv[1] if len(sys.argv) > 1 else "https://example.com")

Run it:

python examples/seo_audit_example.py https://yourdomain.com

The spec writer prompts you. The loop runs, the circuit breaker fires if the limits are exceeded, and the ledger records every turn. The output lands in front of you and you decide what to fix.

The loop runs to you, not into a void.

Pluggable LLM Client

The loop works with any client that satisfies the LLMClient protocol (Anthropic by default). Bring your own via a ~20-line adapter.

# agent_loop.py
from typing import Protocol, runtime_checkable


@runtime_checkable
class MessagesEndpoint(Protocol):
    def create(self, *, model: str, max_tokens: int,
               system: str, messages: list) -> object: ...


@runtime_checkable
class LLMClient(Protocol):
    messages: MessagesEndpoint

messages is an instance attribute (not a nested class) because that's how the real Anthropic SDK exposes it — anthropic.Anthropic().messages.create(...). Modeling it as a nested class would mean the real client wouldn't satisfy the Protocol. The @runtime_checkable decorator lets you sanity-check conformance with isinstance(client, LLMClient), and the repo's test suite uses exactly that assertion against the FakeClient test double.

Here's an OpenAI adapter example (This is illustrative. A production adapter would also map streaming, tool-use, and error shapes.):

# openai_adapter.py — illustrative pseudocode, not production-ready.
from openai import OpenAI as _OpenAI


class _MessagesAdapter:
    def __init__(self, client):
        self._client = client

    def create(self, *, model, max_tokens, system, messages):
        completion = self._client.chat.completions.create(
            model=model,
            max_tokens=max_tokens,
            messages=[{"role": "system", "content": system}] + messages,
        )
        # Reshape OpenAI's response into the Anthropic-shaped surface
        # AgentLoop reads: response.usage.{input,output}_tokens,
        # response.content[0].text, response.stop_reason.
        return _adapt_response(completion)


class OpenAIAdapter:
    def __init__(self, api_key: str):
        self._client = _OpenAI(api_key=api_key)
        self.messages = _MessagesAdapter(self._client)  # instance attr, not a nested class

The adapter pattern is worth teaching explicitly. Provider APIs don't share a shape. Anthropic puts system at the top level. OpenAI puts it inside the messages array. An adapter shim is ~20 lines and makes the loop provider-agnostic without rewriting anything. Note that self.messages is assigned in __init__ so it's a real attribute on each adapter instance, the same shape as the actual SDK.

Running the Tests

python -m pytest tests/

With coverage:

python -m coverage run --source=circuit_breaker,ledger,spec_writer,agent_loop,review_surface -m pytest tests/
python -m coverage report -m

80 tests, 100% coverage on all five core modules. The loop is exercised against a FakeClient test double defined inline in tests/test_agent_loop.py. It satisfies the LLMClient protocol via duck typing: messages is set to self, so client.messages.create(...) routes back to the same object and ships with scripted responses for each test scenario. Clone the repo and run pytest to see all 80 tests pass without touching the network or needing an API key.

circuit_breaker.py has 100% coverage — no untested paths. It's the financial safety component. Every path through it is exercised.

What You've Built

In this tutorial, you've build five small primitives, each independently usable.

The pattern: upstream discipline defines the boundaries. Downstream enforcement breaks the circuit. Neither trusts the model to police itself.

A loop that runs without an exit condition isn't autonomous. It's a billing event waiting to happen.

Define what done looks like before you start. That's the job, and always has been.

Next Steps

The repo is at github.com/dannwaneri/production-safe-agent-loop.

There are three natural extensions if you want to go further:

1. Graduation to Distributed Systems

The SQLite ledger works for isolated sequential loops. The moment you run multiple agents against shared state, you need serializable isolation — concurrent writes to flat JSON corrupt silently. The README documents the three tipping points where a flat ledger needs to graduate.

2. Cryptographic Signing

For compliance-scale systems where the auditor wasn't present when the loop ran, SQLite rows aren't enough. A database admin can run an UPDATE query. Ed25519 signing wraps each ledger row in a receipt that proves the log wasn't altered after execution. But that's a different tutorial.

Wiring a Cron Job

The honest architecture for the SEO audit agent isn't 24/7 autonomous operation. It's a cron job that runs on schedule, surfaces what's broken, and stops. 0 3 * * 2 python examples/seo_audit_example.py https://yourdomain.com is the whole thing. The loop runs to you, not into a void.

If you need this architecture built for your own stack (circuit breakers, audit trails, production-safe agent loops), I do freelance work. dannwaneri.com/ai-agents/

Instead of manually editing every page, modern JavaScript libraries let you add page numbers directly inside the browser.

In this tutorial, you'll build a browser-based PDF page numbering tool using JavaScript.

Users will be able to upload a PDF, choose where page numbers appear, customize formatting options, preview the document, and download the updated PDF without uploading files to a server.

Everything runs locally inside the browser for better privacy and faster processing.

Table of Contents

1. How PDF Page Numbering Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading PDF Pages

6. Previewing Uploaded Pages

7. Selecting Page Number Position

8. Choosing Pages to Number

9. Configuring Number Format and Style

10. Generating the Updated PDF

11. Previewing and Downloading the Final PDF

12. How PDF Page Numbers Help in Real-World Documents

13. Demo: How the PDF Page Number Tool Works

14. Important Notes from Real-World Use

15. Common Mistakes to Avoid

16. Conclusion

How PDF Page Numbering Works

A PDF page numbering tool loads an existing PDF document, modifies selected pages, and inserts page numbers before generating a new downloadable file.

Page numbering is commonly used in reports, contracts, invoices, legal documents, eBooks, manuals, and academic papers where readers need an easy way to navigate through multiple pages.

Without page numbers, it can be difficult to reference specific sections or locate information inside larger documents.

The browser reads the uploaded PDF, processes each page, applies numbering rules, and exports the updated document.

Everything happens locally inside the browser.

This means documents never leave the user's device, improving privacy and security.

In this tutorial, we'll build a tool that allows users to upload a PDF, choose where page numbers appear, customize formatting options, preview the result, and download the updated document directly from the browser.

Project Setup

This project is intentionally simple.

You only need an HTML file, a JavaScript file, and a PDF processing library.

No backend server or database is required.

What Library Are We Using?

We'll use PDF-lib because it allows us to load, modify, and export PDF documents directly inside JavaScript.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib"></script>

Once loaded, we can read PDF pages and add numbering information directly inside the browser.

Creating the Upload Interface

Users first need a way to upload PDF files.

A simple file input works:

<input type="file" id="pdfFile" accept=".pdf">

After selecting a file, JavaScript can process the PDF and display a preview.

Reading PDF Pages

After the file is uploaded, the PDF must be loaded into memory.

For example:

const bytes = await file.arrayBuffer();

const pdfDoc = await PDFLib.PDFDocument.load(bytes);

const pages = pdfDoc.getPages();

This gives us access to every page inside the document.

Previewing Uploaded Pages

Before applying page numbers, users can preview document pages directly inside the browser.

Showing page previews helps users verify the document before making changes.

The preview section updates automatically after the PDF is uploaded.

Selecting Page Number Position

Different documents require different page number placements.

Some users prefer numbers at the bottom center, while others may use corners or top positions.

The tool provides multiple positioning options.

For example:

page.drawText(pageNumber, {
  x: 250,
  y: 20
});

This allows page numbers to be placed at different coordinates.

Choosing Pages to Number

Not every page needs numbering.

Some users may want numbering applied to all pages. Others may choose a custom range or skip the first page.

The tool supports all of these options.

Configuring Number Format and Style

Users can customize how page numbers appear inside the document.

The numbering format can use standard numbers, lowercase letters, or uppercase letters.

For example:

const pageNumber = `${index + 1}`;

Different numbering styles can also be generated dynamically.

Users can also select different fonts.

The tool allows changing text size, color, and appearance.

Users can also customize numbering patterns.

For example:

• Page 1

• Page 1 of 20

• Custom patterns

Margin settings control spacing between the page number and document edges.

Generating the Updated PDF

Once configuration is complete, users can generate the updated document.

For example:

const pdfBytes = await pdfDoc.save();

The browser processes the pages and inserts numbering automatically.

Previewing and Downloading the Final PDF

After processing, the updated PDF is displayed inside a preview area.

Users can review the results before downloading.

The interface also shows document details such as total pages and file size.

Navigation buttons allow users to browse through pages directly inside the browser.

Finally, the completed PDF can be downloaded.

How PDF Page Numbers Help in Real-World Documents

Page numbers may seem like a small detail, but they become extremely important as documents grow larger.

In business reports, page numbers help readers quickly locate specific sections during meetings, reviews, or presentations. Instead of scrolling through dozens of pages, someone can simply jump to the referenced page number.

Contracts and legal documents also rely heavily on page numbering. When discussing terms or clauses, it's common to reference a specific page to avoid confusion and ensure everyone is looking at the same information.

Academic papers, research documents, and project reports often require page numbers for citations, references, and formatting guidelines. Many institutions consider page numbering a standard requirement for professional submissions.

Page numbers are also useful for manuals, ebooks, user guides, and training materials. Readers can easily return to a previous section or follow instructions that reference another page within the document.

For example, a company handbook might contain 50 or more pages. Without page numbers, employees would need to manually search for information. With numbering applied, sections can simply reference pages such as "See page 24 for leave policy details."

Similarly, invoices, proposals, and financial reports often use formats like "Page 3 of 12" so readers immediately understand how many pages are included in the document.

Adding page numbers improves navigation, organization, professionalism, and overall readability, making documents easier to use for both creators and readers.

Demo: How the PDF Page Number Tool Works

Step 1: Upload a PDF

Users upload a PDF document into the browser.

Step 2: Review Page Previews

The uploaded document pages appear inside the preview section.

Step 3: Configure Page Number Settings

Users choose position, page range, numbering style, font appearance, transparency, and formatting options.

Step 4: Generate the PDF

After configuration is complete, users click the generate button.

Step 5: Review and Download

The finished PDF appears in the preview area.

Users can browse pages, review numbering, rename, and download the updated document.

Important Notes from Real-World Use

When working with large PDF files, performance and memory usage become important considerations.

Documents containing hundreds of pages may take longer to process inside the browser.

A simple validation check can help prevent unsupported files from being processed:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file");
  return;
}

This ensures users upload a PDF before processing begins.

Another useful optimization is limiting very large files before loading them:

const MAX_SIZE = 20 * 1024 * 1024;

if (file.size > MAX_SIZE) {
  alert("PDF file is too large");
  return;
}

This prevents excessive memory usage and improves browser performance.

When generating page numbers, it's also helpful to process pages only once:

const pages = pdfDoc.getPages();

pages.forEach((page, index) => {
  page.drawText(`${index + 1}`);
});

This keeps the numbering process efficient even for larger documents.

Before downloading the final file, always preview the generated document.

Reviewing the output helps verify that page numbers appear in the correct position, use the expected format, and don't overlap important document content.

Common Mistakes to Avoid

One common mistake is hardcoding page number positions.

Different PDF documents can have different page sizes, so fixed coordinates may place page numbers in the wrong location.

For example:

page.drawText(pageNumber, {
  x: 250,
  y: 20
});

Instead, it's usually better to calculate positions dynamically based on the page dimensions.

Another mistake is applying numbering to every page when only a subset of pages should be updated.

For example, users may want to skip the cover page or number only specific page ranges.

Always verify page selection settings before generating the final file.

It's also important to preview the output before downloading.

For example:

const previewPage = pdfDoc.getPage(0);

renderPreview(previewPage);

This helps ensure page numbers appear exactly where expected.

Another common issue is failing to validate uploaded files before processing:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file");
  return;
}

Adding basic validation helps prevent errors and improves the overall user experience.

Conclusion

In this tutorial, you built a browser-based PDF page numbering tool using JavaScript.

You learned how to upload PDF files, preview pages, choose numbering positions, customize formatting options, and generate downloadable PDFs directly inside the browser.

More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

If you'd like to try a production-ready version, you can use the AllInOneTools - PDF Page Number Tool.

Once you understand this workflow, you can extend it further with features like headers, footers, watermarks, PDF stamps, document annotations, or advanced page management.

And that's where things start getting really interesting.

Instead of re-creating the document manually, users usually just need a quick way to rotate pages and save the corrected version.

Modern browsers make this possible directly with JavaScript.

In this tutorial, you’ll build a browser-based PDF rotator using JavaScript.

The tool will allow users to upload PDF files, preview pages, rotate selected pages, change orientation, generate an updated PDF, preview the final result, rename the file, and download everything directly from the browser.

Everything works entirely client-side without a backend server.

Table of Contents

1. How PDF Rotation Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Previewing Uploaded PDF Pages

6. Selecting Pages to Rotate

7. Applying Rotation Options

8. Generating the Rotated PDF

9. Previewing and Downloading the Final PDF

10. Why PDF Rotation Is Useful in Real-World Documents

11. Demo: How the PDF Rotator Tool Works

12. Important Notes from Real-World Use

13. Common Mistakes to Avoid

14. Conclusion

How PDF Rotation Works

PDF rotation works by updating the orientation data of PDF pages.

Instead of modifying the actual content manually, JavaScript libraries can rotate pages programmatically and export an updated version of the document.

The browser loads the PDF file, reads page information, applies rotation values like 90°, 180°, or landscape orientation, and then generates a new downloadable PDF.

Everything happens directly inside the browser.

This keeps the process fast, private, and easy to use without uploading files to external servers.

Project Setup

This project is intentionally simple.

You only need an HTML file, a JavaScript file, and a PDF processing library.

Everything runs entirely inside the browser using JavaScript. No backend server or database is required.

What Library Are We Using?

We’ll use the PDF-lib library for editing PDF files directly in the browser.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

This library allows us to:

• load PDF documents

• rotate pages

• modify orientation

• export updated PDFs

Creating the Upload Interface

Start with a basic upload input:

<input type="file" id="pdfUpload" accept="application/pdf">

<button onclick="rotatePDF()">
  Rotate PDF
</button>

This allows users to upload PDF files directly from the browser.

Here’s what the upload section looks like inside the tool:

Previewing Uploaded PDF Pages

After uploading a PDF file, users can preview pages directly inside the browser before applying rotations.

The preview section also includes rotation controls so users can rotate pages individually as needed before generating the final PDF.

To render previews, we first load the uploaded PDF document:

const pdfDoc = await PDFLib.PDFDocument.load(arrayBuffer);

const totalPages = pdfDoc.getPageCount();

Next, we render page previews dynamically:

for (let i = 0; i < totalPages; i++) {
  const page = pdfDoc.getPage(i);

  console.log("Rendering page:", i + 1);
}

Users can then move between pages using left and right navigation buttons.

Rotation buttons can also be attached to each preview card:

rotateLeftBtn.addEventListener("click", () => {
  rotatePage(currentPage, -90);
});

rotateRightBtn.addEventListener("click", () => {
  rotatePage(currentPage, 90);
});

This makes it easier to verify page orientation before generating the updated PDF.

Here’s what the page preview section looks like:

Selecting Pages to Rotate

Not every document needs all pages rotated.

Some users may only want to rotate even-numbered pages, odd-numbered pages, or specific pages within the document.

The tool allows users to select which pages should receive the rotation changes before generating the final PDF.

For example, users can choose the rotation scope like this:

const selectedMode = document.querySelector(
  'input[name="pageMode"]:checked'
).value;

Specific page ranges can also be supported:

const customPages = document
  .getElementById("customPages")
  .value;

This gives users more control over which document pages are modified.

Here’s how the page selection controls look inside the tool:

Applying Rotation Options

Once the pages are selected, users can apply different rotation actions directly inside the browser.

Pages can be rotated left by 90 degrees, rotated right by 90 degrees, flipped by 180 degrees, or converted into portrait or landscape orientation.

Here’s a simple example using PDF-lib:

const page = pdfDoc.getPage(pageIndex);

page.setRotation(
  PDFLib.degrees(90)
);

To rotate pages left:

page.setRotation(
  PDFLib.degrees(-90)
);

You can also apply orientation presets dynamically:

if (orientation === "landscape") {
  page.setRotation(PDFLib.degrees(90));
}

These controls allow users to fix scanned documents and incorrect page layouts directly inside the browser.

Here’s what the rotation controls look like inside the tool:

Generating the Rotated PDF

After the rotation settings are configured, users can generate the updated PDF directly inside the browser.

The tool processes selected pages, applies rotation changes, and exports a new downloadable PDF file instantly.

For example:

const pdfBytes = await pdfDoc.save();

Next, create a downloadable file:

const blob = new Blob(
  [pdfBytes],
  { type: "application/pdf" }
);

const url = URL.createObjectURL(blob);

Finally, trigger the download:

const link = document.createElement("a");

link.href = url;
link.download = "rotated-document.pdf";

link.click();

This entire workflow runs locally inside the browser without requiring a backend server.

Here’s what the generate button looks like inside the tool:

Previewing and Downloading the Final PDF

Once processing is complete, the tool displays a live preview of the rotated document.

Users can review updated pages before downloading the final file.

The interface also shows additional document details such as total pages and file size.

A rename option is available before downloading the generated PDF.

For example, users can rename the file like this:

const fileName = prompt(
  "Enter PDF name:",
  "rotated-document"
);

The preview section also includes left and right navigation controls so users can browse through rotated pages directly inside the browser.

Document details can also be displayed dynamically:

fileSizeElement.textContent =
  formatFileSize(blob.size);

pageCountElement.textContent =
  pdfDoc.getPageCount();

This improves usability and helps users verify the final output before downloading.

Here’s what the final output section looks like:

Why PDF Rotation Is Useful in Real-World Documents

PDF rotation may seem like a small feature, but it solves a very common problem in everyday document handling.

Many scanned documents, mobile scans, invoices, certificates, and office files are saved with incorrect orientation. Some pages appear sideways, upside down, or mixed between portrait and landscape layouts.

Instead of reopening and rescanning those files, users can quickly fix page orientation directly inside the browser.

For example, PDF rotation is commonly used for:

• scanned agreements

• invoices and bills

• government forms

• academic documents

• construction drawings

• landscape reports

• mobile camera scans

This becomes especially useful when working with multi-page PDFs where only certain pages need correction.

Some users may only want to rotate:

• even-numbered pages

• odd-numbered pages

• specific pages

• landscape pages only

That’s why page-based rotation controls are important in modern PDF tools.

Browser-based PDF rotation also improves privacy because uploaded documents stay on the user’s device instead of being sent to external servers.

Demo: How the PDF Rotator Tool Works

Step 1: Upload the PDF

Users first upload a PDF document directly into the browser-based tool.

The upload section supports drag-and-drop along with manual file selection.

Here’s what the upload interface looks like:

Step 2: Preview PDF Pages

After uploading the document, the tool generates page previews automatically.

The preview section also includes a rotation option so users can rotate document pages as per required.

Here’s the preview section inside the tool:

Step 3: Configure Rotation Settings

Users can now choose how the PDF pages should rotate.

The tool supports:

• rotate left

• rotate right

• flip 180 degrees

• portrait orientation

• landscape orientation

Users can also choose whether rotations apply to all pages or just certain pages.

Here’s what the rotation settings panel looks like:

Step 4: Generate the Rotated PDF

Once everything is configured, users click the generate button to apply the rotations.

The browser processes the document locally and creates the updated PDF instantly.

Here’s the generate button inside the tool:

Step 5: Preview the Final Output

After processing is complete, the tool displays the rotated PDF preview directly inside the browser.

Users can navigate page-by-page using the left and right controls to verify the final output.

The interface also shows:

• total pages

• file size

• output filename

Here’s the final preview section:

Step 6: Rename and Download the PDF

Before downloading, users can rename the generated PDF file directly inside the browser.

Once renamed, the updated document can be downloaded instantly.

Here’s the rename and download section:

Important Notes from Real-World Use

When working with scanned PDFs, page orientation issues are very common.

Some documents may contain mixed orientations where certain pages are portrait while others are landscape.

Applying rotation changes page-by-page usually gives better results than rotating the entire document blindly.

Large PDF files can also increase processing time inside the browser.

For example:

if (file.size > 50 * 1024 * 1024) {
  alert("Large PDF files may process slowly.");
}

Another useful optimization is previewing pages before applying permanent changes.

This helps users verify page orientation and reduces mistakes before downloading the updated document.

Since everything runs locally in the browser, uploaded documents never leave the user’s device, which improves privacy and security.

Common Mistakes to Avoid

One common mistake is rotating pages multiple times accidentally.

For example, applying two consecutive 90-degree rotations may result in unexpected orientation changes.

Another issue is ignoring page selection before applying rotations.

Users may accidentally rotate all pages instead of specific sections of the document.

Large scanned PDFs can also slow down rendering and preview generation.

Validating uploaded files before processing helps avoid broken workflows:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

Incorrect preview synchronization is another common issue.

If page previews aren't refreshed after rotation, users may think the rotation failed even though the exported PDF is correct.

Updating previews dynamically after each rotation improves the overall experience.

Conclusion

In this tutorial, you built a browser-based PDF rotator using JavaScript.

You learned how to upload PDF files, preview document pages, rotate selected pages, change page orientation, generate updated PDFs, and download the final document directly inside the browser.

More importantly, you saw how modern browsers can handle practical PDF editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

You can also try the live tool here: AllInOneTools - PDF Rotator Tool.

Once you understand this workflow, you can extend it further with features like PDF page extraction, annotations, document organization, digital signatures, or advanced editing tools.

And that’s where things start getting really interesting.

Whether it’s adding a company logo, a “CONFIDENTIAL” label, or a draft watermark, users often need a quick way to modify PDFs without uploading files to external servers.

Modern browsers make this much easier than before. Instead of sending documents to a backend, we can process PDF files directly inside the browser using JavaScript. This keeps documents private while making the tool fast and easy to use.

In this tutorial, you’ll build a browser-based PDF watermark tool using JavaScript.

The tool will support both text and image watermarks, adjustable opacity, rotation, page selection, positioning controls, and downloadable PDF output directly from the browser.

Everything works entirely client-side without any backend.

Table of Contents

1. How PDF Watermarking Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Adding Text Watermarks

6. Adding Image Watermarks

7. Positioning and Opacity Controls

8. Selecting Pages to Apply

9. Generating and Downloading the Final PDF

10. Demo: How the PDF Watermark Tool Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How PDF Watermarking Works

A PDF watermark is simply additional text or an image layered on top of an existing PDF page.

In the browser, JavaScript libraries can load PDF pages, modify them visually, and export a new downloadable version.

The process starts when the user uploads a PDF file into the tool. JavaScript then reads the document, loads each page, and applies watermark elements like text or logos on top of the existing content. After positioning and opacity settings are applied, the updated PDF is generated and downloaded directly from the browser.

Everything happens locally inside the browser. This means uploaded documents never leave the user’s device, which improves privacy and security.

Project Setup

This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend server is required.

You only need:

• an HTML file

• a JavaScript file

• a PDF processing library

What Library Are We Using?

We’ll use the PDF-lib library for editing existing PDF documents inside the browser.

Add it using a CDN:

<script src="https://unpkg.com/pdf-lib/dist/pdf-lib.min.js"></script>

This library allows us to load PDF files directly in the browser, modify existing pages, insert custom text or image watermarks, and finally export the updated document as a new downloadable PDF.

Because everything runs client-side with JavaScript, users can edit PDFs without uploading files to a server.

How to Create the Upload Interface

Start with a basic upload input:

<input type="file" id="pdfUpload" accept="application/pdf">

<button onclick="addWatermark()">
  Apply Watermark
</button>

This allows users to upload PDF files directly from the browser.

The tool also includes watermark settings like text input, image upload, opacity controls, positioning, and page selection.

Here’s what the watermark settings panel looks like inside the tool:

How to Add Text Watermarks

Text watermarks are commonly used for labels like “CONFIDENTIAL”, “DRAFT”, or “APPROVED”.

For example:

page.drawText("CONFIDENTIAL", {
  x: 200,
  y: 300,
  size: 48,
  opacity: 0.5
});

This inserts watermark text directly onto the PDF page. Users can also customize the appearance of the watermark directly inside the tool.

For text watermarks, users can adjust the font size, change the text color, apply bold or italic styling, control opacity levels, and rotate the watermark at different angles for better visibility and protection.

Here’s an example of text watermark controls inside the tool:

How to Add Image Watermarks

Some users may want to apply logos or branded graphics instead of plain text.

For example:

const image = await pdfDoc.embedPng(imageBytes);

page.drawImage(image, {
  x: 180,
  y: 250,
  width: 120,
  height: 120,
  opacity: 0.5
});

This inserts an image watermark onto the PDF page.

The tool also supports image scaling controls so users can resize uploaded logos before applying them.

Here’s an example of image watermark settings inside the tool:

Positioning and Opacity Controls

Watermark placement is important for readability and document appearance.

Users may want centered watermarks, corner positioning, or diagonal overlays depending on the document type.

For example:

page.drawText("CONFIDENTIAL", {
  x: 220,
  y: 250,
  rotate: degrees(45),
  opacity: 0.5
});

This creates a rotated semi-transparent watermark.

The tool also allows users to adjust watermark positioning and appearance directly inside the browser.

Users can control the X and Y position, change opacity levels, rotate the watermark at different angles, and quickly move the watermark using directional placement controls.

This makes it easier to place watermarks correctly without manually editing the PDF in external software.

Here’s an example of positioning controls inside the tool:

How to Select Pages to Apply

Not every watermark needs to appear on every page. Some users may only want watermarks on specific pages.

For example:

const selectedPages = [1, 3, 5];

The tool allows users to control exactly where the watermark should appear.

For example, a watermark can be applied to every page in the document, only even-numbered pages, only odd-numbered pages, or specific custom page ranges like 1-3,5.

This makes the tool more flexible for real-world use cases such as contracts, invoices, reports, certificates, and branded documents..

Here’s an example of page selection options inside the tool:

How to Generate and Download the Final PDF

Once watermark settings are configured, the browser generates the updated PDF directly inside the browser.

For example:

const pdfBytes = await pdfDoc.save();

Then the updated file becomes downloadable:

download(pdfBytes, "watermarked.pdf");

This process happens locally without uploading files to external servers.

Demo: How the PDF Watermark Tool Works

For this example, we’ll apply a custom watermark directly inside the browser.

Step 1: Upload the PDF

Users upload a PDF document into the watermark tool.

Step 2: Preview the Uploaded PDF

After uploading the PDF, the tool generates a live preview directly inside the browser.

Users can navigate through pages using the left and right arrow buttons to review the document before applying the watermark.

This page-by-page preview helps users verify the correct file, check page content, and decide where the watermark should appear.

Here’s how the PDF preview section looks inside the tool:

Step 3: Configure Watermark Settings

Users can choose between text or image watermark mode.

For text watermarks, users can customize font size, color, opacity, and rotation.

For image watermarks, users can upload a logo and adjust image scale before applying it.

Step 4: Position and Apply the Watermark

Users can reposition the watermark visually before generating the final file.

The tool also allows users to control where the watermark should be applied within the document. For example, the watermark can appear on all pages, only even-numbered pages, only odd-numbered pages, or specific custom page ranges.

Opacity and rotation controls help improve visibility without blocking important document content.

This gives users more flexibility when watermarking contracts, invoices, reports, certificates, or branded PDFs.

Step 5: Generate the Watermarked PDF

Once the watermark settings are configured, users can click the generate button to process the document directly inside the browser.

The tool applies the watermark to the selected pages and prepares the updated PDF instantly.

Here’s how the generate PDF button looks inside the tool:

Step 6: Preview and Download the Updated PDF

After processing is complete, the tool displays a live preview of the final watermarked PDF.

Users can review the updated document before downloading it. The interface also shows useful file details such as total pages and final file size.

A rename option is available before downloading the generated PDF.

Here’s an example of the final output preview section:

Important Notes from Real-World Use

When working with large PDF documents, performance and rendering speed become important.

Applying watermarks page-by-page is usually more stable than modifying everything simultaneously.

For example:

for (const page of pdfDoc.getPages()) {
  // apply watermark
}

Another useful optimization is lowering image watermark size before embedding large logos. This reduces output file size and improves processing speed.

Opacity is also important. Very dark watermarks can make documents difficult to read, especially on printed pages. Keeping watermark opacity between 0.3 and 0.5 usually works well in real-world situations.

Since everything runs locally inside the browser, uploaded documents remain private and never leave the user’s device.

Common Mistakes to Avoid

One common mistake is applying watermarks at full opacity. This can make the document difficult to read.

For example:

opacity: 1

Instead, use lower opacity values:

opacity: 0.4

Another issue is incorrect watermark positioning. If coordinates are hardcoded incorrectly, the watermark may appear outside the visible page area.

Dynamic positioning usually works better across different page sizes. Large image watermarks can also increase PDF file size significantly. Resizing images before embedding them helps improve performance.

Another common mistake is forgetting to validate uploaded files:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

This prevents unsupported files from breaking the tool.

Conclusion

In this tutorial, you built a browser-based PDF watermark tool using JavaScript.

You learned how to upload PDF files, apply text or image watermarks, control positioning and opacity, and generate downloadable PDFs directly inside the browser.

More importantly, you saw how modern browsers can handle document editing tasks locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

You can also try the live tool here: All In One Tools PDF Watermark Tool

Once you understand this workflow, you can extend it further with features like digital signatures, PDF annotations, stamping tools, password protection, or advanced document editing.

And that’s where things start getting really interesting.

Modern browsers make this much easier than before.

Instead of uploading documents to a server, we can process PDF files directly inside the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based PDF to image converter using JavaScript.

The tool will support uploading PDF files, previewing pages, selecting image formats like JPG or PNG, adjusting image quality, and downloading converted images directly from the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How PDF to Image Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading the PDF File

6. Rendering PDF Pages as Images

7. Selecting Image Format and Quality

8. Generating and Downloading Images

9. Demo: How the PDF to Image Tool Works

10. Important Notes from Real-World Use

11. Common Mistakes to Avoid

12. Conclusion

How PDF to Image Conversion Works

A browser can't directly convert PDF files into images on its own.

Instead, JavaScript libraries render PDF pages onto an HTML canvas, which can then be exported as image files like JPG or PNG.

The process starts when users upload a PDF document into the browser. JavaScript then reads the file, renders each PDF page visually onto a canvas, converts those rendered pages into image files, and finally makes them available for download.

Everything happens locally inside the browser.

This means users don't need to upload private documents to external servers, making the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple. Everything runs directly inside the browser using JavaScript, so no backend or server setup is required.

You only need:

• an HTML file

• a JavaScript file

• the PDF.js library

What Library Are We Using?

We’ll use Mozilla’s PDF.js library to render PDF pages inside the browser.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.min.js"></script>

Once loaded, the browser can read and render PDF pages directly using JavaScript.

Creating the Upload Interface

Start with a simple upload area:

<input type="file" id="pdfUpload" accept="application/pdf">

<select id="format">
  <option>JPG</option>
  <option>PNG</option>
  <option>WEBP</option>
</select>

<input type="range" id="quality" min="10" max="100" value="90">

<button onclick="convertPDF()">
  Convert to Images
</button>

This allows users to upload PDF files directly into the browser.

Here’s what the upload section looks like inside the tool:

Reading the PDF File

After the file is uploaded, we need to read it using JavaScript.

For example:

const file = document.getElementById("pdfUpload").files[0];

const reader = new FileReader();

reader.onload = async function () {
  const typedArray = new Uint8Array(reader.result);

  const pdf = await pdfjsLib.getDocument(typedArray).promise;

  console.log(pdf.numPages);
};

reader.readAsArrayBuffer(file);

This loads the PDF document directly inside the browser.

You can then access each page individually.

Rendering PDF Pages as Images

Once the PDF is loaded, pages can be rendered onto a canvas.

For example:

const page = await pdf.getPage(1);

const viewport = page.getViewport({ scale: 2 });

const canvas = document.createElement("canvas");

const context = canvas.getContext("2d");

canvas.width = viewport.width;
canvas.height = viewport.height;

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

This renders the selected PDF page visually inside the browser.

After rendering, the canvas can be converted into an image.

For example:

const imageData = canvas.toDataURL("image/jpeg", 0.9);

This creates a downloadable image version of the PDF page.

Selecting Image Format and Quality

Before generating the final images, users may want to customize output settings.

Different image formats work better for different situations.

For example:

• JPG works well for smaller file sizes

• PNG preserves better quality

• WEBP offers modern compression

Users can also control image quality using a slider.

For example:

canvas.toDataURL("image/jpeg", 0.8);

The value 0.8 controls compression quality.

Here’s an example of image format and quality settings inside the tool:

Generating and Downloading Images

Once pages are rendered, images can be downloaded directly from the browser.

For example:

const link = document.createElement("a");

link.href = imageData;

link.download = `page-${pageNumber}.jpg`;

link.click();

This downloads the generated image instantly.

When working with multi-page PDFs, the same process can run for every page automatically.

This allows users to export complete PDF documents as separate image files.

Demo: How the PDF to Image Tool Works

For this example, we’ll convert PDF pages into downloadable image files directly inside the browser.

Step 1: Upload PDF Files

Users upload one or more PDF files into the converter.

Step 2: Preview Uploaded Pages

The tool generates page previews before conversion.

This helps users verify the uploaded document visually.

Step 3: Configure Output Settings

Users can choose image format and quality settings before generating images.

This allows better control over output size and image clarity.

Step 4: Convert PDF Pages into Images

Once settings are configured, users click the convert button.

The browser processes the PDF locally and generates image files instantly.

Step 5: Download Generated Images

After conversion, every PDF page becomes a downloadable image.

Important Notes from Real-World Use

When working with large PDFs, performance and memory usage become important.

Documents with many pages can slow down rendering if everything is processed at once.

One practical optimization is processing pages step-by-step instead of rendering the entire document immediately.

For example:

for (let i = 1; i <= pdf.numPages; i++) {
  const page = await pdf.getPage(i);

  // render page
}

This keeps browser memory usage more stable.

Another useful optimization is reducing render scale for large documents.

For example:

const viewport = page.getViewport({
  scale: 1.5
});

Lower scale values generate smaller image files and improve performance.

You can also resize generated images before export.

For example:

canvas.width = viewport.width;
canvas.height = viewport.height;

This helps reduce unnecessary file size growth.

Since everything runs locally inside the browser, uploaded PDF files never leave the user’s device, which improves privacy and security.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example:

if (!file || file.type !== "application/pdf") {
  alert("Please upload a valid PDF file.");
  return;
}

This prevents unsupported files from breaking the tool.

Another issue is rendering extremely large pages at very high scale values.

Large canvas rendering can consume a lot of memory and slow down conversion significantly.

Using smaller scale values usually improves performance.

Another common mistake is forgetting to wait for page rendering before exporting the image.

For example:

await page.render({
  canvasContext: context,
  viewport: viewport
}).promise;

Without await, the image may export before rendering finishes.

Incorrect file naming can also confuse users when multiple pages are generated.

Adding page numbers to filenames improves organization:

link.download = `page-${pageNumber}.jpg`;

Conclusion

In this tutorial, you built a browser-based PDF to image converter using JavaScript.

You learned how to upload PDF files, render pages inside the browser, generate images, and download them directly without using a backend server.

More importantly, you saw how modern browsers can handle document processing tasks locally while keeping user files private.

This approach keeps the tool fast, lightweight, and easy to use.

Once you understand this workflow, you can extend it further with features like ZIP downloads, batch exports, page selection, watermarking, or image compression.

You can also try a real working version here:

https://allinonetools.net/pdf-to-image-converter/

And that’s where things start getting really interesting.

Modern browsers make this much easier than before.

Instead of uploading files to a server, we can now process images directly in the browser using JavaScript. This keeps the tool fast, private, and easy to use.

In this tutorial, you’ll build a browser-based Image to PDF converter using JavaScript.

The tool will support uploading multiple images, sorting files, choosing orientation and page size, configuring margins, and merging images into either a single PDF or separate PDF files. Users will also be able to preview and download the generated document directly in the browser.

Everything runs entirely client-side without any backend.

Table of Contents

1. How Image to PDF Conversion Works

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Reading Uploaded Images

6. Generating the PDF

7. Handling Multiple Images

8. Configuring PDF Settings

9. Renaming and Downloading the PDF

10. Demo: How the Image to PDF Tool Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How Image to PDF Conversion Works

The browser can't directly combine images into a PDF by itself.

Instead, we'll use a JavaScript PDF library that creates pages, inserts images, and exports everything as a downloadable PDF document.

The process starts when users upload one or multiple images into the browser. JavaScript then reads the image data and prepares it for PDF generation. After that, the tool creates PDF pages, inserts the uploaded images into those pages, and finally exports everything as a downloadable PDF document.

Everything happens locally inside the browser.

This means users don’t need to upload private files to a server, which makes the process faster and more privacy-friendly.

Project Setup

This project is intentionally simple.

You only need:

• an HTML file

• a JavaScript file

• a PDF library

No backend or database is required.

What Library Are We Using?

We’ll use the jsPDF library. It allows us to generate PDF files directly in JavaScript.

Add it using a CDN:

<script src="https://cdnjs.cloudflare.com/ajax/libs/jspdf/2.5.1/jspdf.umd.min.js"></script>

Once loaded, we can create and export PDF files directly from the browser.

Creating the Upload Interface

Start with a basic upload area:

<input type="file" id="upload" multiple accept="image/*">

<button onclick="convertToPDF()">
  Convert to PDF
</button>

This allows users to upload multiple image files and generate the PDF.

Here’s what the upload section looks like inside the tool:

You can also expand the interface with additional controls for sorting, page settings, margins, and merge modes.

Reading Uploaded Images

After users select files, we need to read them in JavaScript.

We can use FileReader for this:

const fileInput = document.getElementById("upload");

const files = fileInput.files;

for (const file of files) {
  const reader = new FileReader();

  reader.onload = function (e) {
    const imageData = e.target.result;

    console.log(imageData);
  };

  reader.readAsDataURL(file);
}

This converts uploaded images into readable Base64 data that can later be inserted into the PDF.

Generating the PDF

Now we can create the PDF document.

const { jsPDF } = window.jspdf;

const pdf = new jsPDF();

Once the PDF is created, images can be inserted into pages:

pdf.addImage(imageData, "JPEG", 10, 10, 180, 120);

This inserts the uploaded image into the PDF page at a specific position and size.

Finally, export the document:

pdf.save("images.pdf");

This downloads the generated PDF instantly.

Handling Multiple Images

If users upload multiple files, each image can be added to its own PDF page automatically.

For example:

files.forEach((file, index) => {

  if (index !== 0) {
    pdf.addPage();
  }

});

This creates a new page before inserting the next image into the document.

In some situations, users may also want multiple images on the same page instead of one image per page.

For example:

pdf.addImage(img1, "JPEG", 10, 20, 80, 80);

pdf.addImage(img2, "JPEG", 110, 20, 80, 80);

This allows more flexible layouts for galleries, reports, or grouped documents.

Configuring PDF Settings

Before generating the final PDF, users can customize several layout and output settings.

These settings improve document quality and give users more control over the generated file.

Here’s what the configuration panel looks like inside the tool:

Sorting Images

When multiple images are uploaded, organizing them properly becomes important before generating the PDF.

Users may want to sort images alphabetically, reverse the order, or arrange them based on file size.

For example, images can be sorted alphabetically like this:

files.sort((a, b) => a.name.localeCompare(b.name));

You can also sort files by size:

files.sort((a, b) => a.size - b.size);

Here’s an example of sorting options inside the tool:

This helps users organize documents more efficiently before converting them into a PDF.

Choosing Orientation

Different images work better in different page orientations.

Portrait orientation works well for vertical images, while landscape orientation is better for wider images.

For example:

const pdf = new jsPDF({
  orientation: "portrait"
});

You can also switch to "landscape" when needed.

Here’s an example of orientation options inside the tool:

Selecting Page Size

PDF page size controls the dimensions of the generated document.

For example:

const pdf = new jsPDF({
  unit: "mm",
  format: "a4"
});

This creates an A4-sized PDF document using millimeter units.

Other formats like letter, legal, or custom page sizes can also be supported.

Here’s an example of selecting page size options inside the tool:

Adding Margins

Margins create spacing between the image and the edges of the page.

Without margins, images may touch the borders and appear cramped.

For example:

const margin = 10;

pdf.addImage(imageData, "JPEG", margin, margin, 180, 120);

Here’s an example of margins options inside the tool:

This creates cleaner spacing around the inserted image.

Automatic Image Fitting

One common issue when generating PDFs from images is incorrect sizing.

If images are inserted with fixed dimensions, they may stretch, overflow outside the page, or appear distorted.

Instead, it’s better to calculate image dimensions dynamically.

For example:

const pageWidth = pdf.internal.pageSize.getWidth();

const imgWidth = pageWidth - 20;

const imgHeight = (image.height * imgWidth) / image.width;

pdf.addImage(imageData, "JPEG", 10, 10, imgWidth, imgHeight);

This automatically scales images proportionally while maintaining margins and layout consistency.

Merge Options

One useful feature is allowing different output modes.

For example, users may want to merge all uploaded images into a single PDF document when creating reports, notes, or combined files.

In some cases, users may prefer generating separate PDFs for each image instead of combining everything together. This can be useful when exporting individual documents or scanned pages.

Custom grouping is another helpful option because it allows users to combine selected images into multiple PDFs based on their own arrangement or categories.

These different output modes make the tool much more flexible for different real-world use cases.

A simple selection dropdown works well:

<select id="mergeMode">
  <option>Merge all into Single PDF</option>
  <option>Create Separate PDFs</option>
  <option>Custom Grouping</option>
</select>

Once selected, JavaScript can apply different generation logic based on the chosen mode.

Here’s an example of merge mode options inside the tool:

This makes the tool more flexible for handling different document workflows.

Renaming and Downloading the PDF

After generating the document, users may want to rename the file before downloading.

You can prompt for a filename like this:

const fileName = prompt("Enter PDF name:", "images");

pdf.save(`${fileName}.pdf`);

This gives users more control over the exported file.

Here’s an example of the rename popup inside the tool:

Demo: How the Image to PDF Tool Works

Step 1: Upload Images

Users upload one or multiple image files into the browser-based tool.

The tool supports common formats like JPG, PNG, and WEBP.

Step 2: Configure PDF Settings

Users can customize layout settings before generating the PDF.

This includes:

• sorting images

• orientation

• page size

• margins

• merge mode

These settings help create cleaner PDF output.

Step 3: Generate the PDF

Once settings are configured, users click the convert button.

The browser processes all uploaded images locally and generates the PDF instantly.

Step 4: Rename the Generated File

Before downloading, users can rename the generated PDF.

This improves organization when exporting multiple documents.

Step 5: Download the PDF

Finally, the generated PDF becomes available for download directly in the browser.

The entire process works without uploading files to any server.

Important Notes from Real-World Use

When working with large images, performance and memory usage become important.

Large images can slow down PDF generation and create unnecessarily large output files.

For example, you can limit upload size before processing:

const MAX_SIZE = 10 * 1024 * 1024;

if (file.size > MAX_SIZE) {
  alert("Image is too large.");
  return;
}

Another useful optimization is resizing images before inserting them into the PDF.

For example:

const canvas = document.createElement("canvas");

const ctx = canvas.getContext("2d");

canvas.width = image.width * 0.5;
canvas.height = image.height * 0.5;

ctx.drawImage(image, 0, 0, canvas.width, canvas.height);

const resizedImage = canvas.toDataURL("image/jpeg", 0.7);

This reduces image dimensions and compression quality before generating the PDF.

It also helps reduce memory usage and improves PDF generation speed for large files.

Since everything runs directly inside the browser, uploaded images never leave the user’s device, which improves privacy.

Common Mistakes to Avoid

One common mistake is not validating uploaded files before processing them.

For example, users may upload unsupported formats or attempt to generate a PDF without selecting images.

Always validate input before processing:

if (!fileInput.files.length) {
  alert("Please upload images first.");
  return;
}

Another issue is inserting very large images without resizing them first.

Large images can create oversized PDFs and reduce performance significantly.

Incorrect image positioning is also common.

If dimensions are hardcoded incorrectly, images may overflow outside the page or become distorted.

Using dynamic image sizing and margins helps prevent these layout issues.

Conclusion

In this tutorial, you built a browser-based image to PDF converter using JavaScript.

You learned how to upload images, generate PDF documents, configure layout settings, and export files directly inside the browser.

More importantly, you saw how modern browsers can handle document generation locally without relying on a backend server.

This approach keeps the tool fast, private, and easy to use.

Once you understand this workflow, you can extend it further with features like compression, drag-and-drop sorting, watermarking, batch exports, or advanced PDF editing tools.

You can also try a full working version here:

https://allinonetools.net/image-to-pdf-converter/

And that’s where things start getting really interesting.

It doesn't learn.

You ingest 500 documents. You ask a question. The system retrieves the three most similar chunks and hands them to the LLM. Repeat for the next query.

The system knows exactly as much as it did on day one. It's a library that never builds a card catalog, never cross-references its own shelves, never notices that three of its books are saying contradictory things.

That's what I set out to fix with a knowledge reflection layer. After every ingest, the system finds semantically related documents already in the index and asks an LLM to synthesise what's new, how it connects, and what gap remains. That synthesis gets embedded, stored, and boosted in search results.

The knowledge base gets smarter as you add more documents — not just bigger.

This tutorial shows you exactly how to build it.

Table of Contents

1. What You Will Build

2. Prerequisites

3. How to Set Up the Base System

4. Why Standard RAG Has a Memory Problem

5. Step 1: Schema Update

6. Step 2: The Reflection Engine

7. Step 3: Consolidation

8. Step 4: Wire It Into Your Ingest Handler

9. Step 5: Boost Reflections in Search

10. Step 6: Filtering by doc_type

11. What Changes After You Build This

12. Deploying

13. What to Build Next

What You Will Build

In this tutorial, you'll build a post-ingest reflection pipeline that:

1. Fires automatically after every document ingest

2. Finds the most semantically related documents already in the index

3. Asks Kimi K2.5 to synthesise a three-sentence insight linking the new document to existing knowledge

4. Stores that reflection with doc_type=reflection and a 1.5× ranking boost in search results

5. Consolidates reflections into summaries every three ingests

By the end, searching your knowledge base will surface both raw document chunks and reflection artifacts the system wrote on ingest.

Prerequisites

You will need:

• A Cloudflare account — free tier works

• Node.js v18+ and Wrangler CLI installed (npm install -g wrangler)

• Basic TypeScript familiarity

No external API keys. Everything runs on Cloudflare's infrastructure.

How to Set Up the Base System

If you have already built the RAG system from my freeCodeCamp handbook, skip this section — your system is ready for the reflection layer.

If you're starting fresh, this section gets you to a working base in about 15 minutes.

Scaffold the Project

npm create cloudflare@latest rag-reflection-system
cd rag-reflection-system

Choose: Hello World example → TypeScript → No deploy yet.

Create the Vectorize Index and D1 Database

npx wrangler vectorize create rag-index --dimensions=384 --metric=cosine
npx wrangler d1 create rag-db

Configure wrangler.toml

name = "rag-reflection-system"
main = "src/index.ts"
compatibility_date = "2026-01-01"

[[vectorize]]
binding = "VECTORIZE"
index_name = "rag-index"

[[d1_databases]]
binding = "DB"
database_name = "rag-db"
database_id = "YOUR_DB_ID"

[ai]
binding = "AI"

Create the documents Table

-- migrations/001_init.sql
CREATE TABLE IF NOT EXISTS documents (
  id TEXT PRIMARY KEY,
  content TEXT NOT NULL,
  source TEXT,
  date_created TEXT DEFAULT (datetime('now'))
);

npx wrangler d1 execute rag-db --remote --file=./migrations/001_init.sql

Add the ingest and search endpoints

Replace src/index.ts with this minimal working system:

export interface Env {
  VECTORIZE: VectorizeIndex;
  DB: D1Database;
  AI: Ai;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === '/ingest' && request.method === 'POST') {
      const { id, content, source } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [content.slice(0, 512)],
      }) as any;
      const vector = embResult.data[0];

      await env.VECTORIZE.upsert([{
        id,
        values: vector,
        metadata: { content: content.slice(0, 1000), source, doc_type: 'raw' },
      }]);

      await env.DB.prepare(
        'INSERT OR REPLACE INTO documents (id, content, source) VALUES (?, ?, ?)'
      ).bind(id, content, source ?? '').run();

      return Response.json({ success: true, id });
    }

    if (url.pathname === '/search' && request.method === 'POST') {
      const { query } = await request.json() as any;

      const embResult = await env.AI.run('@cf/baai/bge-small-en-v1.5', {
        text: [query],
      }) as any;
      const vector = embResult.data[0];

      const results = await env.VECTORIZE.query(vector, {
        topK: 5,
        returnMetadata: 'all',
      });

      const context = results.matches
        .map(m => m.metadata?.content as string)
        .filter(Boolean)
        .join('\n\n');

      const answer = await env.AI.run('@cf/moonshotai/kimi-k2.5', {
        messages: [
          { role: 'system', content: 'Answer using only the context provided.' },
          { role: 'user', content: `Context:\n\({context}\n\nQuestion: \){query}` },
        ],
        max_tokens: 256,
      }) as any;

      return Response.json({ answer: answer.response, sources: results.matches.map(m => m.id) });
    }

    return new Response('RAG system running', { status: 200 });
  },
};

Deploy and Verify

npx wrangler deploy

Test it:

# Ingest a document
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Cursor pagination beats offset pagination for live-updating datasets because offset becomes unreliable when rows are inserted or deleted during pagination."}'

# Search
curl -X POST https://your-worker.workers.dev/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what pagination approach should I use?"}'

If you get a grounded answer back, the base system is working. The next sections add the reflection layer on top of this foundation.

Why Standard RAG Has a Memory Problem

Standard RAG retrieval is stateless. Every query goes in cold. The system has no memory of what it found before, no synthesis of what it learned across documents, and no growing understanding of what questions remain unanswered.

Imagine you've ingested 200 documents about your product. Twelve of them touch on a pricing decision made last year. No single one has the full picture — it's distributed across quarterly reports, meeting notes, an internal Slack export, a few Notion pages.

A user asks: "Why did we change our pricing structure?"

Standard RAG retrieves the three most similar chunks. If those three chunks collectively have the answer, great. If they don't — if the real answer requires synthesising across those twelve documents — the system has no mechanism for that. It returns fragments. The LLM makes its best guess.

The reflection layer addresses this directly. When the twelfth pricing document gets ingested, the system finds the eleven related documents, synthesises what connects them, and stores that synthesis as a retrievable artifact. The answer to "why did we change our pricing structure" exists in the index before anyone asks the question.

Not smarter retrieval — smarter indexing.

Step 1: Schema Update

The reflection layer needs two new fields in your D1 documents table. Run this migration:

-- migrations/003_add_reflection_fields.sql
ALTER TABLE documents ADD COLUMN doc_type TEXT DEFAULT 'raw';
ALTER TABLE documents ADD COLUMN reflection_score REAL DEFAULT 0;
ALTER TABLE documents ADD COLUMN parent_reflection_id TEXT;

Apply it:

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql

doc_type distinguishes raw documents (raw), single-document reflections (reflection), and consolidated multi-reflection summaries (summary). You'll use this field to filter — exposing only reflections to users who want the distilled view, or excluding them for users who want raw source chunks.

Step 2: The Reflection Engine

Create src/engines/reflection.ts. This is the core of the layer.

import { Env } from '../types/env';
import { resolveEmbeddingModel, resolveReflectionModel } from '../config/models';

const REFLECTION_BOOST = 1.5;
const CONSOLIDATION_THRESHOLD = 3; // consolidate every N new reflections

export async function reflect(
  newDocId: string,
  newDocContent: string,
  env: Env
): Promise<void> {
  // 1. Find semantically related documents already in the index
  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, {
    text: [newDocContent.slice(0, 512)],
  });
  const queryVector = (embResult as any).data?.[0];
  if (!queryVector) return;

  const related = await env.VECTORIZE.query(queryVector, {
    topK: 5,
    filter: { doc_type: { $eq: 'raw' } },
    returnMetadata: 'all',
  });

  const relatedDocs = (related.matches ?? []).filter(
    m => m.id !== newDocId && (m.score ?? 0) > 0.65
  );

  if (relatedDocs.length === 0) return; // nothing related yet — skip

  // 2. Build synthesis prompt
  const relatedSummaries = relatedDocs
    .slice(0, 3)
    .map((m, i) => `Document \({i + 1}: \){String(m.metadata?.content ?? '').slice(0, 300)}`)
    .join('\n\n');

  const prompt = `You are synthesising knowledge across documents in a knowledge base.

New document:
${newDocContent.slice(0, 600)}

Related existing documents:
${relatedSummaries}

Write exactly three sentences:
1. What the new document adds that the existing documents don't already cover
2. How the new document connects to or extends the existing documents
3. What gap or question remains unanswered across all these documents

Be specific. Reference actual content. Do not summarise — synthesise.`;

  // 3. Call the reflection model
  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 180,
  });

  const reflectionText = (llmResp as any)?.response?.trim();
  if (!reflectionText || reflectionText.length < 40) return;

  // 4. Embed and store the reflection
  const reflEmbResult = await env.AI.run(embModel.id as any, {
    text: [reflectionText],
  });
  const reflVector = (reflEmbResult as any).data?.[0];
  if (!reflVector) return;

  const reflectionId = `refl_\({newDocId}_\){Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: reflectionId,
      values: reflVector,
      metadata: {
        content: reflectionText,
        doc_type: 'reflection',
        parent_id: newDocId,
        reflection_score: REFLECTION_BOOST,
        source_doc_ids: relatedDocs.map(m => m.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents
     (id, content, doc_type, reflection_score, parent_id, date_created)
     VALUES (?, ?, 'reflection', ?, ?, ?)`
  )
    .bind(reflectionId, reflectionText, REFLECTION_BOOST, newDocId, new Date().toISOString())
    .run();

  // 5. Check if consolidation is due
  const recentCount = await env.DB
    .prepare(`SELECT COUNT(*) as cnt FROM documents WHERE doc_type = 'reflection' AND date_created > datetime('now', '-1 hour')`)
    .first<{ cnt: number }>();

  if ((recentCount?.cnt ?? 0) >= CONSOLIDATION_THRESHOLD) {
    await consolidate(env);
  }
}

Two things worth noting here.

First, the semantic threshold (score > 0.65) matters. Too low and you're synthesising unrelated documents. Too high and you're rarely finding connections. 0.65 works well with bge-small. You can bump it to 0.72 with qwen3-0.6b (1024d) where scores cluster higher.

The prompt structure is deliberate. Three sentences, each doing a specific job: what's new, how it connects, what remains. This keeps reflections useful for retrieval. A freeform synthesis prompt produces beautiful prose that doesn't retrieve well. This structure produces retrievable artifacts.

Step 3: Consolidation

As reflections accumulate, they need their own synthesis layer — otherwise you're adding noise at a higher abstraction level.

Add this to src/engines/reflection.ts:

export async function consolidate(env: Env): Promise<void> {
  // Fetch recent reflections not yet consolidated
  const recent = await env.DB
    .prepare(
      `SELECT id, content FROM documents
       WHERE doc_type = 'reflection'
       AND id NOT IN (
         SELECT DISTINCT parent_id FROM documents
         WHERE doc_type = 'summary' AND parent_id IS NOT NULL
       )
       ORDER BY date_created DESC
       LIMIT 6`
    )
    .all<{ id: string; content: string }>();

  if (!recent.results || recent.results.length < CONSOLIDATION_THRESHOLD) return;

  const reflectionTexts = recent.results.map((r, i) => `Reflection \({i + 1}: \){r.content}`).join('\n\n');

  const prompt = `You are consolidating multiple knowledge reflections into a single compressed insight.

${reflectionTexts}

Write two to three sentences that capture the most important cross-cutting pattern or tension across these reflections. What does the knowledge base now understand that it didn't before these documents were added? What's the most important open question?

Be precise. No preamble.`;

  const reflModel = resolveReflectionModel(env.REFLECTION_MODEL);
  const llmResp = await env.AI.run(reflModel.id as any, {
    messages: [{ role: 'user', content: prompt }],
    max_tokens: 320,
  });

  const summaryText = (llmResp as any)?.response?.trim();
  if (!summaryText || summaryText.length < 40) return;

  const embModel = resolveEmbeddingModel(env.EMBEDDING_MODEL);
  const embResult = await env.AI.run(embModel.id as any, { text: [summaryText] });
  const summaryVector = (embResult as any).data?.[0];
  if (!summaryVector) return;

  const summaryId = `summary_${Date.now()}`;

  await env.VECTORIZE.upsert([
    {
      id: summaryId,
      values: summaryVector,
      metadata: {
        content: summaryText,
        doc_type: 'summary',
        reflection_score: REFLECTION_BOOST * 1.2,
        source_reflection_ids: recent.results.map(r => r.id).join(','),
        date_created: new Date().toISOString(),
      },
    },
  ]);

  await env.DB.prepare(
    `INSERT INTO documents (id, content, doc_type, reflection_score, date_created)
     VALUES (?, ?, 'summary', ?, ?)`
  )
    .bind(summaryId, summaryText, REFLECTION_BOOST * 1.2, new Date().toISOString())
    .run();
}

Summaries get a 1.2× multiplier on top of the base reflection boost. In search results, a summary synthesising twelve related documents should rank above any single document chunk on broad conceptual queries. On specific factual queries, the raw chunks will score higher. The ranking sorts itself.

Step 4: Wire It Into Your Ingest Handler

The reflection runs as a background job. It doesn't block the ingest response — that would add 2–3 seconds to every ingest call.

In your src/handlers/ingest.ts, after you've stored the document:

import { reflect } from '../engines/reflection';

// ... existing ingest logic ...

// After VECTORIZE.upsert() and DB insert succeed:
ctx.waitUntil(
  reflect(documentId, content, env).catch(err => {
    console.warn('[reflection] failed for', documentId, err.message);
  })
);

return new Response(JSON.stringify({
  success: true,
  documentId,
  chunks: chunkCount,
  // ... rest of response
}), { headers: { 'Content-Type': 'application/json' } });

ctx.waitUntil() is the Cloudflare Workers primitive for background work. The response returns immediately. The reflection runs after. The ingest API stays fast.

The .catch() is important. A failed reflection should never fail an ingest. Raw documents are the source of truth. Reflections are derived value — useful, but not critical path.

Step 5: Boost Reflections in Search

Add the reflection boost to your ranking logic in src/engines/hybrid.ts. After RRF fusion and before returning results:

// Apply reflection boost
const boosted = results.map(r => ({
  ...r,
  score: r.doc_type === 'reflection' || r.doc_type === 'summary'
    ? r.score * (r.reflection_score ?? 1.5)
    : r.score,
}));

return boosted.sort((a, b) => b.score - a.score);

This is a post-fusion boost, not a pre-fusion rerank. The reasoning: apply RRF across all results first, so reflections earn their place on raw relevance before getting boosted. A reflection that would not rank in the top 20 on raw similarity shouldn't appear just because it has a boost multiplier.

Step 6: Filtering by doc_type

Your search endpoint should accept a doc_type filter so callers can control what they see:

// In your search request handler:
const docTypeFilter = body.filters?.doc_type;

// Pass to Vectorize query:
const vectorFilter: Record<string, unknown> = {};
if (docTypeFilter) {
  vectorFilter.doc_type = docTypeFilter;
}

This gives callers three modes:

# Only reflections and summaries
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$in": ["reflection", "summary"] } } }

# Only source documents
POST /search
{ "query": "pricing decisions", "filters": { "doc_type": { "$eq": "raw" } } }

# Default: all types, reflections boosted
POST /search
{ "query": "pricing decisions" }

The default (no filter) is the most useful. Let the boost do its job. Restrict to raw when you need citations. Restrict to reflections when you want the synthesised view.

What Changes After You Build This

At 200 documents, the difference becomes noticeable. Queries that previously returned five fragmented chunks now surface a reflection that already synthesised those chunks. Broad conceptual queries — "what do we know about X?" — start returning genuinely useful summaries instead of just the most-similar individual paragraph.

At 2,000 documents, the reflection layer is the most valuable part of the system. The raw chunks answer specific factual questions. The reflections and summaries answer conceptual questions that could not be answered from any single document. The system has learned something no individual document contains.

One failure mode worth knowing: if your embedding model has poor semantic clustering — old bge-small at 384d with mixed-domain documents — the related-documents retrieval step will surface weak connections and produce shallow reflections. The 0.65 threshold filters most of this out, but if you're seeing reflections that seem off-topic, your embeddings are the first thing to check.

Deploying

wrangler d1 execute mcp-knowledge-db --remote --file=./migrations/003_add_reflection_fields.sql
wrangler deploy

Then ingest a few documents and watch what happens:

# Ingest document 1
curl -X POST https://your-worker.workers.dev/ingest \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "doc-001", "content": "Your document text here..."}'

# After a few seconds, check if a reflection was created
curl "https://your-worker.workers.dev/search" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your topic", "filters": {"doc_type": {"$eq": "reflection"}}}'

Reflections won't appear until there are related documents to synthesise. Ingest at least three documents on similar topics before expecting to see them.

What to Build Next

The reflection layer as described here fires after every ingest. That's expensive at high ingest volume: if you're batch-importing 10,000 documents, you don't want 10,000 individual reflection calls.

For bulk ingestion, gate it: call reflect() only when a document's similarity search returns a match above 0.8, or batch-run reflection after the bulk import completes. The POST /ingest/batch endpoint in the full repo does this.

The second thing worth building: surfacing reflections in your UI with a visual distinction. A search result that's a reflection should look different from a raw chunk. In the dashboard included in the repo, reflections render with a 💡 badge and a "synthesised from N documents" note.

Full source at github.com/dannwaneri/vectorize-mcp-worker — reflection engine, consolidation, batch ingest, dashboard, OpenAPI spec.

The codebase is TypeScript, deploys with a single wrangler deploy, runs for roughly $1–5/month at 10,000 queries/day.

Standard RAG retrieves. This learns.

Sometimes you need to combine reports or invoices, or simply merge multiple documents into a single clean file.

Most tools that handle this either require installing software or uploading files to a server, which can be slow and not always ideal – especially when dealing with private documents.

But what if you could merge PDFs directly in the browser, without any backend?

That’s exactly what we’ll build in this tutorial.

By the end, you’ll have a fully working browser-based PDF merger. It will allow users to upload files, preview them, reorder documents using drag-and-drop, select specific pages, and download the final merged PDF instantly.

Table of Contents

1. How PDF Merging Works in the Browser

2. Project Setup

3. What Library Are We Using?

4. Creating the Upload Interface

5. Rendering PDF Previews

6. Reordering Files Drag and Drop

7. Sorting and Reordering PDFs (Important)

8. Merging PDFs Using JavaScript

9. Improving User Experience

10. Demo: How the PDF Merger Works

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Conclusion

How PDF Merging Works in the Browser

At a high level, merging PDFs means loading multiple PDF files, extracting pages from each, and combining them into a single document.

Traditionally, this process happens on a server. Files are uploaded, processed, and then returned to the user.

But modern JavaScript libraries make it possible to do all of this directly in the browser. Instead of sending files anywhere, the entire process runs locally on the user’s device.

This approach has a few practical advantages. It makes the process faster because there’s no upload time involved. It also improves privacy, since files never leave the user’s system. And from a development perspective, it removes the need for backend processing altogether.

Project Setup

We’ll keep this project simple.

You only need:

• an HTML file

• JavaScript

• a few libraries

No backend required.

What Library Are We Using?

We’ll use two important libraries:

<script src="https://unpkg.com/pdf-lib@1.17.1/dist/pdf-lib.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/2.16.105/pdf.min.js"></script>

• We'll use pdf-lib to merge and modify PDFs

• We'll use pdf.js to render previews in the browser

This combination is very powerful and commonly used in real projects.

Creating the Upload Interface

Start with a simple drag-and-drop area:

<div id="upload-area">
  <input type="file" id="file-input" multiple accept="application/pdf">
</div>

Users can either drag files or click to select.

Once files are selected, we read them using:

const arrayBuffer = await file.arrayBuffer();

This allows us to pass the file into our PDF libraries.

Rendering PDF Previews

To improve usability, we'll show a preview of each uploaded PDF.

Using pdf.js, we can render pages like this:

const pdf = await pdfjsLib.getDocument(arrayBuffer).promise;
const page = await pdf.getPage(1);

const viewport = page.getViewport({ scale: 1.5 });
canvas.height = viewport.height;
canvas.width = viewport.width;

page.render({
  canvasContext: context,
  viewport: viewport
});

This gives users visual feedback before merging.

Reordering Files (Drag and Drop)

Order matters when merging PDFs.

Instead of forcing users to upload in sequence, we'll allow reordering.

We can use a library like Sortable.js for this:

new Sortable(document.getElementById('pdf-grid'), {
  animation: 150
});

This enables drag-and-drop sorting and instant visual updates.

Sorting and Reordering PDFs (Important)

This is where the tool becomes more practical in real-world use.

Instead of forcing users to upload files in a specific order, the tool allows them to rearrange PDFs before merging.

Users can manually drag and drop files to adjust the sequence, or use built-in sorting options such as arranging files alphabetically or by file size. This makes it easy to quickly organize multiple documents without re-uploading them.

This flexibility ensures that the final merged document follows the exact order the user needs. In real-world scenarios, this is especially useful when combining reports, invoices, or other documents where sequence is important.

Here’s a simple example of how you might sort uploaded files:

function sortFiles(files, type) {
  return files.sort((a, b) => {
    if (type === "name-asc") {
      return a.name.localeCompare(b.name);
    }

    if (type === "name-desc") {
      return b.name.localeCompare(a.name);
    }

    if (type === "size-asc") {
      return a.size - b.size;
    }

    if (type === "size-desc") {
      return b.size - a.size;
    }

    return 0;
  });
}

This allows precise control over what gets merged.

Merging PDFs Using JavaScript

Now comes the core logic. We'll use pdf-lib to combine pages:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const pdf = await PDFDocument.load(file.arrayBuffer);
  const pages = await mergedPdf.copyPages(pdf, selectedPages);

  pages.forEach(page => mergedPdf.addPage(page));
}

const pdfBytes = await mergedPdf.save();

Finally, we'll create a downloadable file:

const blob = new Blob([pdfBytes], { type: 'application/pdf' });

Improving User Experience

A simple merge tool works, but a good tool feels smooth.

Small improvements make a big difference.

For example:

• showing previews before merging

• allowing users to remove files

• enabling page navigation

• providing instant feedback

These details turn a basic feature into a real product.

Demo: How the PDF Merger Works

Here’s how the full flow looks in practice:

Step 1: Upload PDFs

Users can drag and drop PDF files into the upload area or select them manually.

Step 2: Preview Files

Each uploaded file is displayed with a preview as well as pdf files details (name, size, nos of page, and so on), so users can verify the content before merging.

Step 3: Reorder Files

Users can arrange the order of PDFs using drag-and-drop or sorting options as well as manual options. This ensures the final merged document follows the correct sequence.

Step 4: Merge PDFs

Once everything is arranged, users can click the merge button to combine all selected PDFs into a single file.

Step 5: Download the Final PDF

The merged PDF is generated instantly in the browser, and users can preview , rename, and download it without any server interaction.

Important Notes from Real-World Use

When building tools like a PDF merger, handling large files efficiently becomes important.

If multiple large PDFs are loaded at once, it can slow down the browser or consume too much memory. Instead of processing everything at once, it’s better to handle files step by step.

For example, instead of loading all PDFs together, you can process them one by one:

const { PDFDocument } = PDFLib;

const mergedPdf = await PDFDocument.create();

for (const file of files) {
  const arrayBuffer = await file.arrayBuffer();
  const pdf = await PDFDocument.load(arrayBuffer);

  const pages = await mergedPdf.copyPages(pdf, pdf.getPageIndices());

  pages.forEach(page => mergedPdf.addPage(page));
}

This approach keeps memory usage lower and avoids freezing the browser when working with larger files.

You can also improve performance by limiting file size or the number of files users can upload at once. This helps keep the tool responsive even on lower-powered devices.

Another important aspect is privacy. Since everything runs directly in the browser, files are never uploaded to a server. This means sensitive documents stay on the user’s device.

But it’s still important to be transparent about this. In real-world tools, you should clearly mention that all processing happens locally and no files are stored or transmitted.

This client-side approach improves both performance and user trust, especially when working with private or confidential documents.

Common Mistakes to Avoid

A common mistake is skipping validation. If users upload invalid files or empty inputs, the merge process can fail.

Another issue is ignoring page ranges. If parsing is incorrect, users may get unexpected results.

Also, relying on fixed layouts or assumptions can break the experience across different files. Testing with different PDF types is important.

Conclusion

In this tutorial, you built a browser-based PDF merger using JavaScript.

More importantly, you learned how to process files locally in the browser, render previews for better usability, handle user input safely, and manage dynamic document structures when working with PDFs.

This approach removes the need for a backend and keeps everything fast, private, and efficient.

Once you understand this pattern, you can extend it to build more advanced tools. For example, you could create features like PDF splitting, compression, editing, or other document-based utilities using the same core ideas.

And that’s where things start getting really interesting.

That frustration made the problem feel very clear to me: it was not about having fewer clothes. It was about having better organization, better visibility, and better guidance when making outfit decisions.

So I built a fashion web app that helps users organize their wardrobe, get outfit suggestions, evaluate shopping decisions, and improve recommendations over time using feedback.

In this article, I’ll walk through what the app does, how I built it, the decisions I made along the way, and the challenges that shaped the final result.

Table of Contents

• Table of Contents

• What the App Does

• Why I Built It

• Tech Stack

• Product Walkthrough (What Users See)

• How I Built It

• Challenges I Faced

• What I Learned

• What I Want to Improve Next

• Future Improvements

• Conclusion

What the App Does

At a high level, the app combines six core capabilities:

1. Wardrobe management

2. Outfit recommendations

3. Shopping suggestions

4. Discard recommendations

5. Feedback and usage tracking

6. Secure multi-user accounts

Users can upload clothing items, explore suggested outfits, and mark recommendations as helpful or not helpful. They can also rate outfits and track whether items are worn, kept, or discarded.

That feedback becomes structured data for improving future recommendation quality.

Why I Built It

I wanted to create something that felt personal and actually useful. A lot of fashion apps look polished, but they do not always help with everyday decisions. My goal was to build something that could make wardrobe management easier and outfit selection less overwhelming. The app needed to do three things well:

• store each user’s wardrobe data

• personalize recommendations

• learn from user feedback over time .

That feedback loop mattered to me because it makes the app feel more alive instead of static.

Tech Stack

Here are the tools I used to built the app:

• Frontend: React + Vite

• Backend: FastAPI

• Database: SQLite (local development)

• Background jobs: Celery + Redis

• Authentication: JWT (access + refresh token flow)

• Deployment support: Docker and GitHub Codespaces

This ended up giving me a pretty modular setup, which helped a lot as features started increasing: fast frontend iteration, clean API boundaries, and room to evolve recommendations separately from UI.

Product Walkthrough (What Users See)

1. Onboarding and Account Setup

To start using the app, a user needs to register, verify their email, and complete some profile basics.

Each account is isolated, so wardrobe history and recommendations stay user-specific.

In this onboarding screen above, you can see account creation, email verification, and profile fields for body shape, height, weight, and style preferences.

2. Wardrobe Upload

Users can upload clothing images .

Image analysis labels each item and makes it searchable for recommendations. The wardrobe upload form shows image analysis results with category, dominant color, secondary color, and pattern details listed.

3. Outfit Recommendations

Users can request recommendations, then rate outputs.

Above you can see the outfit recommendation dashboard that shows ranked outfit cards with feedback and rating actions. Recommendations are ranked by a weighted scoring model.

4. Shopping and Discard Assistants

The app evaluates new items against existing wardrobe data and flags low-value wardrobe items that may be worth removing.

You can see the recommendation scores, written reasons (not just a binary decision), and styling guidance for each item above. It also features a "how to style it" incase the user still wants to keep the item.

How I Built It

1. Frontend Setup (React + Vite)

I used React + Vite because I wanted fast iteration and a clean component structure.

The frontend is split into feature areas like onboarding, wardrobe management, outfits, shopping, and discarded-item suggestions. I also keep API calls in a service layer so the UI components stay focused on rendering and interaction.

The snippet below is a simplified example of the API service pattern used in the app. It is not meant to be copy-pasted as-is, but it shows the same structure the frontend uses when talking to the backend.

Example API client pattern:

export async function getOutfitRecommendations(userId, params = {}) {
  const query = new URLSearchParams(params).toString();
  const url = `/users/\({userId}/outfits/recommend\){query ? `?${query}` : ""}`;

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${localStorage.getItem("access_token")}`,
    },
  });

  if (!response.ok) {
    throw new Error("Failed to fetch outfit recommendations");
  }

  return response.json();
}

Here's what's happening in that snippet:

• URLSearchParams builds optional query strings like occasion, season, or limit.

• The request path is user-scoped, which keeps each user’s recommendations isolated.

• The Authorization header sends the access token so the backend can verify the session.

• The response is checked before parsing so the UI can surface a useful error if the request fails.

This pattern kept the frontend simple and reusable as the number of API calls grew.

2. Backend Architecture with FastAPI

The backend is organized around clear route groups:

• auth routes for register, login, refresh, logout, and sessions

• user analysis routes

• wardrobe CRUD routes

• recommendation routes for outfits, shopping, and discard analysis

• feedback routes for ratings and helpfulness signals

One of the most important design choices was enforcing ownership checks on user-scoped resources. That prevented one user from accessing another user’s wardrobe or feedback data.

The backend snippet below is another simplified example from the app’s route layer. It shows the request validation and orchestration logic, while the actual scoring work stays in the recommendation service.

@app.get("/users/{user_id}/outfits/recommend")
def recommend_outfits(user_id: int, occasion: str | None = None, season: str | None = None, limit: int = 10):
    user = get_user_or_404(user_id)
    wardrobe_items = get_user_wardrobe(user_id)

    if len(wardrobe_items) < 2:
        raise HTTPException(status_code=400, detail="Not enough wardrobe items")

    recommendations = outfit_generator.generate_outfit_recommendations(
        wardrobe_items=wardrobe_items,
        body_shape=user.body_shape,
        undertone=user.undertone,
        occasion=occasion,
        season=season,
        top_k=limit,
    )

    return {"user_id": user_id, "recommendations": recommendations}

Here's how to read that code:

• get_user_or_404 loads the profile data needed for personalization.

• get_user_wardrobe fetches only the current user’s items.

• The minimum wardrobe check prevents the recommendation logic from running on incomplete data.

• generate_outfit_recommendations handles the scoring logic separately, which keeps the route handler small and easier to test.

• The response returns the results in a shape the frontend can consume directly.

That separation helped keep the API layer readable while the recommendation logic stayed isolated in its own service.

3. Recommendation Logic

I intentionally started with deterministic rules before introducing heavy ML. That made behavior easier to debug and explain.

The outfit recommender scores combinations using weighted signals:

$$\text{outfit score} = 0.4 \cdot \text{color harmony} + 0.4 \cdot \text{body-shape fit} + 0.2 \cdot \text{undertone fit}$$

The snippet below is a simplified example from the recommendation engine. It shows how the app combines multiple signals into a single score:

def score_outfit(combo, user_context):
    color_score = color_harmony.score(combo)
    shape_score = body_shape_rules.score(combo, user_context.body_shape)
    undertone_score = undertone_rules.score(combo, user_context.undertone)

    total = 0.4 * color_score + 0.4 * shape_score + 0.2 * undertone_score
    return round(total, 3)

The logic behind this approach is straightforward:

• color harmony helps the outfit feel visually coherent

• body-shape scoring helps the outfit feel flattering

• undertone scoring helps the colors work better with the user’s profile

I used a similar structure for discard recommendations and shopping suggestions, but with different factors and thresholds.

4. Authentication and Secure Multi-user Design

Security was one of the most important parts of this build.

I implemented:

• short-lived access tokens

• refresh tokens with JTI tracking

• token rotation on refresh

• session revocation (single session and all sessions)

• email verification and password reset flows

The snippet below is a simplified example of the refresh-token lifecycle used in the app. It shows the important control points rather than every helper function:

def refresh_access_token(refresh_token: str):
    payload = decode_jwt(refresh_token)
    jti = payload["jti"]

    token_record = db.get_refresh_token(jti)
    if not token_record or token_record.revoked:
        raise AuthError("Invalid refresh token")

    new_refresh, new_jti = issue_refresh_token(payload["sub"])
    token_record.revoked = True
    token_record.replaced_by_jti = new_jti

    new_access = issue_access_token(payload["sub"])
    return {"access_token": new_access, "refresh_token": new_refresh}

What this code is doing:

• It decodes the refresh token and looks up its JTI in the database.

• It rejects reused or revoked sessions, which helps prevent replay attacks.

• It rotates the refresh token instead of reusing it.

• It issues a fresh access token so the session stays valid without forcing the user to log in again.

This design made multi-device sessions safer and gave me server-side control over logout behavior.

5. Background Jobs for Long-running Operations

Image analysis can be expensive, especially when the app needs to classify clothing, analyze colors, and estimate body-shape-related signals. To keep the request path responsive, I added Celery + Redis support for background tasks.

That gave the app two modes:

• synchronous processing for simpler local development

• queued processing for heavier or slower jobs

That tradeoff mattered because it let me keep the developer experience simple without blocking the app during more expensive work.

6. Data Model and Feedback Capture

A recommendation system only improves if it captures the right signals.

So I added dedicated feedback tables for:

• outfit ratings (1-5 + optional comments)

• recommendation helpful/unhelpful feedback

• item usage actions (worn/kept/discarded)

Here is the shape of one of those models:

class RecommendationFeedback(Base):
    __tablename__ = "recommendation_feedback"

    id = Column(Integer, primary_key=True)
    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
    recommendation_type = Column(String(50), nullable=False)
    recommendation_id = Column(Integer, nullable=False)
    helpful = Column(Boolean, nullable=False)
    created_at = Column(DateTime, default=datetime.utcnow)

How to read this model:

• user_id ties feedback to the person who gave it.

• recommendation_type tells me whether the feedback belongs to outfits, shopping, or discard suggestions.

• recommendation_id identifies the exact recommendation.

• helpful stores the user’s direct response.

• created_at makes it possible to analyze feedback trends over time.

This part of the system gives the app a real learning foundation, even though the feedback-to-model-update loop is still a future improvement.

Challenges I Faced

This was the section that taught me the most.

1. Image-heavy endpoints were slower than I wanted

The analyze and wardrobe upload flows were doing a lot of work at once: image validation, classification, color extraction, storage, and database writes.

At first, that made the request flow feel heavier than it should have.

What I changed:

• I bounded concurrent image jobs so the app wouldn't try to do too much at once.

• I separated slower jobs into background processing where possible.

• I used load-test results to confirm which endpoints were actually expensive.

The practical effect was that heavy image requests stopped competing with each other so aggressively. Instead of letting many expensive tasks pile up inside the same request cycle, I limited the active work and pushed slower operations into the queue when needed.

Why this fixed it:

• Bounding concurrency prevented the system from overloading CPU-bound tasks.

• Moving expensive work into async jobs kept the main request/response cycle more responsive.

• Load testing gave me evidence instead of guesswork, so I could tune the system based on real performance behavior.

In other words, I didn't just “optimize” the endpoint in theory. I changed the execution model so expensive analysis could not block every other request behind it.

2. JWT sessions needed real server-side control

A basic JWT setup is easy to get working, but it becomes less useful if you cannot revoke sessions or manage multiple devices cleanly.

What I changed:

• I stored refresh tokens in the database.

• I tracked token JTI values.

• I rotated refresh tokens when users refreshed their session.

• I added endpoints for logging out a single session or all sessions.

The important shift here was moving from “token exists, therefore session is valid” to “token exists, matches the database record, and has not been revoked or replaced.” That gave the server the authority to invalidate old sessions immediately.

Why this fixed it:

• Server-side token tracking made revocation possible.

• Rotation reduced the chance of token reuse.

• Session management became visible to the user, which made the app feel more trustworthy.

This is what made logout-all and multi-device management work in a real way instead of just being cosmetic UI actions.

3. User data isolation had to be explicit

Because this is a multi-user app, I had to be careful that one account could never accidentally see another account’s wardrobe data.

What I changed:

• I added ownership checks to user-scoped routes.

• I kept all wardrobe and feedback queries filtered by user_id.

• I used encrypted image storage instead of exposing raw paths.

In practice, this meant every route had to ask the same question: “Does this user own the resource they are trying to access?” If the answer was no, the request stopped immediately.

Why this fixed it:

• Ownership checks made data access rules explicit.

• User-filtered queries prevented accidental cross-account reads.

• Encrypted storage improved privacy and reduced the risk of exposing image data directly.

That combination is what kept wardrobe data, feedback history, and images separated correctly across accounts.

4. Docker made the project easier to share, but only after the stack was organized

The app includes the frontend, backend, Redis, Celery worker, and Celery Beat, so the first challenge was making the setup feel reproducible instead of fragile.

What I changed:

• I defined the stack in Docker Compose.

• I documented the required environment variables.

• I kept the dev stack aligned with how the app runs in practice.

This removed a lot of setup ambiguity. Instead of asking someone to manually figure out how the frontend, backend, Redis, and workers fit together, I made the stack describe itself.

Why this fixed it:

• Docker let contributors start the project with fewer manual steps.

• Clear environment configuration reduced setup mistakes.

• Matching the stack to the architecture made the app easier to understand and test.

That was important because the app depends on several moving parts, and the simplest way to make the project approachable was to make startup behavior predictable.

What I Learned

This project taught me a few important lessons:

• Small features become much more valuable when they work together.

• Feedback data is one of the strongest signals for improving recommendations.

• Clean data modeling matters a lot when multiple users are involved.

• Docker and clear setup instructions make a project much easier for other people to try.

I also learned that a project does not need to be huge to be useful. A focused app that solves one problem well can still feel meaningful.

What I Want to Improve Next

My roadmap from here:

1. Integrate feedback directly into ranking updates

2. Add visual analytics for recommendation quality trends

3. Improve mobile UX parity

4. Deploy with persistent cloud storage and production database defaults

5. Provide a public demo mode for easier evaluation

Future Improvements

There are still a few things I would like to add later:

• a more advanced recommendation engine

• visual analytics for user feedback

• better mobile support

• live deployment with persistent cloud storage

• a public demo mode for easier testing

Conclusion

This project began as a personal frustration and turned into a full web application with authentication, wardrobe storage, recommendation logic, and feedback infrastructure.

The most rewarding part was seeing how practical software decisions, not just flashy UI, can help people make everyday choices faster.

If you want to explore or run the project, check out the repo. You can try the flows and share feedback. I would especially love input on recommendation quality, UX clarity, and what features would make this genuinely useful in daily life.

A character count doesn't need GPT-4. A presence check doesn't need Sonnet. A regex doesn't need anything except Python.

The mistake isn't using AI — it's not knowing when to stop using it.

This tutorial shows you how to build a tiered routing system that sends tasks to the cheapest model that can solve them. The pattern is called the cost curve. It comes from a comment thread on a DEV.to article, implemented by three developers over a weekend, and it cut the per-URL cost of a real SEO audit agent from \(0.006 to effectively \)0 for most pages.

By the end, you'll have a working cost_curve.py module you can drop into any agent project.

What You'll Build

A three-tier routing function that:

• Runs deterministic Python checks first — zero API cost

• Escalates to Claude Haiku only for genuinely ambiguous cases — ~$0.0001 per call

• Escalates to Claude Sonnet only when semantic judgment is required — ~$0.006 per call

• Falls back gracefully when any tier fails

• Returns a consistent result schema regardless of which tier handled the request

The full implementation is part of dannwaneri/seo-agent, an open-core SEO audit agent. The cost curve module is the premium routing layer, and the principle applies to any agent with mixed-complexity tasks.

Prerequisites

• Python 3.11 or higher

• An Anthropic API key

• Basic familiarity with Python and the Claude API

Table of Contents

1. The Problem with Calling Claude on Everything

2. The Cost Curve Explained

3. Project Setup

4. Tier 1: Deterministic Python

5. Tier 2: Claude Haiku for Ambiguous Cases

6. Tier 3: Claude Sonnet for Semantic Judgment

7. The Router: audit_url()

8. Graceful Fallback

9. Testing the Cost Curve

10. Applying This Pattern to Your Agent

The Problem with Calling Claude on Everything

Here's what most agent code looks like:

def audit_url(snapshot: dict) -> dict:
    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        messages=[{"role": "user", "content": build_prompt(snapshot)}]
    )
    return parse_response(response)

This works. It also calls Sonnet for every URL in the list — including the ones where the title is 142 characters long and the answer is obviously FAIL without any model involvement.

Claude Sonnet 4 is priced at \(3 per million input tokens and \)15 per million output tokens. A typical page snapshot is around 500 input tokens. That's \(0.0015 per URL just for input — before output tokens. Across a 20-URL weekly audit, the total is around \)0.12. Not expensive. But most of those pages have mechanical SEO issues: missing descriptions, titles over 60 characters, no canonical tag. A character count catches all of that. You don't need a model.

The cost curve fixes this by routing based on what the task actually requires, not on what the model is capable of.

The Cost Curve Explained

In the cost curve, we have three tiers, three tools, and three price points:

Tier 1 — Deterministic Python. Cost: $0. Check title length, description length, H1 count, canonical presence. These are not judgment calls. They're string operations. If title length > 60, FAIL. No model needed.

Tier 2 — Claude Haiku. Cost: ~$0.0001 per call. Title present but only 4 characters long. Description present but only 30 characters. Status code is a redirect. These pass the mechanical audit but something is off. Haiku is fast and cheap enough that escalating ambiguous cases costs less than the debugging time you'd spend on false positives.

Tier 3 — Claude Sonnet. Cost: ~$0.006 per call. Pages Haiku flags as needing semantic judgment. "This title passes length but reads like a navigation label." "This description duplicates the title verbatim." Sonnet earns its cost on genuinely hard cases — not on every URL in the list.

The routing decision happens before any API call. The result schema is identical regardless of which tier handled the request.

Project Setup

mkdir cost-curve-demo && cd cost-curve-demo
pip install anthropic

Set your API key:

# macOS/Linux
export ANTHROPIC_API_KEY="sk-ant-..."

# Windows PowerShell
$env:ANTHROPIC_API_KEY = "sk-ant-..."

Create cost_curve.py — you'll build this module step by step.

Tier 1: Deterministic Python

Tier 1 runs first on every URL. It checks four fields using only Python string operations. There's no API call, no latency, and no cost.

import json
import logging
import os
import re
from datetime import datetime, timezone

import anthropic

logger = logging.getLogger(__name__)

REDIRECT_CODES = {301, 302, 307, 308}

# Fields that trigger Tier 2 escalation
# Title or description present but suspiciously short
AMBIGUOUS_TITLE_MAX = 10   # chars — present but too short to be real
AMBIGUOUS_DESC_MAX = 50    # chars — present but too short to be useful


def _now_iso() -> str:
    return datetime.now(timezone.utc).isoformat()


def _build_result(snapshot: dict, method: str) -> dict:
    """Base result skeleton — same schema regardless of tier."""
    return {
        "url": snapshot.get("final_url", ""),
        "final_url": snapshot.get("final_url", ""),
        "status_code": snapshot.get("status_code"),
        "title": {"value": None, "length": 0, "status": "PASS"},
        "description": {"value": None, "length": 0, "status": "PASS"},
        "h1": {"count": 0, "value": None, "status": "PASS"},
        "canonical": {"value": None, "status": "PASS"},
        "flags": [],
        "human_review": False,
        "audited_at": _now_iso(),
        "method": method,
        "needs_tier3": False,
    }


def tier1_check(snapshot: dict) -> dict:
    """
    Pure Python SEO checks. Zero API calls.

    Returns a result dict with method="deterministic".
    Sets needs_tier3=False always — Tier 1 never escalates to Tier 3 directly.
    Escalation to Tier 2 is decided by the router, not here.
    """
    result = _build_result(snapshot, "deterministic")

    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    h1s = snapshot.get("h1s") or []
    canonical = snapshot.get("canonical") or ""

    # Title check
    result["title"]["value"] = title or None
    result["title"]["length"] = len(title)
    if not title or len(title) > 60:
        result["title"]["status"] = "FAIL"
        msg = "Title is missing" if not title else f"Title is {len(title)} characters (max 60)"
        result["flags"].append(msg)

    # Description check
    result["description"]["value"] = description or None
    result["description"]["length"] = len(description)
    if not description or len(description) > 160:
        result["description"]["status"] = "FAIL"
        msg = "Meta description is missing" if not description else f"Meta description is {len(description)} characters (max 160)"
        result["flags"].append(msg)

    # H1 check
    result["h1"]["count"] = len(h1s)
    result["h1"]["value"] = h1s[0] if h1s else None
    if len(h1s) == 0:
        result["h1"]["status"] = "FAIL"
        result["flags"].append("H1 tag is missing")
    elif len(h1s) > 1:
        result["h1"]["status"] = "FAIL"
        result["flags"].append(f"Multiple H1 tags found ({len(h1s)})")

    # Canonical check
    result["canonical"]["value"] = canonical or None
    if not canonical:
        result["canonical"]["status"] = "FAIL"
        result["flags"].append("Canonical tag is missing")

    return result

The key design decision: tier1_check() never decides whether to escalate. It just runs the checks and returns. The router decides escalation based on the result.

Tier 2: Claude Haiku for Ambiguous Cases

Tier 2 runs when Tier 1 detects something mechanical but the result might need a second look. A 4-character title present but clearly wrong. A 30-character description that's technically there but useless. A redirect status that needs a human-readable explanation.

Haiku is the right model here. It's fast, cheap (\(1 input / \)5 output per million tokens), and sufficient for triage-level judgment. The prompt asks a narrow question: is this ambiguous enough to need Sonnet?

def tier2_check(snapshot: dict) -> dict:
    """
    Claude Haiku call for ambiguous cases.

    Returns result with method="haiku".
    Sets needs_tier3=True if Haiku determines the case needs semantic judgment.
    Falls back to Tier 1 result on API error.
    """
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise OSError("ANTHROPIC_API_KEY is not set.")

    client = anthropic.Anthropic(api_key=api_key)

    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    status_code = snapshot.get("status_code")

    prompt = f"""You are an SEO auditor doing a quick triage check.

Page data:
- Title: {repr(title)} ({len(title)} chars)
- Meta description: {repr(description)} ({len(description)} chars)
- Status code: {status_code}

Answer these two questions with only "yes" or "no":
1. Does this page need semantic judgment beyond simple length/presence checks? 
   (e.g. title is present but clearly wrong, description is present but meaningless)
2. Is the status code a redirect that needs investigation?

Respond in this exact JSON format and nothing else:
{{"needs_tier3": true_or_false, "reason": "one sentence explanation"}}"""

    try:
        response = client.messages.create(
            model="claude-haiku-4-5-20251001",
            max_tokens=150,
            messages=[{"role": "user", "content": prompt}],
        )
        raw = response.content[0].text.strip()
        # Strip markdown fences if present
        if raw.startswith("```"):
            lines = raw.splitlines()
            raw = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])
        parsed = json.loads(raw)

        result = _build_result(snapshot, "haiku")
        # Copy Tier 1 field checks — Haiku doesn't redo those
        t1 = tier1_check(snapshot)
        result["title"] = t1["title"]
        result["description"] = t1["description"]
        result["h1"] = t1["h1"]
        result["canonical"] = t1["canonical"]
        result["flags"] = t1["flags"]
        result["needs_tier3"] = parsed.get("needs_tier3", False)
        if result["needs_tier3"]:
            result["flags"].append(f"Escalated to Tier 3: {parsed.get('reason', '')}")

        return result

    except Exception as exc:
        logger.warning("[tier2] Haiku API error: %s — falling back to Tier 1 result", exc)
        fallback = tier1_check(snapshot)
        fallback["method"] = "haiku-fallback"
        return fallback

The fallback is the critical piece. If Haiku fails — rate limit, network error, malformed response — the function returns the Tier 1 result rather than crashing. The audit continues. The URL gets flagged with method="haiku-fallback" so you can identify it later.

Tier 3: Claude Sonnet for Semantic Judgment

Tier 3 is where the full extraction prompt runs. This is the same call you'd make in a naïve implementation — the difference is that only a small fraction of URLs reach this tier.

def tier3_check(snapshot: dict) -> dict:
    """
    Claude Sonnet call for semantic judgment.

    Returns result with method="sonnet".
    This is the full extraction prompt — same as calling the model directly.
    """
    api_key = os.environ.get("ANTHROPIC_API_KEY")
    if not api_key:
        raise OSError("ANTHROPIC_API_KEY is not set.")

    client = anthropic.Anthropic(api_key=api_key)

    prompt = f"""You are an SEO auditor. Analyze this page snapshot and return ONLY a JSON object.
No prose. No explanation. No markdown fences. Raw JSON only.

Page data:
- URL: {snapshot.get('final_url')}
- Status code: {snapshot.get('status_code')}
- Title: {snapshot.get('title')}
- Meta description: {snapshot.get('meta_description')}
- H1 tags: {snapshot.get('h1s')}
- Canonical: {snapshot.get('canonical')}

Return this exact schema:
{{
  "url": "string",
  "final_url": "string",
  "status_code": number,
  "title": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "description": {{"value": "string or null", "length": number, "status": "PASS or FAIL"}},
  "h1": {{"count": number, "value": "string or null", "status": "PASS or FAIL"}},
  "canonical": {{"value": "string or null", "status": "PASS or FAIL"}},
  "flags": ["array of strings describing specific issues"],
  "human_review": false,
  "audited_at": "ISO timestamp"
}}

PASS/FAIL rules:
- title: FAIL if null or length > 60 characters, or if present but clearly not a real title
- description: FAIL if null or length > 160 characters, or if present but meaningless
- h1: FAIL if count is 0 or count > 1
- canonical: FAIL if null
- audited_at: use current UTC time"""

    try:
        response = client.messages.create(
            model="claude-sonnet-4-20250514",
            max_tokens=1000,
            messages=[{"role": "user", "content": prompt}],
        )
        raw = response.content[0].text.strip()
        if raw.startswith("```"):
            lines = raw.splitlines()
            raw = "\n".join(lines[1:-1] if lines[-1].strip() == "```" else lines[1:])

        result = json.loads(raw)
        result["method"] = "sonnet"
        result["needs_tier3"] = False
        return result

    except Exception as exc:
        logger.warning("[tier3] Sonnet API error: %s — falling back to Tier 1 result", exc)
        fallback = tier1_check(snapshot)
        fallback["method"] = "sonnet-fallback"
        return fallback

Note the prompt addition in Tier 3 that isn't in Tier 1: "or if present but clearly not a real title" and "or if present but meaningless". That's the semantic judgment Haiku identified as needed. Tier 3 acts on it.

The Router: audit_url()

The router is the public interface. Everything else is an implementation detail.

def audit_url(snapshot: dict, tiered: bool = False) -> dict:
    """
    Route a page snapshot through the appropriate audit tier.

    Args:
        snapshot: Page data from browser.py — must contain final_url,
                  status_code, title, meta_description, h1s, canonical.
        tiered: If False, delegates directly to Tier 3 (Sonnet).
                If True, routes through the cost curve.

    Returns:
        Audit result dict with method field indicating which tier ran.
    """
    if not tiered:
        # Non-tiered mode: call Sonnet directly, same as v1 behavior
        return tier3_check(snapshot)

    # Tier 1: always runs first
    t1_result = tier1_check(snapshot)

    # Check if escalation to Tier 2 is warranted
    title = snapshot.get("title") or ""
    description = snapshot.get("meta_description") or ""
    status_code = snapshot.get("status_code")

    needs_tier2 = (
        # Title present but suspiciously short
        (title and len(title) < AMBIGUOUS_TITLE_MAX) or
        # Description present but suspiciously short
        (description and len(description) < AMBIGUOUS_DESC_MAX) or
        # Redirect status — may need explanation
        (status_code in REDIRECT_CODES)
    )

    if not needs_tier2:
        # Tier 1 result is definitive — return without any API call
        return t1_result

    # Tier 2: Haiku triage
    t2_result = tier2_check(snapshot)

    if not t2_result.get("needs_tier3", False):
        # Haiku determined no semantic judgment needed
        return t2_result

    # Tier 3: Sonnet for semantic judgment
    return tier3_check(snapshot)

The router logic is explicit and readable. Each decision point is a named condition. When tiered=False, behavior is identical to the v1 naive implementation — this is the backward compatibility guarantee that lets you add the cost curve incrementally without breaking existing audits.

Graceful Fallback

The fallback pattern appears in both Tier 2 and Tier 3. It's worth making explicit:

# Pattern used in both tier2_check() and tier3_check()
except Exception as exc:
    logger.warning("[tierN] API error: %s — falling back to Tier 1 result", exc)
    fallback = tier1_check(snapshot)
    fallback["method"] = "tierN-fallback"
    return fallback

Three things this does:

1. Logs the error with enough context to debug later

2. Returns a valid result — the Tier 1 deterministic check always runs regardless

3. Tags the result with the fallback method so you can filter these in your report

An agent that crashes on API errors is not production-ready. An agent that degrades gracefully and continues is.

Testing the Cost Curve

Create test_cost_curve.py to verify routing behavior without live API calls:

import json
from unittest import mock

from cost_curve import audit_url, tier1_check


def make_snapshot(title="Normal Title Under 60 Chars",
                  description="A normal meta description that is under 160 characters and describes the page content well.",
                  h1s=["Single H1"],
                  canonical="https://example.com/page",
                  status_code=200,
                  final_url="https://example.com/page"):
    return {
        "title": title,
        "meta_description": description,
        "h1s": h1s,
        "canonical": canonical,
        "status_code": status_code,
        "final_url": final_url,
    }


def test_clean_page_returns_tier1_no_api_calls():
    """Clean page: all checks pass deterministically — no API call."""
    snapshot = make_snapshot()
    with mock.patch("anthropic.Anthropic") as mock_client:
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "deterministic"
        mock_client.assert_not_called()
    print("PASS: clean page → Tier 1, zero API calls")


def test_long_title_returns_tier1_fail_no_api_call():
    """Title >60 chars: FAIL from Tier 1, no API call."""
    snapshot = make_snapshot(title="A" * 70)
    with mock.patch("anthropic.Anthropic") as mock_client:
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "deterministic"
        assert result["title"]["status"] == "FAIL"
        mock_client.assert_not_called()
    print("PASS: title >60 → Tier 1 FAIL, zero API calls")


def test_suspiciously_short_title_escalates_to_tier2():
    """Title present but 4 chars: escalates to Tier 2."""
    snapshot = make_snapshot(title="SEO")  # 3 chars — under AMBIGUOUS_TITLE_MAX
    mock_response = mock.MagicMock()
    mock_response.content = [mock.MagicMock(
        text='{"needs_tier3": false, "reason": "title is short but not ambiguous"}'
    )]
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.return_value = mock_response
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "haiku"
        assert mock_client.return_value.messages.create.call_count == 1
    print("PASS: short title → Tier 2 (Haiku called once)")


def test_tiered_false_calls_sonnet_directly():
    """tiered=False: Sonnet called regardless of snapshot content."""
    snapshot = make_snapshot()  # clean page, would be Tier 1 in tiered mode
    mock_response = mock.MagicMock()
    mock_response.content = [mock.MagicMock(text=json.dumps({
        "url": "https://example.com/page",
        "final_url": "https://example.com/page",
        "status_code": 200,
        "title": {"value": "Normal Title Under 60 Chars", "length": 27, "status": "PASS"},
        "description": {"value": "desc", "length": 4, "status": "PASS"},
        "h1": {"count": 1, "value": "Single H1", "status": "PASS"},
        "canonical": {"value": "https://example.com/page", "status": "PASS"},
        "flags": [],
        "human_review": False,
        "audited_at": "2026-04-01T00:00:00+00:00",
    }))]
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.return_value = mock_response
        result = audit_url(snapshot, tiered=False)
        assert result["method"] == "sonnet"
        assert mock_client.return_value.messages.create.call_count == 1
    print("PASS: tiered=False → Sonnet called directly")


def test_haiku_api_failure_falls_back_to_tier1():
    """Haiku failure: falls back to Tier 1 result, no crash."""
    snapshot = make_snapshot(title="SEO")  # triggers Tier 2
    with mock.patch("anthropic.Anthropic") as mock_client:
        mock_client.return_value.messages.create.side_effect = Exception("rate limit")
        result = audit_url(snapshot, tiered=True)
        assert result["method"] == "haiku-fallback"
    print("PASS: Haiku failure → fallback to Tier 1, no crash")


if __name__ == "__main__":
    test_clean_page_returns_tier1_no_api_calls()
    test_long_title_returns_tier1_fail_no_api_call()
    test_suspiciously_short_title_escalates_to_tier2()
    test_tiered_false_calls_sonnet_directly()
    test_haiku_api_failure_falls_back_to_tier1()
    print("\nAll tests passed.")

Run it:

python test_cost_curve.py

Expected output:

PASS: clean page → Tier 1, zero API calls
PASS: title >60 → Tier 1 FAIL, zero API calls
PASS: short title → Tier 2 (Haiku called once)
PASS: tiered=False → Sonnet called directly
PASS: Haiku failure → fallback to Tier 1, no crash

Applying This Pattern to Your Agent

The cost curve is not SEO-specific. Any agent with mixed-complexity tasks can use it.

The principle: classify tasks by what they actually require before deciding which model to invoke.

Customer support agent:

• Tier 1: keyword matching for known FAQ topics — no model

• Tier 2: Haiku for intent classification on ambiguous queries

• Tier 3: Sonnet for complex complaints requiring judgment

Code review agent:

• Tier 1: lint rules, syntax checks — no model

• Tier 2: Haiku for common pattern detection

• Tier 3: Sonnet for architectural review

Content moderation agent:

• Tier 1: blocklist matching — no model

• Tier 2: Haiku for borderline cases

• Tier 3: Sonnet for context-dependent judgment

The implementation pattern is the same in all three cases. The audit_url() router becomes route_task(). The tier functions change their prompts and escalation conditions. The fallback logic stays identical.

The key question to ask before writing any agent code: what fraction of my inputs are mechanically solvable? That fraction goes to Tier 1. The rest escalate. The cost curve routes everything else.

Wrapping Up

The full implementation — including the SEO audit agent that uses this module in production — is at dannwaneri/seo-agent. The core/ directory is MIT licensed. The tiered routing lives in premium/cost_curve.py.

This tutorial is the companion piece to I Was Paying \(0.006 Per URL for SEO Audits Until I Realized Most Needed \)0 on DEV.to, which covers the architecture decisions behind the cost curve.

Most developers either rely on external tools or assume this requires backend processing. That’s usually where things get slower, more complex, and harder to maintain.

But modern browsers have quietly become powerful enough to handle this entirely on their own.

In this tutorial, you’ll build a barcode generator that runs completely in the browser. It won’t upload data anywhere, and it won’t require any server logic. Everything happens instantly on the client side.

Along the way, you’ll also learn how barcode formats work, how to validate inputs properly, and how to create a real-time preview experience that feels responsive and practical.

Table of Contents

1. How Barcode Generation Works

2. Project Setup

3. What Library Are We Using?

4. Creating the HTML Structure

5. Adding JavaScript for Barcode Generation

6. How the Barcode Is Generated

7. Types of Barcodes You Can Generate

8. Adding Real-Time Preview

9. How to Validate Input Properly

10. How to Download the Barcode

11. Important Notes from Real-World Use

12. Common Mistakes to Avoid

13. Demo: How the Barcode Generator Works

14. Conclusion

How Barcode Generation Works

A barcode is simply a visual encoding of data. Instead of displaying text directly, it represents that data using a pattern of lines and spaces.

Different barcode formats use different encoding rules. Some support only numbers, while others allow full text input. When you generate a barcode in the browser, you’re essentially converting user input into a structured visual pattern.

The key idea here is that we don’t draw these lines manually. A library takes care of encoding the data and rendering it as an SVG element, which the browser can display instantly.

Project Setup

We’ll keep this project intentionally simple so the focus stays on understanding how it works.

All you need is a basic HTML file, a small JavaScript file, and a barcode library. There’s no backend involved, and nothing gets stored or uploaded.

This makes the tool fast, private, and easy to integrate into other projects.

What Library Are We Using?

In this project, we use the JsBarcode library.

It’s a lightweight JavaScript library that can generate barcodes directly inside the browser using SVG. It supports multiple formats and works without any external dependencies.

You can include it using a CDN:

<script src="https://cdn.jsdelivr.net/npm/jsbarcode@3.11.5/dist/JsBarcode.all.min.js"></script>

Creating the HTML Structure

The interface is simple but practical. It includes an input field where users can enter data, a dropdown to choose the barcode format, and a preview area where the barcode is rendered.

<input type="text" id="text" placeholder="Enter text or number">

<select id="format">
  <option value="CODE128">Code128</option>
  <option value="EAN13">EAN13</option>
</select>

<button onclick="generateBarcode()">Generate</button>

<svg id="barcode"></svg>

This structure is enough to handle input, display output, and connect everything through JavaScript.

Adding JavaScript for Barcode Generation

Now we'll connect the user input to barcode generation.

function generateBarcode() {
  const text = document.getElementById("text").value;
  const format = document.getElementById("format").value;

  if (!text) {
    alert("Please enter a value");
    return;
  }

  JsBarcode("#barcode", text, {
    format: format,
    width: 2,
    height: 100,
    displayValue: true
  });
}

This function reads the input, checks if it exists, and then generates the barcode using the selected format.

How the Barcode Is Generated

When you call the JsBarcode function, the library handles everything behind the scenes.

It encodes the input into a barcode standard, converts that into a pattern of lines, and renders it as an SVG element. Because SVG is vector-based, the barcode remains sharp even when resized.

All of this happens instantly in the browser, which is why the experience feels fast.

Types of Barcodes You Can Generate

Different barcode formats are used in different industries, and understanding them helps you build more practical tools.

1. Code128 is the most flexible format. It supports letters, numbers, and special characters, which makes it ideal for general-purpose use.

2. EAN-13 is commonly used in retail products. It works only with 13-digit numbers, so it requires strict validation.

3. UPC is similar to EAN and is widely used in billing systems, especially in the US. It also expects numeric input with a fixed length.

4. Code39 is simpler and supports uppercase letters and numbers, but it’s less compact compared to Code128.

5. ITF-14 is mostly used in logistics and packaging. It’s designed for numeric data and is common in shipping environments.

In most cases, starting with Code128 is the safest option unless you have a specific requirement.

Adding Real-Time Preview

One of the biggest improvements you can make to a tool like this is real-time feedback.

Instead of requiring users to click a button every time, you can generate the barcode as they type.

document.getElementById("text").addEventListener("input", generateBarcode);
document.getElementById("format").addEventListener("change", generateBarcode);

This small change makes the tool feel much more responsive.

As soon as the user types or changes the format, the barcode updates automatically. This is the same kind of interaction you see in polished production tools.

How to Validate Input Properly

Validation is where many simple tools break.

Since different barcode formats have different rules, if you don’t validate input correctly, the barcode may fail silently or produce incorrect output.

Here’s a simple example:

function isValidInput(text, format) {
  if (format === "EAN13") {
    return /^\d{13}$/.test(text);
  }

  if (format === "UPC") {
    return /^\d{12}$/.test(text);
  }

  return text.length > 0;
}

Then use it inside your generator:

if (!isValidInput(text, format)) {
  alert("Invalid input for selected format");
  return;
}

This ensures users get immediate feedback instead of confusion.

How to Download the Barcode

Once the barcode is generated, you can allow users to download it.

function downloadBarcode() {
  const svg = document.getElementById("barcode");
  const serializer = new XMLSerializer();
  const source = serializer.serializeToString(svg);

  const blob = new Blob([source], { type: "image/svg+xml" });
  const url = URL.createObjectURL(blob);

  const link = document.createElement("a");
  link.href = url;
  link.download = "barcode.svg";
  link.click();
}

This converts the SVG into a file that can be downloaded directly from the browser.

Important Notes from Real-World Use

When building tools like this in production, small details matter.

Large input values can sometimes affect readability, so it’s important to test how dense the barcode becomes. Choosing the right format also makes a difference depending on whether you need flexibility or strict standards.

Another important detail is rendering quality. Using SVG instead of raster formats ensures that the barcode remains sharp even when printed.

Common Mistakes to Avoid

One common issue is skipping validation. This leads to broken or unreadable barcodes, especially with strict formats like EAN or UPC.

Another mistake is relying too much on button-based interactions. Real-time updates create a much better user experience.

Finally, developers sometimes forget to include the library correctly, which leads to silent failures. Always verify that your CDN is loaded.

Demo: How the Barcode Generator Works

To better understand how everything comes together, here’s a quick walkthrough of how the tool works in the browser.

Step 1: Select a Barcode Type

Start by choosing the barcode format. In most cases, Code128 is a good default since it supports both text and numbers.

Step 2: Enter Your Data

Next, enter the value you want to encode. This could be a product ID, URL, or any text depending on the selected format.

Step 3: Customize the Design

You can adjust things like bar width, height, and colors. These settings help control how the barcode looks and how readable it is in different use cases.

Step 4: Generate and Preview

As you type or change settings, the barcode updates instantly. This real-time preview makes it easier to experiment and see results immediately.

Step 5: Download the Barcode

Once you're satisfied with the result, you can download the barcode in formats like PNG, JPG, or SVG.

This entire process happens in the browser, without uploading any data to a server.

Conclusion

In this tutorial, you built a browser-based barcode generator using JavaScript.

More importantly, you learned how to think about building tools that run entirely on the client side. This approach reduces complexity, improves performance, and gives users a faster experience.

Once you understand this pattern, you can apply it to many other tools like QR generators, image converters, and file processors.

And that’s where things start to get interesting.

Agent skills fix this. A skill is a markdown file that loads into Claude Code's context automatically when you need it. You write the workflow once. The agent follows it every time. And because skills follow an open standard, the same file works in Claude Code, GitHub Copilot, Cursor, and Gemini CLI.

This tutorial shows you how to build a skill from scratch. You will build a commit-message-writer — a skill that reads your staged changes and generates a structured commit message following the Conventional Commits standard. By the end, you will have a working skill installed and ready to use, and you will understand the structure well enough to build any skill you need.

Table of Contents

1. What an Agent Skill Is

2. How to Choose What to Build

3. How to Structure Your Skill

4. How to Write the Description

5. How to Write the Instructions

6. How to Build the commit-message-writer Skill

7. How to Install and Test Your Skill

8. How to Improve Your Skill Over Time

9. Where to Go Next

What an Agent Skill Is

A skill is a folder containing a SKILL.md file. That file has two parts: a YAML frontmatter block at the top, and a markdown body below it.

my-skill/
└── SKILL.md

The frontmatter tells the agent what the skill is called and when to use it. The body tells the agent what to do when it loads the skill. Here is the minimal structure:

---
name: my-skill
description: What this skill does and when to use it.
---
 
# My Skill
 
Instructions for the agent go here.

When you invoke a skill — either explicitly with /skill-name or by describing what you want — the agent reads the SKILL.md body and follows the instructions inside it. The frontmatter never reaches the agent's instructions. It's metadata the skill system uses to decide whether to load the skill at all.

How the Agent Decides to Load a Skill

This is the most important thing to understand before you write your first skill: the agent decides whether to load your skill based entirely on the description field.

Skills appear in Claude Code's context as a list of names and descriptions. When you make a request, the agent scans that list and loads any skill whose description matches what you're asking for. If the description is vague, the skill won't load when you need it. If the description is too narrow, it won't load for variations of the same request.

The instructions in the body only matter after the skill loads. Getting the description right is what determines whether the skill loads at all.

What Skills Are Not

Skills are instruction files. They cannot run code on their own — but they can instruct the agent to run code using its existing tools. They are not plugins, extensions, or packages. They have no runtime. They are markdown files the agent reads, like a recipe a chef follows.

How to Choose What to Build

The best skills share three properties.

1. They encode a repeatable workflow. If you do something differently every time, a skill won't help. If you follow the same steps every session — even if you explain them differently each time — that's a skill candidate.

2. They have a clear trigger. You should be able to finish the sentence "I need this skill when I want to...". If you can't finish that sentence in one clause, the workflow isn't scoped enough for a skill.

3. They produce a consistent output format. Skills that output in a fixed structure — a commit message, a code review, a spec — are easier to build and test than skills that produce open-ended prose.

Good candidates: commit messages, pull request descriptions, code reviews, changelog entries. Bad candidates: "help me think through this", "make this better" — too open-ended to encode in a skill.

For this tutorial, commit message generation is the right scope. The trigger is obvious (you want to commit), the workflow is defined (read staged changes, apply Conventional Commits format), and the output is structured (a commit message with a specific shape).

How to Structure Your Skill

Every skill starts as a single folder with a single file:

commit-message-writer/
└── SKILL.md

As skills grow, they can include additional files the agent loads as needed:

commit-message-writer/
├── SKILL.md          ← always loaded when skill triggers
└── references/
    └── examples.md   ← loaded only when the agent needs examples

The SKILL.md body should stay under 500 lines. If your instructions are growing beyond that, move supporting detail into a references/ subfolder and tell the agent when to read those files. This keeps the skill lean — the agent only loads what it needs.

For this tutorial, a single SKILL.md is enough.

How to Write the Description

The description field is the trigger condition. It determines when your skill loads and when it doesn't. Most skills fail not because the instructions are wrong, but because the description doesn't match how people actually ask for help.

Here is a weak description:

description: Generates commit messages.

This will undertrigger. "Generate a commit message" will load it. "Write a commit for my changes" probably won't. "Summarize my staged diff" definitely won't — even though all three are asking for the same thing.

Here is a stronger description:

description: Generates structured commit messages following the Conventional Commits standard. Use when you want to commit your changes and need a well-formatted message. Triggers on "write a commit message", "commit my changes", "summarize my staged diff", "what should my commit say", or any request to describe or document code changes for version control.

The pattern is: what the skill does + when to use it + specific trigger phrases. The trigger phrases cover the different ways a developer might ask for the same thing.

Two rules for descriptions:

Be specific about the output. "Generates commit messages" is vague. "Generates structured commit messages following the Conventional Commits standard" tells the agent and the user exactly what they'll get.

Be slightly pushy. The agent has a natural tendency to undertrigger skills — to handle requests itself rather than loading a skill. A description that explicitly lists trigger phrases counteracts this. You are not being redundant. You are training the trigger.

How to Write the Instructions

The body of SKILL.md is where you define what the agent does when the skill loads. Good instructions follow two principles.

Generate first, clarify second. The agent should produce output immediately rather than asking clarifying questions. If it needs to make assumptions, it should make them and flag them — not ask. Asking questions before producing output adds friction and loses the benefit of having a skill at all.

Define the output format explicitly. Don't say "write a good commit message." Say exactly what the structure is, what fields are required, what the character limits are. The more specific the output format, the more consistent the results.

Here is what weak instructions look like:

# Commit Message Writer
 
Look at the staged changes and write a commit message that describes what changed.

That will produce different results every time — different formats, different lengths, different conventions. It's not a skill. It's a prompt.

Here is what strong instructions look like:

# Commit Message Writer
 
Read the staged diff using `git diff --staged`. Generate a commit message
following the Conventional Commits standard.
 
Output format:
type(scope): short description under 72 characters
 
Body (if changes are non-trivial):
- What changed and why, not how
- One bullet per logical change
 
Footer (if applicable):
BREAKING CHANGE: description
Closes #issue-number

The agent knows exactly what to produce. The output will be consistent across sessions, across projects, and across agents that support the standard.

How to Build the commit-message-writer Skill

Now build it. Create the skill directory:

mkdir -p ~/.claude/skills/commit-message-writer

On Windows PowerShell:

Note: PowerShell uses backtick (`) for line continuation, not backslash.

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\commit-message-writer"

Create the SKILL.md file inside that directory. Here is the complete content:

---
name: commit-message-writer
description: Generates structured commit messages following the Conventional Commits
  standard. Use when you want to commit your changes and need a well-formatted message.
  Triggers on "write a commit message", "commit my changes", "summarize my staged
  diff", "what should my commit say", or any request to describe or document staged
  changes for version control.
---
 
# commit-message-writer
 
You generate structured commit messages from staged git changes.
 
## How to invoke
 
Run `git diff --staged` to read the staged changes. If nothing is staged, tell the
user and suggest they run `git add` first.
 
Generate first. Do not ask clarifying questions before producing the commit message.
If you need to make assumptions about scope or type, make them and note them after
the output.
 
## Output format
 
~~~
type(scope): short description
 
[body — optional, include if changes are non-trivial]
 
[footer — optional]
~~~
 
**Type** — choose one:
- `feat` — a new feature
- `fix` — a bug fix
- `docs` — documentation changes only
- `refactor` — code change that neither fixes a bug nor adds a feature
- `test` — adding or updating tests
- `chore` — build process, tooling, or dependency updates
 
**Scope** — the module, file, or area affected. Use the directory name or component
name. Omit if the change spans the entire codebase.
 
**Short description** — imperative mood, under 72 characters, no period at the end.
"Add user authentication" not "Added user authentication" or "Adds user authentication."
 
**Body** — what changed and why, not how. One bullet per logical change. Skip if the
short description is self-explanatory.
 
**Footer** — include `BREAKING CHANGE:` if the commit breaks backward compatibility.
Include `Closes #N` if it resolves a GitHub issue.
 
## Quality rules
 
- Never use "updated", "changed", or "modified" in the short description — be specific
- Never write "various improvements" or "misc fixes" — name what improved
- If more than three files changed across unrelated concerns, flag it:
  "These changes may be better split into separate commits: [list concerns]"
- The short description must be under 72 characters — count before outputting
 
## Example output
 
Input: staged changes adding a rate limiter to an API endpoint
 
~~~
feat(api): add rate limiting to /query endpoint
 
- Limits requests to 100 per minute per IP using Cloudflare's rate limit binding
- Returns 429 with Retry-After header when limit is exceeded
- Adds rate limit configuration to wrangler.toml
 
Closes #47
~~~

Save that file. The skill is built.

How to Install and Test Your Skill

Verify the File Exists

cat ~/.claude/skills/commit-message-writer/SKILL.md

You should see the full SKILL.md content. If you get an error, check the directory path.

Test the Skill

Open Claude Code in any git repository that has staged changes. Type:

/commit-message-writer

The agent will read your staged diff and produce a commit message following the format you defined.

You can also trigger it naturally:

write a commit message for my staged changes

what should my commit say

summarize my diff for git

All three should load the skill and produce a structured commit message. If the skill doesn't trigger on natural language requests, the description needs more trigger phrases — see the improvement section below.

Test Edge Cases

Test these cases before relying on the skill in production:

# Stage nothing, then ask for a commit message
git add -p  # stage nothing
# In Claude Code: "write a commit message"
# Expected: skill tells you nothing is staged and suggests git add

# Stage changes across unrelated files
git add src/api.ts src/styles.css README.md
# In Claude Code: "write a commit message"  
# Expected: skill flags that commits may be better split

How to Improve Your Skill Over Time

The first version of any skill is a draft. You improve it by observing where it produces inconsistent or wrong output, then updating the instructions.

When the Skill Undertriggers

If you type "summarize my changes for git" and the skill doesn't load, add that phrase to the description's trigger list:

description: ... Triggers on "write a commit message", "commit my changes",
  "summarize my staged diff", "summarize my changes for git", ...

The description is your primary lever for fixing triggering problems.

When the Output Format Drifts

If the agent starts producing commit messages that don't match your format — wrong type, missing scope, body in the wrong style — the instructions need to be more explicit. Add a concrete example that shows the failure and the correct output:

## Common mistakes to avoid
 
Wrong: "Updated the authentication flow"
Right: "refactor(auth): simplify token validation logic"
 
Wrong: "Fixed bugs"
Right: "fix(api): handle null response from upstream service"

Concrete counterexamples are more effective than abstract rules.

When the Scope Grows

If you find yourself wanting the skill to handle related tasks — reviewing commit messages, generating changelogs, writing PR descriptions — resist the urge to add everything to one skill. Build separate skills. Each skill should do one thing well. The Agent Skills standard is designed for composition, not for monolithic instructions.

Where to Go Next

The commit-message-writer covers the core pattern. The same structure works for any repeatable workflow.

Pull request descriptions follow the same shape — read the diff, apply a structure, produce consistent output. The trigger phrases are different ("write a PR description", "summarize my branch for review") and the output format adds sections for motivation and testing, but the SKILL.md structure is identical.

Code review checklists work well as skills when your team has a standard review process. The trigger is "review this code" or "check this PR", and the instructions encode whatever your team actually checks — security concerns, test coverage, naming conventions.

The commit-message-writer is the simplest skill architecture — instructions only. As your skills grow more specialized, two other patterns become useful.

The first adds a references/ directory: the voice-humanizer skill loads a CORPUS.md file containing the author's published writing, which the agent reads when it needs to check output against a specific style. The second adds quality rules and structured output formats that make results stricter and more consistent — that's the pattern spec-writer uses to surface assumptions inline. Each is the same SKILL.md structure at a different level of complexity.

Start with instructions only. Add references when the agent needs external context. Add output format rules when consistency matters more than flexibility.

The Agent Skills standard is supported in Claude Code, GitHub Copilot in VS Code, Cursor, and Gemini CLI. A skill you build once installs across all of them. The install path differs by agent:

The SKILL.md format is the same across all of them.

The commit-message-writer you just built is a working skill. The next one will take less time. By the third, you will start seeing workflows you repeat and immediately think: that should be a skill.

That's the point.

The tool is spec-writer: a Claude Code skill that takes a vague feature request and generates a structured spec, technical plan, and task breakdown before a single line of code gets written.

The problem it solves is one most developers hit within their first week of using AI coding agents seriously: the agent writes confidently in the wrong direction and you pay for it twice, once in tokens, once in rewrites.

This tutorial shows you how to install spec-writer, how to invoke it on a real feature, and how to read the output so you can catch the assumptions that would have wasted your time.

Table of Contents

1. The Problem with Prompting Agents Directly

2. What Spec-Driven Development Is

3. How spec-writer Works

4. How to Install spec-writer

5. How to Write Your First Spec

6. How to Read the Output

7. How to Hand the Spec to Your Agent

8. Where to Go Next

The Problem with Prompting Agents Directly

Here is what happens when you skip the spec.

You have a feature in your head: "Add a way for users to export their data." You open Claude Code and describe it. The agent produces code. It looks right. You run it. It's mostly right – except it exports everything including soft-deleted records, it doesn't paginate, it times out on large accounts, and it has no authentication check on the export endpoint.

None of those things were in your prompt. The agent guessed, and it guessed plausibly – which is worse than guessing obviously wrong. You didn't notice until testing.

This is the fundamental problem with prompting agents directly on anything non-trivial: your prompt carries your conscious requirements, but every feature has a shadow of requirements you didn't think to state. And the agent fills that shadow with assumptions.

Most of the time, those assumptions are reasonable. Some of the time, they're wrong in ways that take hours to unravel.

The failure mode isn't hallucination. It's the agent being exactly as helpful as the prompt allowed, which wasn't helpful enough.

Spec-Driven Development addresses this directly. The methodology – documented extensively by practitioners like Julián Deangelis – argues that a written spec isn't documentation overhead. It's the mechanism that forces you to make decisions before the agent does.

What Spec-Driven Development Is

Spec-Driven Development is the practice of writing a structured specification before you write code or prompt an agent. The spec defines what the feature must do, what assumptions are being made, and what tasks the implementation breaks into.

The key insight is what a spec is for. A spec is not trying to replace code. It's trying to surface the decisions that would otherwise be invisible. The agent will make those decisions either way: with a spec, you make them first. Without a spec, you discover them during testing.

The strongest counterargument to SDD comes from Gabriella Gonzalez: a sufficiently detailed spec is just code. She's right that some specs devolve into pseudocode so specific they might as well be implementations.

But that's a spec written at the wrong level of abstraction. The goal is to name the decisions, not to pre-implement them. "Only authenticated users can trigger this export" is a decision. "Call verifyJWT(token) and return 401 if it fails" is implementation. The spec needs the first. The agent handles the second.

SDD has three levels:

1. Spec-First: write a spec before every feature and hand it to the agent as context. This is the entry point and the workflow this tutorial focuses on.

2. Spec-Anchored: the spec lives in the repository and evolves alongside the code. When requirements change, you update the spec and re-prompt the agent to realign.

3. Spec-as-Source: the spec is the primary artifact. Code is generated from it and considered disposable. This is the most ambitious level and the direction many teams are moving toward.

spec-writer gets you to Spec-First immediately, with no ceremony.

How spec-writer Works

spec-writer is a Claude Code skill – a markdown file that loads into the agent's context and changes how it responds when invoked.

The skill follows one rule: generate first, flag assumptions inline. Instead of asking you clarifying questions before producing output, it generates the full spec immediately and marks every decision it made without your explicit input using [ASSUMPTION: ...] tags. Then you correct what's wrong.

This is faster than Q&A because it makes the decisions visible in a form you can react to rather than anticipate.

The output has three sections in fixed order:

1. SPEC: the what. One-line purpose, user stories, requirements, edge cases, and acceptance criteria in Given/When/Then format.

2. PLAN: the how. Stack and architecture decisions, data model changes, API contracts, testing strategy, and security constraints.

3. TASKS: the breakdown. Ordered, self-contained tasks each completable in a single agent session, each with its own acceptance criteria.

After the three sections, the skill produces an Assumptions summary: every [ASSUMPTION: ...] from the output, ranked by impact. This is the part you review before handing anything to the agent.

The skill is compatible with GitHub Spec Kit and OpenSpec. If you use either framework, save the spec output to your .specify/ or openspec/changes/ directory and continue from there.

How to Install spec-writer

spec-writer uses the Agent Skills standard, which means the same SKILL.md file works across Claude Code, Cursor, GitHub Copilot, Gemini CLI, and any other agent that supports the standard. You install it once and it works everywhere.

Installation

Create the skills directory if it doesn't exist and clone the repo:

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/spec-writer.git ~/.claude/skills/spec-writer

On Windows PowerShell:

(Note: PowerShell uses backtick (`) for line continuation, not backslash.)

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/spec-writer.git "$HOME\.claude\skills\spec-writer"

That's the entire installation. No package to install, no configuration file to edit, no API key. The skill is a markdown file. The agent reads it.

Verification

Open Claude Code and type:

/spec-writer test

If the skill is installed correctly, the agent will read the SKILL.md and produce a spec structure – even for "test" as input. You'll see the three sections and the Assumptions summary. If nothing happens, confirm that the ~/.claude/skills/spec-writer/SKILL.md file exists.

How to Write Your First Spec

The invocation pattern is:

/spec-writer [your feature description]

The description can be as rough as you'd write in a Slack message. The skill's job is to structure it. You don't need to be precise. Being precise is what the spec is for.

A Real Example

Here is a real invocation from the Foundation project, a federated knowledge base built on Cloudflare Workers:

/spec-writer Add CLI capture for Claude Code sessions stored in ~/.claude/projects/

That's twelve words. No mention of the tech stack, no data model details, no authentication requirements, no error handling spec. All of that comes out in the spec.

Here is the abbreviated output:

SPEC

One-line purpose: Developers can capture Claude Code session logs from their local filesystem into Foundation before they are deleted after 30 days.

Users and use cases:

• As a developer using Claude Code daily, I want my coding sessions captured automatically so that architectural decisions and debugging patterns don't disappear after 30 days.

• As a Foundation user, I want CLI sessions and browser extension captures in the same knowledge base so that I have one place to query across all my AI interactions.

Acceptance criteria:

Given a developer with Claude Code sessions in ~/.claude/projects/
When they run the Foundation CLI capture command
Then a list of uncaptured sessions is displayed, sorted by most recent first
 
Given a session already in Foundation
When the developer runs capture again
Then that session does not appear in the review list
 
Given a malformed .jsonl file
When the capture command processes it
Then an error is logged for that file and processing continues on remaining sessions

PLAN

Stack and architecture:

CLI capture runs locally — it needs to read the local filesystem, which
Cloudflare Workers cannot do. [ASSUMPTION: CLI capture is a local Node.js
or Bun script that calls the Foundation API to insert sessions, rather
than a Worker itself]

API contracts:

• POST /api/sessions/import – accepts parsed session JSON, returns session ID

• Returns 409 if session already exists

• Triggers evaluator pipeline after successful insert

TASKS

## Task 1: .jsonl parser
 
**What to build:** A parser that reads a Claude Code .jsonl session file
and outputs Foundation's internal message format.
**Files likely affected:** cli/src/parsers/claudeCode.js (create)
**Acceptance criteria:**
1. Parses a valid .jsonl file into the correct message format
2. Handles malformed lines without crashing — logs and skips
3. Returns empty array for empty file
**Dependencies:** none

Assumptions to review:

1. CLI capture is a local script calling the Foundation API, not a Worker
   Impact: HIGH
   Correct this if: you want a purely serverless approach
 
2. Manual curation before capture, not automatic bulk import
   Impact: HIGH
   Correct this if: you want automatic background capture
 
3. Session ID from .jsonl filename is the deduplication key
   Impact: MEDIUM
   Correct this if: session IDs are stored differently in your schema
 
4. No sensitive data scrubbing in v1
   Impact: MEDIUM
   Correct this if: your sessions contain credentials or keys

Twelve words in, four decisions surfaced immediately – three of which had real architectural implications.

The third assumption ("Session ID from .jsonl filename is the deduplication key") is the one that would have caused the most subtle bug. The agent would have implemented deduplication based on the filename and it would have worked until a session was renamed. The spec caught it before a line of code was written.

How to Read the Output

The output is designed to be scanned for [ASSUMPTION: ...] tags first, read for the tasks second.

Reading the Assumptions

Every [ASSUMPTION: ...] tag marks a place where the agent filled in something you didn't specify. Your job is to go through the Assumptions summary and decide for each one:

• Correct: the assumption is right, leave it

• Override: the assumption is wrong, restate it and re-run the spec

• Defer: the assumption doesn't matter for this iteration, mark it and move on

The impact rating tells you which assumptions to fix before you start coding. HIGH-impact assumptions affect architecture or data model. If they're wrong, fixing them requires rework. LOW-impact assumptions affect behavior details that are easy to change later.

Reading the Acceptance Criteria

The acceptance criteria in Given/When/Then format are the most useful part of the spec for catching scope errors. Read each one and ask: is this actually what I want?

Criteria are binary by design. "Returns 401 when unauthenticated" is a criterion. "Works correctly" is not. If you find yourself reading a criterion and thinking "well, it depends", then that's a signal that the criterion is hiding an assumption. Restate it.

Reading the Tasks

The tasks are ordered and self-contained. Each task produces a verifiable change. Before you hand any task to an agent, check two things:

1. Does the task have all the context it needs? If a task says "follow the existing auth pattern" and you haven't pointed the agent at your auth code, it will guess.

2. Does the acceptance criteria match what you'd actually test? If the criteria are vague, tighten them before the agent sees the task.

How to Hand the Spec to Your Agent

The spec is context, not a prompt. When you start an agent session for a task, include the relevant spec sections alongside the task description.

For Task 1 from the example above, your agent session might open like this:

Context:
- This is a federated knowledge base built on Cloudflare Workers, D1, and Vectorize
- Sessions are stored in ~/.claude/projects/ as .jsonl files
- The API runs at https://<your-worker>.workers.dev
 
Spec:
[paste the SPEC and PLAN sections]
 
Task:
[paste Task 1]

The context block is just an example. Replace it with your own project's tech stack, file locations, and API URL. The point is to give the agent the same context a new team member would need on day one.

The agent now has requirements, architecture context, and a single scoped task with binary acceptance criteria. It cannot guess the deduplication key incorrectly because the spec already resolved that assumption. It cannot skip error handling because the acceptance criteria explicitly require it.

This is the workflow the spec is designed for. The spec doesn't replace the agent. Rather, it removes the decisions from the agent's hands and puts them in yours, before the work starts.

Saving the Spec for Later

If you want to move toward Spec-Anchored development – where the spec lives in the repository – save the output to a specs/ directory in your project:

# Create specs directory
mkdir -p specs
 
# Save your spec
# Paste the output into specs/cli-capture.md

When requirements change, update the spec and re-prompt the agent to realign the implementation. The spec becomes the source of truth, not the code comments.

Where to Go Next

Try it on your next feature before you write a line of code. The assumptions it flags will tell you something about your feature you hadn't consciously decided yet – and correcting the HIGH-impact ones before you hand anything to an agent is the whole point. Skipping that step is the same as prompting directly.

If your project is growing, move toward Spec-Anchored. Save specs in your repository under specs/. When a new contributor joins or an agent starts a session cold, the specs give them the decisions that got made without requiring them to reverse-engineer the code.

The strongest ongoing challenge to this workflow is Gabriella Gonzalez's argument that detailed specs become code. If your specs are getting implementation-specific, you've crossed a line. Pull back to decisions – "only authenticated users can trigger this" – and leave implementation to the agent. The spec's job is to name what the agent would have guessed wrong, not to write the feature in prose.

The Agent Skills standard now works across Claude Code, GitHub Copilot, Cursor, and Gemini CLI. The spec-writer repo is at github.com/dannwaneri/spec-writer.

The irony of spending 64% of a Claude budget building a token-efficiency tool is real. But the spec surfaced four decisions on a twelve-word prompt. The fourth one – the deduplication key assumption – would have produced a bug that worked perfectly until a session got renamed.

That's not a hallucination. That's the agent being exactly as helpful as the prompt allowed.

The spec is how you raise the ceiling on what "helpful" means.