Week 10 full-stack milestone

Why this matters

Six days ago you had a React app full of invented data and an API nobody called. Today you prove they are one product: a technician logs in, finds a machine, records a repair, and logs out — and every one of those actions survives a restart of everything involved.

Then you explain it, out loud, without notes. That second half is not a formality. Being able to narrate a system is the difference between having built it and having assembled it, and it is what every technical interview and every handover is actually testing.

Integration regression

A regression is behaviour that used to work and no longer does. Integration weeks produce them in quantity, because every day changed something two other days depended on.

Yours are already sitting there. Day 68 changed the equipment response from a bare array to { data, page, limit, total } — any screen still doing response.map(...) is broken. Day 66 added credentials: 'include'; any request that skipped it now returns 401 in a place that used to work. Day 67 wrapped two writes in a transaction; if the status update throws, the record insert now disappears too, which is correct and also different.

The lesson is the one this week's analogy has been making all along: every module passing its bench test is not evidence that the assembled unit works. Modules were tested against your assumptions about their neighbours. Integration is where the assumptions get compared.

The tool is a regression checklist: the same ordered sequence of user actions with an expected observation for each, run in one sitting, top to bottom, after any change to a shared boundary. Write it once and reuse it. Week 11 replaces it with automated tests — which is much better, and which you will only be able to write well because you did it manually first and know what it is checking.

Data persistence

"It works" is a claim about a moment. "It persists" is a claim about the future, and it is the one that matters. Your app currently keeps state in four places with four different lifetimes:

Where	Survives a re-render	Survives reload	Survives a restart	Sharable
React state	yes	no	no	no
The URL query string	yes	yes	yes	yes
The session cookie	yes	yes	yes, until it expires	no (and must not be)
PostgreSQL	yes	yes	yes	yes

A demo that only ever exercises the first row proves nothing, and it is very easy to do by accident: you create a machine, it appears on screen from React state, and you conclude it saved. The row may never have reached the database.

So the acceptance test for persistence is a power cycle. Stop the API. Stop PostgreSQL. Start them both. Reload the browser. Everything the user created must still be there, attached to the right machine, with the same values. Anything that vanishes was never persisted — it was displayed.

Explaining the system

Five minutes, no notes. Use this structure — it is the same order as your data flow, so you cannot get lost:

1. What it is for. One sentence about the user and their problem. "Technicians record what they did to a machine, and anyone can see a machine's history."
2. The runtime picture. Three processes: a browser running your React bundle, an Express process on port 3000, a PostgreSQL process on 5432. Name what talks to what, and over what.
3. One request, end to end. Take the walk you wrote on Day 64: click → apiFetch → HTTP → route → service → repository → SQL → rows → JSON → state → screen.
4. Where the boundaries are and what guards them. Two origins and the CORS configuration between them. An httpOnly cookie carrying the session. Server-side authentication and authorization, with the frontend guards named as UX only. Validation on the server, mirrored on the client for speed.
5. What is true only locally. Be explicit about the assumptions your current setup makes, so nobody mistakes it for a deployed product.

That last point is worth writing down properly, because it is Week 11's agenda:

• The Vite dev server is a development server. Production serves built static files instead.
• CORS names http://localhost:5173. A deployed frontend has a different origin.
• The session cookie is set without Secure locally; over the public internet it needs HTTPS.
• Database credentials come from your local environment; nothing is set up to manage them elsewhere.
• There is no automated test suite yet guarding any of this, and no DNS, TLS, or hosting.

Naming a limitation you have not fixed is not a weakness in an explanation. It is the strongest signal that you understand the system, and it is what a reviewer listens for.

Walkthrough: the acceptance run

Do this in one sitting, in this order, writing pass or fail beside each line. Start from a genuinely cold system.

# 1. Cold start: confirm PostgreSQL is running, then start both apps
psql -c 'SELECT 1;'        # macOS: brew services list   Linux: systemctl status postgresql
npm run dev                # frontend, in one terminal
npm run dev                # API, in another (whatever script your API uses)

#	Action	Expected observation
1	Open the app while logged out	Redirected to /login, no console errors
2	Log in with a wrong password	One generic error, no hint about which field was wrong
3	Log in correctly	Equipment list loads; DevTools shows 200 for /api/auth/login
4	Reload the page	Still logged in; GET /api/auth/me returns 200
5	Search and page through the list	URL query string updates; results match the header count
6	Copy the URL into a new tab	Identical filtered view
7	Open a machine	Detail and maintenance history load; empty history says so
8	Submit the log form with a required field blank	Server 400; the message appears beside that field; nothing typed is lost
9	Submit it correctly	Record appears and the machine's status updates together
10	Double-click Save on a new record	Exactly one row in the database
11	Stop the API, click something	A clear error state, not a permanent spinner
12	Restart the API and PostgreSQL, reload	All created data still present and correctly attached
13	Log out, then press Back	Not logged back in; protected pages redirect

Your turn

1. Cold-start everything and run all thirteen steps, recording pass or fail. Do not fix anything until the whole run is finished — you want the complete picture, not the first fault.
2. Fix the failures, then run the entire checklist again from step 1. A partial re-run is how regressions survive.
3. Save the checklist as docs/regression-checklist.md. You will run it again in Week 11.
4. Draw the runtime architecture on one page: the three processes, the ports, the two origins, the protocol on each arrow, and where the session cookie lives. Mark the two boundaries you drew on Day 1 and label what enforces each.
5. Under the diagram, list the deployment assumptions from this lesson that are true only on your machine.
6. Record yourself explaining the system for five minutes using the five-point structure. Watch it back. Note every place you reached for a file to remember something.
7. Commit the working application with a message that says what the milestone is.

Common pitfalls

• Demoing without a cold start. The API has been running for two hours holding state you cannot see. Restart everything before you believe a result.
• Testing only the happy path. The signed-out path, the validation failure, and the API-down case are where users actually live.
• Fixing as you go during the run. You lose the overall picture and usually re-break an earlier step without noticing.
• Explaining with the code open. If you need the file to say what happens next, you have not yet got the model — and the file will not be there in the conversation that matters.

Verify it yourself

Open today's reference, MDN's How the web works, and compare its picture to the diagram you just drew.

1. MDN's version includes parts your local setup does not have at all — start with DNS. List every component in their diagram that has no counterpart on your machine, and say what stands in for it locally.
2. Find where MDN describes what a web server does with a request. Does your Express process do the same job, or a different one? Say precisely where the two descriptions diverge.

Add both answers beside your architecture drawing. On Day 1 you drew this diagram with no idea how any of it worked and were asked to add DNS to it. Doing that again now, with a running system underneath, is a fair measure of how far ten weeks has taken you.