nick-sde-value-driver-website/GETTING-STARTED.md

Getting Started — Project SDE Meeting Toolkit

A step-by-step, no-experience-needed guide to running this app on your own computer and changing it with Claude Code.

Hi! This guide assumes you have never written code before. Every step tells you exactly what to click, type, or copy. You will mostly be copying commands and pressing Enter. Take it one step at a time and you'll be fine.

• Time needed: about 30–45 minutes the first time (most of it is downloads installing).
• Can I break anything? No. Everything runs only on your computer. If something gets messed up, the Troubleshooting section fixes it, and worst case you can delete the folder and start over.
• What you'll have at the end: the meeting-tools website running on your own machine, plus the ability to ask Claude Code to change it and watch the changes appear instantly.

---

Table of contents

1. What we're setting up (in plain English)
2. How to use the "terminal"
3. Step-by-step: install the tools
4. Step-by-step: get the project onto your computer
5. Step-by-step: run the app
6. Step-by-step: change something with Claude Code
7. Everyday use (quick reference)
8. If something goes wrong
9. Word glossary

---

1. What we're setting up (in plain English)

The app is the website with the two meeting tools (Field Problem Workshop and Scope Lock Suite). To run it on your computer, it needs three helpers:

Helper	What it does	Why you need it
Node.js	Runs the website's code on your computer.	The app is written in a language Node understands.
Docker Desktop	Runs a small database for us in the background.	The app saves its data in a database. Docker lets us start one instantly without installing a database by hand (that part is genuinely painful, so we skip it).
Claude Code	An AI assistant you talk to in the terminal.	This is how you'll change ("tweak") the app without writing code yourself.

You'll also install VS Code (a friendly editor — you'll use it to download the project and to open the terminals you type commands into) and Git (a behind-the-scenes tool VS Code and Claude use to download the code and save your changes — you won't use it directly). Don't worry about what any of these are yet — just follow along.

Here's the picture of what you're building:

  Your computer
  ┌─────────────────────────────────────────────┐
  │                                               │
  │   Docker  ─►  Database  (stores the data)      │
  │                  ▲                             │
  │                  │                             │
  │   Node   ─►  The app  ─►  http://localhost:5180 │  ◄── you open this in your browser
  │                  ▲                             │
  │                  │                             │
  │   Claude Code  ──┘  (you ask it to change the app) │
  │                                               │
  └─────────────────────────────────────────────┘

---

2. How to use the "terminal"

A terminal is a window where you type commands instead of clicking buttons. On Windows the one we'll use is called PowerShell.

To open it: press the Windows key, type powershell, and click Windows PowerShell. A dark or blue window opens with a blinking cursor. That's it.

Use PowerShell, not "Command Prompt" (cmd). Windows has an older, similar-looking black window called Command Prompt or cmd. Some of the commands in this guide only work in PowerShell, so always start from the "Windows PowerShell" app as described above. If your window's cursor line starts with PS C:\...>, you're in the right one.

A few things to know (this guide is Windows-only, so everything below is written for PowerShell):

• A command is a line of text you paste in and then press Enter to run.
• To paste into PowerShell: right-click inside the window (or press Ctrl+V). Then press Enter.
• When a command finishes, you get your blinking cursor back on a new line. If it's still "thinking," just wait.
• If you ever want to stop something that's running, click the window and press Ctrl + C.
• Commands are picky about spelling and spaces. Copy-paste them exactly rather than retyping.

Try it now: paste this and press Enter. It just prints a message, to prove pasting works.

echo "Hello, I can use the terminal"

---

3. Install the tools

Install these one at a time. Some of them may already be on your work computer — so for each one, run the "check" command first. If it prints a version number, that tool is already installed and you can skip straight to the next one. Only download it if the check says the command isn't recognized.

After any install, close and reopen PowerShell so it notices the new tool, then run the check again to confirm.

3a. Node.js

First, check if it's already installed. In PowerShell, run:

node -v
npm -v

If you see two version numbers (for example v20.11.1 and 10.2.4), Node is already installed — skip to 3b. (npm comes bundled with Node; you never install it separately.) If instead you see a message like "node is not recognized," install it:

1. Go to https://nodejs.org.
2. Click the button that says LTS (it will have a version number like "20.x.x LTS"). LTS means the stable, recommended version.
3. Open the downloaded file and click Next → Next → Install → Finish. Accept all the defaults. If it asks about "Tools for Native Modules," you can leave that unchecked.
4. Close PowerShell, open a fresh one, and run node -v and npm -v again to confirm you now get version numbers.

3b. Docker Desktop

First, check if it's already installed. Run:

docker --version

If you see a version number, Docker is installed — just make sure the app is running (Windows key → type "Docker" → open Docker Desktop, and wait for the whale icon by the clock to go steady), then skip to 3c. Otherwise, install it:

1. Go to https://www.docker.com/products/docker-desktop/ and download Docker Desktop for Windows.
2. Run the installer, accept the defaults, and let it finish. It may ask you to restart your computer — go ahead.
3. After restarting, open Docker Desktop (Windows key → type "Docker" → click it). The first launch takes a minute. Accept the service agreement if asked.
4. Leave Docker Desktop running. You'll know it's ready when the little whale icon near the clock (bottom-right of your screen) is steady, not animating. Docker must be running whenever you use the app.
5. Close and reopen PowerShell, then run docker --version again to confirm.

Docker Desktop on Windows uses something called WSL2. If the installer offers to set it up, say yes. If you hit an error about WSL, run PowerShell as Administrator (right- click PowerShell → "Run as administrator") and paste wsl --install, then restart.

3c. Git

First, check if it's already installed. Run:

git --version

If you see a version number, skip to 3d. Otherwise, install it:

1. Go to https://git-scm.com/download/win. The download starts automatically.
2. Run the installer. There are a lot of screens — just click Next through all of them and then Install. The defaults are fine.
3. Close and reopen PowerShell, then run git --version again to confirm.

3d. VS Code

VS Code is the editor you'll use to download the project and to open a terminal. We'll use it in Step 4, so please install it.

First, check if it's already installed: press the Windows key and type Visual Studio Code. If it shows up, it's installed — skip to 3e. Otherwise:

• Download from https://code.visualstudio.com and run the installer.
• On the installer's "Select Additional Tasks" screen, tick the "Open with Code" checkboxes — it makes things easier later. Then finish with the defaults.

3e. Claude Code

This is the AI assistant you'll use to change the app.

First, check if it's already installed. Run:

claude --version

If you see a version number, skip to Step 4. Otherwise, now that Node is installed (3a), install Claude Code with one command:

npm install -g @anthropic-ai/claude-code

The -g means "install it for the whole computer." When it finishes, close and reopen PowerShell and confirm:

claude --version

You'll log in the first time you actually start it (in Step 6) — it opens your browser to sign in with your Anthropic account. If you don't have an account yet, ask whoever gave you this project which login to use.

---

4. Get the project onto your computer

You'll download ("clone") the project from our internal Gitea site straight into VS Code. Don't download a ZIP — cloning from Gitea keeps your copy connected to the real project so you can pull in updates later.

We'll do this entirely through VS Code's menus — no typing commands.

1. Open VS Code (Windows key → type Visual Studio Code → Enter).

2. Open the Command Palette: press Ctrl + Shift + P. A search box drops down from the top.

3. Type Git: Clone and click it when it appears in the list.

4. It asks for a repository URL. Paste this exact address and press Enter:

   https://primegit.primecontrols-dev.com/c.west/nick-sde-value-driver-website.git
   

5. A file window opens asking where to put the project. Choose your Documents folder and click Select as Repository Destination. (VS Code creates a nick-sde-value-driver-website folder inside it for you.)

6. The first time, a browser window or a pop-up will ask you to sign in to the internal Gitea site — use your work login. If it asks to allow the "GitHub"/"Git" extension to sign in, allow it.

7. When it finishes downloading, VS Code shows a notification in the bottom-right: "Would you like to open the cloned repository?" Click Open.

You should now see the project's files listed in the panel on the left side of VS Code (names like src, package.json, docker-compose.yml, and GETTING-STARTED.md — this guide). That means it worked. Keep VS Code open for the next step.

If you don't have the Gitea link or can't sign in, ask the person who shared this project with you — you need access to that internal site to download the code.

---

5. Run the app

From here on, all commands go into a terminal that is inside the project folder. The easiest way to get one is to use the terminal built into VS Code — because you opened the project there in Step 4, it already starts in the right place.

5a. Open the terminal inside VS Code

1. With the project open in VS Code, click the Terminal menu at the top → New Terminal. (Or press Ctrl + ` — that's the key just above Tab, to the left of the 1 key.)
2. A panel opens at the bottom of VS Code with a blinking cursor. This is your PowerShell terminal, and it's already sitting inside the project folder.
3. Make sure it's PowerShell: the line should start with PS followed by a path ending in nick-sde-value-driver-website. If it says something else, click the small dropdown arrow (⌄) next to the + at the top-right of the terminal panel, choose Select Default Profile → Windows PowerShell, then open a New Terminal again.

To double-check you're in the right place, type this and press Enter:

ls

You should see names like package.json, src, docker-compose.yml, and this GETTING-STARTED.md. If you do, you're ready. Use this VS Code terminal for all the commands below.

5b. Create your settings file

The app reads its settings from a file named .env. There's a ready-made template called .env.example. Copy it — the default values already match the database we're about to start, so you don't need to edit anything.

Copy-Item .env.example .env

5c. Start the database (with Docker)

Make sure Docker Desktop is running (steady whale icon). Then start just the database:

docker compose up -d db

• The first time, Docker downloads the database software — this can take a minute or two.
• -d means "run it in the background," so you get your cursor back.
• The database automatically creates the tables it needs on first startup. You don't have to do anything.

Check it's running:

docker compose ps

You should see a db line with status running (or healthy). Leave it running in the background.

5d. Install the app's building blocks

The app depends on some code libraries. This command downloads them into the folder. It's a one-time step (you only re-run it if someone changes the dependencies later).

npm install

It prints a lot of text and takes a minute. A few warnings in yellow are normal. As long as it ends without a big red ERR! block, you're good.

5e. Start the app

npm run dev

After a moment you'll see something like:

  VITE ready
  ➜  Local:   http://localhost:5180/

Open your browser and go to http://localhost:5180 — the app appears! Try the dark- mode button in the top bar, click into the tools, enter some text.

Important:

• Keep this terminal open. As long as it's running, the app is live. If you close it (or close VS Code), the app stops.
• To stop the app, click inside that terminal and press Ctrl + C.
• The address is localhost, which just means "this computer." Only you can see it — it's not on the internet.

🎉 The app is now running on your machine. Next, let's change something.

---

6. Change something with Claude Code

Here's the magic: while the app is running, you tell Claude Code what you want changed, and the change shows up in your browser automatically — this is called "hot reload."

6a. Open a second terminal (also in VS Code)

Your first terminal is busy running the app — leave it alone. You'll open a second terminal right next to it in VS Code:

1. In the terminal panel at the bottom of VS Code, click the + (plus) button at its top-right corner. This opens a fresh terminal alongside the first one — you'll see both listed on the right side of the panel, and you can click between them.
2. The new terminal also starts inside the project folder, so you're ready to go. (Your npm run dev keeps running in the other one the whole time.)

6b. Start Claude Code

claude

The first time, it opens your browser to log in — follow the prompts. After that, you'll see a prompt where you can type to Claude in plain English.

6c. Ask for a change

Type a request in normal words and press Enter. Some examples to try:

• Change the heading on the home page from "Meeting Toolkit" to "SDE Meeting Tools".
• Make the "Open →" links on the home page cards bright green.
• Add a short sentence under the main heading explaining what the Scope Lock tool is for.

Claude will explain what it's about to do and make the edits. It may ask for your approval before changing files — read what it says and approve if it looks right. You can't permanently break anything — see "undo" below.

6d. Watch it happen

Switch to your browser at http://localhost:5180 and refresh if needed. Your change is there. Keep chatting with Claude to refine it: a bit darker green, undo that, move it above the heading, and so on.

6e. Undoing changes

If you don't like a change, just ask Claude in plain English: undo the last change, put the heading back the way it was, or undo everything you've changed today. Claude keeps track and can walk it back for you — you don't need to know how it does that.

6f. When you're happy — saving your work to the repo

Your changes so far live only on your computer. When you want to keep them and put them back into the shared project, just ask Claude — for example:

• Save my changes and put them in the repo with a short description of what I did.

Claude handles all the behind-the-scenes steps for you. If it needs anything from you (like confirming your login), it'll ask in plain language. You don't need to learn any of the commands yourself — describe what you want and let Claude do it.

---

7. Everyday use — quick reference

Once everything is installed, starting up each day is quick:

1. Make sure Docker Desktop is running (open it from the Start menu; wait for the steady whale icon).
2. Open the project in VS Code (it should appear under File → Open Recent, or reopen the nick-sde-value-driver-website folder).
3. Open a terminal (Terminal → New Terminal) and run these two commands:

# make sure the database is up (safe to run even if it already is)
docker compose up -d db

# start the app  (leave this terminal running while you work)
npm run dev

Then open http://localhost:5180 in your browser. Open a second terminal in VS Code (the + button in the terminal panel) and run claude to make changes.

Shutting down:

# in the app's terminal: press Ctrl + C to stop the app
# then, if you want to stop the database too:
docker compose stop

Your data is safe when you stop — it's stored by Docker and will be there next time. (See Troubleshooting for how to wipe it if you ever want a clean slate.)

---

If something goes wrong

"The app won't open in my browser / the page is blank." Check the first VS Code terminal is still running npm run dev and shows a Local: address. Make sure you typed the address exactly: http://localhost:5180. If the terminal shows a red error, copy it and paste it to Claude Code and ask what's wrong.

"Port 5180 is already in use" (or the app won't start). Something else is using that address — usually an old copy of the app still running. Close any other terminals running the app (or close and reopen VS Code, or restart your computer), then try npm run dev again.

"Cannot connect to the database" / errors mentioning ECONNREFUSED or 5432. The database isn't running. Make sure Docker Desktop is open, then run docker compose up -d db and wait until docker compose ps shows it running/healthy.

"docker: command not found" or "Docker Desktop is not running." Open Docker Desktop from the Start menu and wait for the whale icon to go steady. Then retry your command.

npm install ended with red ERR! text. Make sure you're in the project folder (ls should show package.json). Try running it once more. If it still fails, copy the red text to Claude Code and ask for help.

"claude: command not found." Close and reopen the VS Code terminal (it needs to pick up the new install) — the quickest way is to close VS Code entirely and reopen the project. If it still isn't found, re-run npm install -g @anthropic-ai/claude-code.

I want to erase all the app's saved data and start clean. This deletes the database contents (the tables get re-created empty next start):

docker compose down -v
docker compose up -d db

When in doubt: you have an AI assistant right here. In the second terminal, run claude and describe what happened in plain English — paste any red error text. That's literally what it's for.

---

Word glossary

• Terminal / PowerShell — the window where you type commands.
• Command — a line of text you paste and run by pressing Enter.
• Node.js — the program that runs the app's code on your computer.
• npm — comes with Node; downloads and manages the app's code libraries. ("npm install" fetches them; "npm run dev" starts the app.)
• Docker — runs the database for us in a self-contained box, so we don't install a database by hand.
• Database — where the app stores the data people enter.
• Dependencies / libraries — pre-written code the app relies on, downloaded by npm install into a node_modules folder.
• .env file — a small settings file the app reads on startup.
• localhost — "this computer." http://localhost:5180 is the app running only on your machine.
• Port — a numbered "door" on your computer. The app uses door 5180; the database uses 5432.
• Hot reload — when you change the code, the running app updates in the browser by itself.
• Git — a behind-the-scenes tool that downloads the project and saves changes. VS Code and Claude use it for you; you don't run it yourself.
• Repository ("repo") — the project stored on our internal Gitea site (its code plus its history). Your copy on your computer is connected to it.
• Gitea — our internal website where the project lives, like a private GitHub.
• Claude Code — the AI assistant in the terminal you ask to change the app.

---

Stuck on a step? Open Claude Code (claude) in the project folder and describe exactly what you see. It can read this guide and walk you through it.