1. Freeze the starting point

From the repository root, run:

git status
git log -1 --oneline

git status
git log -1 --oneline

If git status shows changes you made earlier, do not delete them. Note them in your scratch notes so you know which files belong to the current baseline.

Now list the project files without opening dependencies:

find . -maxdepth 3 \
  -not -path './node_modules*' \
  -not -path './.git*' \
  -type f | sort

find . -maxdepth 3 \
  -not -path './node_modules*' \
  -not -path './.git*' \
  -type f | sort

If find is unavailable, use your editor’s file tree instead.

Check: You should be able to identify whether this is:

• one package with both client and server code,
• a repository with separate client and server folders,
• or a workspace/monorepo with several packages.

Write that structure down in one sentence.

2. Read the scripts before running anything

Find every package.json:

find . -name package.json -not -path './node_modules/*' -print

find . -name package.json -not -path './node_modules/*' -print

Open each relevant file and inspect its "scripts" section. You can print the root one with:

node -e "console.log(JSON.stringify(require('./package.json'), null, 2))"

node -e "console.log(JSON.stringify(require('./package.json'), null, 2))"

For a nested package, replace the path with its location:

node -e "console.log(JSON.stringify(require('./path/to/package.json'), null, 2))"

node -e "console.log(JSON.stringify(require('./path/to/package.json'), null, 2))"

Make a small table in your notes:

Do not guess from script names alone. Read the command after each script name. For example, a script may call Vite, Nodemon, tsx, or a compiled dist file.

Check: You should know the exact command that starts the React side and the exact command that starts the Express side. If either is unclear, follow the command into the next file or tool configuration.

3. Trace the React entry point

Start with the script that launches the frontend. Look for a source folder containing files such as:

• main.jsx
• main.tsx
• index.jsx
• index.tsx
• App.jsx
• App.tsx

Use your editor’s “find references” or search for:

createRoot
<App
ReactDOM

createRoot
<App
ReactDOM

Your trace should look like this, with your actual filenames filled in:

frontend script: ______
        ↓
HTML entry: ______
        ↓
React entry file: ______
        ↓
root component: ______
        ↓
first visible page/component: ______

frontend script: ______
        ↓
HTML entry: ______
        ↓
React entry file: ______
        ↓
root component: ______
        ↓
first visible page/component: ______

Open the React entry file and identify:

1. Which DOM element receives the React application?
2. Which component is rendered first?
3. Is there a router, provider, or context wrapper?

Write down only the answers that apply to this project.

Check: Start the frontend using the project’s actual script. Then open the printed local URL in your browser.

Confirm:

• the page loads,
• the browser console has no immediate error,
• the first visible component matches the component you traced.

If it fails, copy the first error and fix only the startup problem before continuing. Do not refactor yet.

4. Trace the Express entry point

Now locate the backend script from package.json. Search for:

express()
app.listen
server.listen
app.use

express()
app.listen
server.listen
app.use

Trace the server in the same format:

backend script: ______
        ↓
server entry file: ______
        ↓
Express app creation: ______
        ↓
middleware registration: ______
        ↓
route registration: ______
        ↓
listen call and port: ______

backend script: ______
        ↓
server entry file: ______
        ↓
Express app creation: ______
        ↓
middleware registration: ______
        ↓
route registration: ______
        ↓
listen call and port: ______

Pay attention to whether the project separates the Express app from the file that calls .listen(). That distinction matters when testing an app without opening a real network port.

Record these details:

• port number or environment variable,
• JSON/body middleware,
• CORS setup, if present,
• route prefixes such as /api,
• static-file handling, if present.

Check: Start the backend using its actual script. Look for a startup message or a listening port.

If the project already has a health or test route, call it:

curl -i http://localhost:PORT/ROUTE

curl -i http://localhost:PORT/ROUTE

Replace PORT and ROUTE with the values you found.

If no route exists, do not invent one yet. Your check is simply that the server starts and remains running without crashing.

5. Trace one request end to end

Search the frontend for network calls:

fetch(
axios
/api
http://localhost

fetch(
axios
/api
http://localhost

Pick one request that the current app actually uses. Trace it through these questions:

1. Which component or function starts the request?
2. What URL and HTTP method does it use?
3. Does it send a body or headers?
4. Which Express route receives it?
5. What does the route return?
6. How does the React component use the response?

Write the path in this form:

User action or component effect:
  ______

Frontend request:
  method ______
  URL ______

Express route:
  method ______
  path ______
  handler ______

Response:
  status ______
  JSON/body shape ______

React result:
  state updated/rendered by ______

User action or component effect:
  ______

Frontend request:
  method ______
  URL ______

Express route:
  method ______
  path ______
  handler ______

Response:
  status ______
  JSON/body shape ______

React result:
  state updated/rendered by ______

If the current app has no frontend-to-Express request yet, write:

No client-to-server request exists in the current baseline.

No client-to-server request exists in the current baseline.

That is a valid finding. Do not add a feature just to make the diagram longer.

Check: Open the browser’s Network tab, trigger the action that makes the request, and verify that the request appears. Compare the actual method, URL, status, and response with your notes.

If the request fails, identify whether the failure is:

• the frontend URL,
• the server not running,
• CORS,
• the route path,
• request parsing,
• or the response shape.

Fix the smallest cause you can verify.

6. Write the architecture note

Create a short file at the repository root:

ARCHITECTURE.md

ARCHITECTURE.md

Use this structure, replacing every blank with facts from your project:

# Current Architecture

## Repository shape

This repository is organized as:
- ______

The main packages are:
- ______
- ______

## Running the project

Install dependencies with:

```bash
______

# Current Architecture

## Repository shape

This repository is organized as:
- ______

The main packages are:
- ______
- ______

## Running the project

Install dependencies with:

```bash
______

Start the frontend with:

______

______

Start the backend with:

______

______

The frontend runs at:

The backend runs at:

Frontend flow

The browser loads:

The React entry point is:

It renders:

Backend flow

The Express entry point is:

The server listens on:

Middleware is registered in:

Routes are registered in:

Current request flow

[Describe one real request, or state that no client-to-server request exists yet.]

Browser/component:

Request:

Express route:

Response:

React result:

Baseline check

I verified that:

• dependencies install successfully
• frontend starts
• backend starts
• the browser loads the current page
• ______ request works, or no request currently exists

Keep the note factual. Do not describe planned architecture as if it already exists.

Check: Close your editor, reopen ARCHITECTURE.md, and confirm another developer could identify the startup commands without asking you.

7. Make the baseline reproducible

Use the project’s existing lockfile when installing dependencies. From the package directory that owns the lockfile, run:

npm ci

npm ci

If there is no lockfile, use:

npm install

npm install

Do not manually edit dependency versions during this lesson.

Then run the project again from a clean pair of terminals:

Terminal 1

# use the frontend command you recorded
npm run ______

# use the frontend command you recorded
npm run ______

Terminal 2

# use the backend command you recorded
npm run ______

# use the backend command you recorded
npm run ______

The blanks are intentional: use this project’s scripts rather than copying a generic command.

Now verify the browser page and one backend check again.

If the project has a production build script, run it too:

npm run build

npm run build

If the build fails, record the first meaningful error in ARCHITECTURE.md under a new section:

## Known baseline issue

- Command: ______
- Error: ______
- Reproduction: ______

## Known baseline issue

- Command: ______
- Error: ______
- Reproduction: ______

Only fix it if the cause is clear and local. Avoid broad upgrades or rewrites.

Final check: Run:

git diff --stat
git status

git diff --stat
git status

Your changes should be limited to the architecture note and any small, verified startup fix. The application should still start in the same way it did before this lesson.