F26 · COMP 523

Architecture

How the pieces fit together, what we are building, and what we are adapting to. Below the diagram is our system metaphor.

For a walkthrough of the system, see the project presentation.

Library Navigator architecture diagram A client-server web application. Patrons and librarians use a React interface in a web browser, which communicates over the Internet with a Node.js application server. The server holds a Python AI service for retrieval and guardrails, a Drizzle ORM data access layer, and a PostgreSQL database. Three pre-existing systems sit outside our work: the library resource websites patrons are guided to, the curated dataset supplied by the client, and an external LLM provider. Library Navigator Client-server web application. Responsive browser front end, all data and model access on the server. Deployed to a hosting provider (PaaS). Provider not yet selected. CLIENT the user's own web browser desktop, tablet, phone React single-page UI JavaScript, HTML FRONT END VIEWS Patron view Ask a question, enter a ZIP code,read cited answers, follow guidedsign-in steps. Librarian view Admin panel: add, edit, overrideentries, work the review queue. Internet HTTPS SERVER Application server (Node.js) REST API, session handling, librarian authentication. Model API keys andpermission checks live here and are never sent to the browser. Data access Drizzle ORM. Type-safe SQL across the 40fields on every record. PostgreSQL 467 resource records, audit log, reviewqueue. AI service (Python) Retrieval over the curated dataset, scopedto the library system that serves the user'sZIP code. Scores its own confidence,attaches citations, and refuses to answerwhen confidence is low. PRE-EXISTING SYSTEMS AND DATA Not our work. Our system has to adapt to each of these. Library resource websites NC LIVE, Libby, Hoopla, and individualcounty library systems. We do not controltheir pages or their login flows, so ourguided steps have to track whatever theydo. Patron ends up here, signed in. Curated library dataset Spreadsheet from the client's researchteam, delivered on OneDrive. 467 rows,100 counties, 90 systems, 413 outlets,about 40 columns each. Still being corrected, so this load runs again each revision. LLM provider An external model API, or the localmodel on the hardware our client hasoffered us. Provider not yet chosen,so the AI service keeps it behind oneswappable interface. patron follows our steps, then signs in loaded into the database prompt and response Built by our team Already exists, we adapt to it Data flow Network boundary. Traffic crosses the public Internet, far slower than anything inside one machine.
Library Navigator is a client-server web application. Everything inside a solid navy outline is ours to build. Everything in a dashed outline already exists and we have to work with it as it is.

What kind of system this is

A client-server web application, which is the ordinary shape for something like this and we are not trying to be clever about it. There is no phone app to install and nothing to download. A patron opens a browser, and a React interface runs there. Everything that matters, the library data and the calls to the language model, happens on a server they never see.

That split is not a style preference. Our model API credentials cannot sit in the browser where anyone can read them, and the check for whether someone is actually a librarian has to happen somewhere a user cannot edit. Both of those force a server.

How a question moves through the system

A patron types a ZIP code and a question. That request crosses the Internet to the Node.js application server, which is the only door into the system.

The server resolves the ZIP code to a county and a library system, then hands the question to the Python AI service. That service searches the dataset in PostgreSQL, narrowed to what that particular library system actually carries, and asks the language model to answer using only what it found. It scores how confident it is. High confidence goes back as a direct answer with its source attached. Low confidence does not get dressed up as an answer; the patron is told plainly and pointed at a librarian, and the question is written to a review queue.

Then the part that usually gets skipped. The answer is a set of steps, and the patron follows them to a site we do not own, NC LIVE or Libby or their county library. We cannot control those pages, so the steps have to be maintained against whatever those sites do next. That is the arrow leaving the bottom left of the diagram.

What we inherit

Three things in this system are not ours, and each one constrains us.

The dataset comes from our client's research team as a spreadsheet on OneDrive. It is still being corrected, so loading it is a job we will run again every time she sends a new version.

The library websites are the actual destination for most answers. Their login flows change without telling us, and a dead link in our dataset turns into a patron stuck at a page that does not work.

The language model is a provider we have not picked yet. Our client has offered us hardware with a local model on it, and cost may decide the question. So the AI service keeps the model behind one interface, and swapping providers should be a day of work rather than a rewrite.

Our XP-style system metaphor, the reference desk, lives on its own page: System Metaphor.