AI support copilot project (TypeScript) · Chapter 1 of 12
The plan and the pages
By the end of this chapter you know what Parda's support copilot will do and how its parts fit, you can read Parda's help pages from their files into TypeScript (title, header lines, body), leave out a page that a newer one replaced, and measure the pages in tokens, the unit a model reads and charges by. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: The pages
- 3 tasks
- TypeScript
- Free chapter
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.
Why you need this
Parda sells tickets for twelve of Pune's own cinemas and stages. Members ask the same questions all day on WhatsApp: my show was cancelled, when do I get my money back; can I change my seats; is there a ramp at Kala Talkies; does my two-year-old need a ticket; can I bring food to Sahyadri Lawns. Datta, who runs support and the box office, answers about 200 of them on a weekday, by hand, from Parda's help pages. Last week he told a member that the booking fee is ₹35 a seat. It is ₹20: the ₹35 page was replaced on 1 October, but the old file is still in the folder. Diwali week starts on Friday 6 November, and the questions will double.
Sayali, the founder, wants a support copilot: an API that Parda's WhatsApp tool calls with a member's question. It answers from the help pages only, shows which page it used, and says "I don't know" when the pages do not say. Nikhil, Parda's senior backend engineer, builds it with you over twelve chapters. Every chapter starts from his finished code of the chapter before, so the project always runs.
Everything the copilot will ever say comes from the help pages, and right now nothing reads them. They are 38 markdown files in data/help. One of them is the old booking fee page, and a program that reads "every file" reads the ₹35 page too. Before any search or any model, the app has to know what a page is, which pages are current, and how big they are.
The lesson
Tour of the codebase
This is chapter 1, so everything is new. The whole app is in your chapter's folder; the one file marked as yours is the only one you edit.
package.json the packages and their versions; npm run dev
src/server.ts listens on port 3000
src/app.ts createApp(): the Express app and its routers
src/config.ts every setting the app reads (models, sizes, prices)
src/lib/tokens.ts countTokens(text), with js-tiktoken
src/lib/text.ts splitSentences(text) (chapter 2 uses it)
src/middleware/errors.ts one JSON shape for every error
src/db/client.ts the Postgres pool (only /health uses it for now)
src/modules/health/ GET /health
src/modules/pages/pages.routes.ts GET /pages, /pages/stats, /pages/:id: calls your functions
src/corpus/pages.ts yours: Page, parsePage, loadPages, corpusStats
data/help/ Parda's 38 help pages, one markdown file each
Start the app from the terminal:
$ npm run dev
> parda-copilot@1.0.0 dev
> tsx watch src/server.ts
Parda support copilot listening on http://localhost:3000
tsx runs TypeScript directly, with no build step, and watch restarts the server when you save a file. The saved request "Is the app up?" answers {"ok":true,"database":"up","counts":null}: there are no tables yet, chapter 3 makes them. "Every help page" answers 500 until you write Task 2, and the server's log, your terminal, says why:
Error: Task 2: loadPages is not written yet
at loadPages (/workspace/chapters/01-the-plan-and-the-pages/src/corpus/pages.ts:85:9)
at <anonymous> (/workspace/chapters/01-the-plan-and-the-pages/src/modules/pages/pages.routes.ts:16:12)
...
The plan
A model such as GPT knows a lot about the world and nothing about Parda's refund rules. Asked about them, it guesses, and a guess sounds exactly as sure as a fact. The fix is to give the model the right part of the help pages with the question, and tell it to answer from that part only. This is called retrieval-augmented generation, RAG: first retrieve, then generate. Nikhil's plan has three stages, and the chapters follow them:
- Prepare the pages (chapters 1 to 3): read them, cut them into small pieces called chunks, turn each chunk into numbers that capture its meaning, and store them in Postgres.
- Search (chapters 4 to 6): for a question, find the five chunks that answer it best.
- Answer (chapters 7 to 12): send those chunks and the question to the model, with each chunk's id, and get back an answer that cites them, streamed, guarded, checked and cheap.
This chapter is the first step of the first stage: the pages, as TypeScript objects.
A help page, line by line
Every page has the same shape:
$ head -7 data/help/booking-fee.md
# Booking fee
updated: 2026-10-01
tags: booking fee, fees, charges
supersedes: booking-fee-2025
This page explains Parda's booking fee: how much it is, when you pay it and when you get it back.
The first line is the title after # . Then come header lines, one key: value each, up to the first blank line: updated is on every page, tags on most, supersedes only on a page that replaces an older one. Everything after the blank line is the body. The given Page type holds those six things.
text.split('\n') cuts a text into lines (a blank line becomes ''), and line.startsWith('# ') tests a prefix. The interesting part is a header line. A value may hold a colon itself, so cutting at every colon is wrong, and JavaScript's split with a limit is a trap of its own:
> const line = "owner: Datta: box office"
undefined
> line.split(":")
[ 'owner', ' Datta', ' box office' ]
> line.split(":", 2)
[ 'owner', ' Datta' ]
> line.indexOf(":")
5
> [line.slice(0, 5), line.slice(6)]
[ 'owner', ' Datta: box office' ]
split(":") cut the value in two. split(":", 2) looks like the fix, but JavaScript's limit does not keep the rest of the line: it stops after two pieces and throws the rest away, silently. Find the first colon with indexOf and take the text before and after it with slice. Keys are compared in lower case, so Tags: and tags: are the same header; trim both sides, because people type spaces:
> " Kitchen ".trim().toLowerCase()
'kitchen'
A date is checked by its shape
updated is a date, and JavaScript's Date is too kind to be the judge:
> new Date("2026-10-01")
2026-10-01T00:00:00.000Z
> new Date("1 Oct 2026")
2026-10-01T00:00:00.000Z
> new Date("Tea time")
Invalid Date
Date accepts "1 Oct 2026" without a word, and the day it picks depends on the machine's time zone. So the app keeps updated as text, and only text of one shape is accepted: four digits, a dash, two digits, a dash, two digits. A regular expression says that exactly. ^ and $ pin it to the whole string, and \d{4} means four digits:
> /^\d{4}-\d{2}-\d{2}$/.test("2026-10-01")
true
> /^\d{4}-\d{2}-\d{2}$/.test("1 Oct 2026")
false
Postgres reads that text as a real date later (chapter 3), and ISO text sorts in date order, so nothing is lost.
Tags, and missing headers
Tags are a comma list, and splitting has a trap. A string with no commas still splits into one item, and an empty string splits into one empty item:
> "veg, jain , nut free".split(",")
[ 'veg', ' jain ', ' nut free' ]
> "".split(",")
[ '' ]
> "".split(",").map((t) => t.trim()).filter(Boolean)
[]
So a page with no tags line must give [], not ['']. filter(Boolean) keeps only the items that are truthy, and an empty string is not. A missing header is not an error in itself: reading headers.supersedes gives undefined, and the task wants null for "no such line", so write headers.supersedes || null.
A page that is broken (no title line, no updated, an updated of the wrong shape) should stop ingestion loudly, with the page's id in the message, so whoever edits the pages knows which file to fix: `throw new Error(${pageId}: ...). A bare TypeError: Cannot read properties of undefined` names no page at all.
A folder of pages
Node's fs module reads the files. readdirSync(folder) gives the names of the files in a folder, and readFileSync(path, 'utf8') reads one as text. Say the encoding: without it, you get a Buffer of bytes, and the pages are full of ₹, which is three bytes. join from node:path puts a folder and a name together with the right slash.
> readdirSync("data/help").filter((f) => f.startsWith("b"))
[
'bags-and-security.md',
'booking-fee-2025.md',
'booking-fee.md',
'box-office.md'
]
A page's id is its file name without .md. Keep only the names that end in .md: a notes.txt someone leaves in the folder is not a page. The order readdirSync gives is the file system's, which Node does not promise, so the result must be sorted by id. A stable order makes every later step repeatable.
Now the ₹35 problem. booking-fee.md says supersedes: booking-fee-2025. Datta keeps the old page in the folder on purpose, as a record of what members were told in 2025, but it must never reach a member. The rule is about the whole folder, not one page: you only know a page is replaced after you have read the page that replaces it. So read every page first, collect the ids that any page supersedes into a Set (you only ever ask "is this id in it?", which has answers at once), and keep the pages whose id is not in that set.
Tokens
A model does not read characters or words. It reads tokens, pieces of text from a fixed list of about 200,000, and everything about a model is counted in them: how much it can read at once, how fast it is and what it costs. src/lib/tokens.ts counts them with js-tiktoken and OpenAI's o200k_base list, the one the lab model uses too:
"Parda" 2 [ 'P', 'arda' ]
"Kala Talkies" 3 [ 'Kala', ' Talk', 'ies' ]
" ticket" 1 [ ' ticket' ]
"wheelchair" 2 [ 'wheel', 'chair' ]
"₹120" 2 [ '₹', '120' ]
That is each text, countTokens(text), and its tokens turned back into text (enc.encode gives the token numbers, enc.decode turns one back). Common English words are one token each, with their leading space, so countTokens("The booking fee is ₹20 per seat.") is 9. Words the list has seen less often, like Parda or Talkies, break into pieces. A rough rule for English is four characters a token, but only counting tells you.
To find the biggest page, keep the biggest seen so far and replace it only when a page is strictly bigger: with >, the first of two pages of the same size stays; with >=, the last one wins. An empty list never sets it, so it stays null.
Why not send every page
The pages are small, so why search at all? Nikhil tried the simplest copilot, a little script: every current page joined into one system message, then the question, sent with the openai package to the model named on the command line. The lab model has a window of 8,192 tokens:
$ npx tsx every-page.ts lab-chat
...
BadRequestError: 400 This model's maximum context length is 8192 tokens. However, your messages resulted in 8301 tokens. Please reduce the length of the messages.
lab requests shows what the model received: a system message of 35,521 characters and the question, then context_length_exceeded. The lab's lab-chat-large has a window of 131,072, and it answered:
$ npx tsx every-page.ts lab-chat-large
Sure. The Attic is up a flight of stairs and has no lift, so we cannot offer wheelchair access there. This page explains which venues a wheelchair user can reach and how to book a wheelchair space.
8301 read, 42 written
Right, with a sentence that answers nothing, and expensive. At its price of ₹1,000 a million tokens read and ₹4,000 a million written, that is about ₹8.47 for one answer, about ₹1,700 for Datta's 200 questions a day, to read 8,301 tokens for the one sentence that answered. The pages will also grow, and a model given more to read finds the right sentence less reliably. Searching first sends a few hundred tokens instead.
The lab's models are stand-ins that run inside the lab with no internet. lab-chat behaves like a real chat model in the ways that matter here (windows, prices, errors, answering from what it is given), but its sentences are picked from what it reads, not written. On your own machine, with the take-home of chapter 12 and your own OpenAI key, the same code talks to a real model.
Your turn
- Task 1,
parsePage(pageId, text): one page from its text. The trap: a header value can hold a colon, and a page with no tags line has no tags, not one empty tag. - Task 2,
loadPages(folder): every current page of a folder, by id. The trap: the ₹35 page must not come back. - Task 3,
corpusStats(pages): how many pages, their tokens, the biggest page. Nikhil will ask: the help pages are about 8,000 tokens in all. Why not send every page to the model with every question, instead of searching for the right parts?
With the app running, send "Every help page", "The pages in tokens", "The wheelchair access page" and "The old booking fee page" (which must answer 404). Then press Check. It parses made-up pages and Parda's own, and tells you the first thing that is not right yet. A header line cut at every colon gives:
the line "supersedes: old: page" gave supersedes "old"; cut a header line at its first colon only: "old: page"
And a folder read without the supersedes rule gives:
loadPages kept tea-old, which tea.md's supersedes line replaces: leave out every page another page supersedesWhat you build: 3 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
pages.ts: read one help page
Write parsePage(pageId, text) in src/corpus/pages.ts. It returns a Page from one help page's text.
The first line is the title ("# " then the title; title is the rest, trimmed). Header lines follow, "key: value", up to the first blank line: cut each one at its first colon only, trim and lower-case the key, trim the value. updated is the updated line's value, kept as text, and it must look like 2026-10-01 (four digits, a dash, two digits, a dash, two digits). tags is the tags line split on commas, each tag trimmed, the empty ones left out ([] when there is no tags line). supersedes is its value, or null when there is no such line. body is every line after that first blank line, joined with "\n" and trimmed. id is the pageId given.
Throw an Error whose message names the page's id when the first line does not start with "# ", when there is no updated line, or when updated is not in that form.
The Check parses a made-up page with a "Tags:" line and a header whose value holds a colon, a page with no tags line, data/help/booking-fee.md (it supersedes booking-fee-2025), and three broken pages.
- Task 2
pages.ts: load every page, without the replaced one
Write loadPages(folder) in src/corpus/pages.ts. Read every file of the folder whose name ends in .md as UTF-8 and parse it with parsePage; a page's id is its file name without ".md". Leave out every page whose id another page's supersedes names. Return the pages sorted by id.
The Check loads a made-up folder (tea.md supersedes tea-old.md, biscuits.md, and a notes.txt that is not a page) and data/help, where booking-fee supersedes booking-fee-2025 (the old page that says ₹35 a seat); then GET /pages must list the 37 current pages and GET /pages/booking-fee-2025 must answer 404.
- Task 3 · interview question
Interview: pages.ts, the pages in tokens
Write corpusStats(pages) in src/corpus/pages.ts. Return { pages, tokens, largest }: pages, how many pages there are; tokens, the tokens of all their bodies together, each body counted with the given countTokens; largest, { id, tokens } for the page whose body has the most tokens (when two are as big, the first of them in the list), or null when the list is empty.
The Check measures three made-up pages, two of the same size, then an empty list, then calls GET /pages/stats.
Nikhil will ask: the help pages are about 8,000 tokens in all. Why not send every page to the model with every question, instead of searching for the right parts?
What you will learn
- The plan: what a copilot that answers from documents does, in the order this project builds it.
- Reading a page: lines, a header of key: value lines, the first colon only, and why a date is checked by its shape instead of by Date.
- A folder of pages: readdirSync, readFileSync with an encoding, and leaving out a page another page supersedes.
- Tokens: what a model reads, how js-tiktoken counts them, and what the count means for a model's window and its price.
- Why not send every page: a real request that is too big.
More in The pages
Build The plan and the pages yourself
Parda answers the same audience questions all day. You build the copilot that answers them from its own help pages, with sources, and says so when it does not know. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.