# Blueprint — How it works (plain language)

Read this when something feels confusing. You do **not** need to understand every line of code.

---

## 1. The whole project in one sentence

**Blueprint is two programs that talk to each other:**

| Part | Folder | What it does | Address |
|------|--------|--------------|---------|
| **Screen (frontend)** | `frontend/` | What you see in the browser — buttons, forms, dashboard | http://localhost:5173 |
| **Brain (backend)** | `backend/` | Saves users and items in the database, checks passwords | http://localhost:5000 |

Both must be running at the same time.

### Images and icons (two folders)

| Folder | Path | Use for |
|--------|------|---------|
| **public** | `frontend/public/` | Favicon, files you reference as `/filename.png` in `index.html` |
| **assets** | `frontend/src/assets/` | Logos and images used inside React pages (import them at the top of a `.jsx` file) |

Examples in this project:

- `public/favicon.svg` — browser tab icon (linked in `index.html`)
- `src/assets/logo.svg` — sidebar logo (used in `DashboardLayout.jsx`)

To change the logo: replace `frontend/src/assets/logo.svg` with your own image (same name), or add `my-logo.png` and update the import in `DashboardLayout.jsx`.

---

## 2. How to start the app (every time)

**Step 1 — MongoDB**  
MongoDB must be running on your computer (the database).

**Step 2 — Backend (Terminal 1)**

```powershell
cd backend
npm run dev
```

Wait until you see: `Server running on http://localhost:5000`

**Step 3 — Frontend (Terminal 2)**

```powershell
cd frontend
npm run dev
```

Open: **http://localhost:5173**

If the screen is blank or errors appear, check that **both** terminals are still running.

---

## 3. What happens when someone uses your app

```
Register or Login
       ↓
Backend checks email/password → sends back a "token" (like a temporary key)
       ↓
Browser saves token in localStorage
       ↓
User goes to /dashboard (sidebar + pages)
       ↓
Each page asks the backend for data (items, profile, report)
       ↓
Backend only returns THAT user's data (using the token)
```

**localStorage** = a small storage area inside the browser. After login it holds:

- `token` — proves you are logged in  
- `user` — your name and email (for display)

Log out = those are deleted.

---

## 4. Files you will actually touch

### Safe to edit (words and links)

| File | What you change |
|------|-----------------|
| `frontend/src/components/DashboardLayout.jsx` | Sidebar link names and URLs (`<Link>` lines) |
| `frontend/src/pages/*.jsx` | Page titles, labels, text users see |
| `frontend/src/App.jsx` | Add a new route when you add a new page |
| `frontend/public/` | Favicon and other static files |
| `frontend/src/assets/` | Logos and images for pages |
| `README.md` | Project notes for yourself |

### Edit only if you know why (or with AI help)

| File | What it does |
|------|----------------|
| `backend/.env` | Database address, secret key |
| `backend/models/Item.js` | What fields an "item" has in the database |
| `backend/controllers/itemController.js` | Logic for create/read/update/delete items |
| `frontend/src/pages/Items.jsx` | Form + list that talks to `/api/items` |

### Usually leave alone

| File | Why |
|------|-----|
| `node_modules/` | Installed packages — huge, auto-generated |
| `backend/middleware/auth.js` | Checks the token — works as-is |
| `frontend/src/components/ProtectedRoute.jsx` | Blocks dashboard if not logged in |
| `frontend/src/main.jsx` | Starts the React app |

---

## 5. The parts that confuse people most

### A) Page vs Route vs Link (three names, one idea)

Think of your app like a **building with rooms**:

| Idea | File | Example |
|------|------|---------|
| **Page** | `frontend/src/pages/Items.jsx` | The room content (form, list) |
| **Route** | `frontend/src/App.jsx` | The address: `/dashboard/items` opens Items page |
| **Link** | `DashboardLayout.jsx` | The menu button that sends you to that address |

**Rule:** If you add a menu link, you need **both**:

1. A `<Link to="/dashboard/something">` in `DashboardLayout.jsx`  
2. A `<Route path="something" element={...} />` in `App.jsx`  
3. A page file in `frontend/src/pages/`

Miss step 2 or 3 → link goes nowhere or shows a blank page.

---

### B) What is `App.jsx`?

It is the **map of your website**. It does not show much on screen — it only decides:

- `/login` → Login page  
- `/register` → Register page  
- `/dashboard` → Dashboard layout (sidebar) with pages inside it  

The dashboard "wraps" inner pages using `<Outlet />` inside `DashboardLayout.jsx`.  
**Outlet** = hole where the current page (Items, Report, Profile) appears.

---

### C) What is `ProtectedRoute`?

A **bouncer** at the dashboard door.

- Has `token` in localStorage? → Let them in.  
- No token? → Send to `/login`.

You rarely need to change this file.

---

### D) What is `axios.get` / `axios.post`?

The frontend **asking the backend a question** over the internet.

Example from Items page:

```text
axios.get('http://localhost:5000/api/items', { headers: { Authorization: 'Bearer TOKEN' } })
```

Means: "Hey backend, give me my items. Here is my login token."

- **get** = read data  
- **post** = create new data  
- **put** = update  
- **delete** = remove  

If the URL is wrong or the backend is off → red error on the page.

---

### E) Backend structure (simple)

```
Request hits server.js
        ↓
Routes (authRoutes, itemRoutes) — which URL?
        ↓
Controller — what to do?
        ↓
Model (User, Item) — read/write MongoDB
        ↓
Response back to frontend
```

| URL | Purpose |
|-----|---------|
| `/api/auth/register` | Create account |
| `/api/auth/login` | Sign in, get token |
| `/api/auth/me` | Who am I? |
| `/api/items` | List / create items |
| `/api/items/:id` | Update / delete one item |

---

## 6. Sidebar — how you already customize it

Open `DashboardLayout.jsx`. You will see:

```jsx
<Link to="/dashboard/items">Items</Link>
```

- Change **Items** → any label (e.g. `Products`)  
- Change **to=** only if you also change the route in `App.jsx`  

---

## 7. When something goes wrong

| Problem | Check |
|---------|--------|
| Blank page after login | Is `DashboardLayout` inside `App.jsx`? (not commented out) |
| Link does nothing | Route missing in `App.jsx`? |
| "Failed to load" / network error | Backend running? MongoDB running? |
| Login works but items empty | Normal if you have not created items yet |
| CORS or connection error | Backend on port 5000, frontend on 5173 |

---

## 8. How to use Cursor / AI without confusion

Copy this pattern when you ask for help:

> "In my Blueprint project, I want to [goal].  
> Please change only [file names] and explain in simple words what you changed."

Examples:

- "Rename Items to Tasks in the sidebar and Items page title."  
- "Add a Customers page like Items — tell me which files you touched."  
- "Login works but Report is empty — what should I check?"

Ask **one thing at a time** — easier to follow.

---

## 9. Quick picture

```
┌─────────────────────────────────────────────────────────┐
│  BROWSER (frontend)                                      │
│  Login → token saved → Dashboard (sidebar + pages)       │
│       │ axios calls                                      │
└───────┼─────────────────────────────────────────────────┘
        ▼
┌─────────────────────────────────────────────────────────┐
│  SERVER (backend)  port 5000                             │
│  auth + items APIs                                       │
└───────┼─────────────────────────────────────────────────┘
        ▼
┌─────────────────────────────────────────────────────────┐
│  MongoDB  (database file on your PC)                     │
│  users collection + items collection                     │
└─────────────────────────────────────────────────────────┘
```

---

## 10. You are doing fine if you can answer these

- [ ] I know frontend = what I see, backend = saves data  
- [ ] I know both terminals must run  
- [ ] I know sidebar links live in `DashboardLayout.jsx`  
- [ ] I know new pages need a file + a route in `App.jsx`  
- [ ] I know login saves a `token` so the dashboard works  

You do **not** need to memorize React or Node. Edit labels and links first; copy `Items.jsx` when you need a new list page.

---

*Keep this file in your project folder. When confused, read section 5 for the topic that bothers you, or ask AI: "Explain section X from HOW_IT_WORKS.md for my Blueprint."*
