How your reading list works.

You have a plan for what the app does. This part explains how it will do it. Architecture is the word for which parts a piece of software has, what each part is responsible for and how they talk to each other. You don’t need to build the parts yourself, but knowing them lets you understand the agent’s explanations, ask better questions and tell a sensible suggestion from an unnecessary one.

Two computers, two jobs

Every website involves at least two programs. A server is a program that waits for requests and sends files back. A browser, such as Chrome or Safari, asks for those files and turns them into the page you see. The browser is often called the client, because it is the one making requests.

When you opened the starter in Part 1, both were on your computer. The command npm run dev started a small server, and your browser asked it for the app at a localhost address. When you publish in Part 7, the server will be Netlify’s, somewhere on the internet. The arrangement stays the same.

In this app the server has one job: delivering the app’s files. Once your browser has them, the server takes no further part. It never sees your books.

What runs in your browser

The files the server delivers contain the whole app, and the browser runs it. It helps to think of three parts.

The interface is what you see and click: the list, the form, the buttons and Pip. In this project it is built with React, a widely used library for describing an interface as reusable pieces, such as “a book card”, that redraw themselves when information changes.

The logic is the code that decides how the app behaves. Developers call it application logic. It includes validation, which is checking input before accepting it: a title is required, and a status must be one of three values. It also includes behaviour: undo restores the most recently removed book, and search ignores capital letters. The logic is where the decisions in your plan end up. It is separate from the interface in a useful way: the same logic applies however the form happens to look, and it can be tested on its own, which Part 6 relies on.

The data is the list of books itself. While the page is open the list is held in memory, which is quick to use and forgotten as soon as the page closes or refreshes. To keep it, the app also has to save it somewhere that lasts.

Where the list is saved

Browsers provide each website with a small storage area called localStorage. An app can write text into it and read it back later, including after the page is refreshed, the browser is closed or the computer is restarted. Our app will save the list there after every change and load it on opening.

This is real persistence: the information outlives the page that created it. People sometimes describe localStorage as a lesser substitute for “proper” saving, which is misleading. The list is saved properly. What matters is where it is saved, because that determines what it can and cannot do:

• It belongs to one browser on one device. Books you add on your laptop will not appear on your phone.
• It belongs to one website address. The app at localhost and the published app on Netlify each keep their own separate list.
• It is not a backup. Clearing the site’s data in your browser settings deletes the list, and nothing can bring it back.
• It is private by default. Nobody else, including whoever hosts the site, receives your books.

For a personal reading list on one device, these are reasonable properties, and the app gets them with almost no complexity.

What this app leaves out

Many apps have a further part: an application backend. That is code running on a server which receives information from many people’s browsers and keeps it in a shared database. It is what makes it possible to sign in on a new phone and find your things waiting.

A backend is needed when information must be shared between devices or between people, or must be kept somewhere the user cannot tamper with, as with payments. It brings real work with it: accounts, passwords, rules about who may see what, running costs and responsibility for other people’s data. Our app needs none of that, so it has no backend, no accounts and no database service. Choosing not to add them is an architectural decision too, and a good one for a first project. If your agent ever proposes adding one of these to the reading list, you now know enough to ask what problem it would solve.

Ask your agent to show you

Agents are useful for explaining a project as well as changing it. Try this in your starter:

Read CLAUDE.md and docs/brief.md. Do not change any files. In plain language, show me where these three things will live in this project when it is built: the interface, the logic, and the saved list. Tell me which existing files belong to the interface now. Then explain what the development server does when I open the local URL, and what it does not do. Keep it short, and define any technical term you use.

Compare the answer with the diagram above. If it uses a word you don’t know, ask. You are not expected to open the files it mentions, though nothing stops you being curious.

FAQ

Next: Build your reading list.