create-jinmankn-app 1.0.0

package/templates/blueprint/HOW_IT_WORKS.md

@@ -0,0 +1,286 @@
+# 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."*

package/templates/blueprint/README.md

@@ -0,0 +1,123 @@
+# Blueprint
+
+A reusable full-stack starter template with authentication, CRUD, and MongoDB. Copy or rename this folder to bootstrap any new project.
+
+## Stack
+
+- **Backend:** Node.js, Express, Mongoose, JWT, bcrypt
+- **Frontend:** React (Vite), Tailwind CSS, React Router, axios
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v18+ recommended)
+- [MongoDB](https://www.mongodb.com/try/download/community) running locally (use [MongoDB Compass](https://www.mongodb.com/products/compass) to inspect `blueprint_db`)
+
+## Project structure
+
+```
+blueprint/
+├── backend/     # API (port 5000)
+├── frontend/    # React app (port 5173)
+│   ├── public/  # Favicon, static files (e.g. /favicon.svg)
+│   └── src/
+│       └── assets/  # Logos, images used in pages
+└── README.md
+```
+
+## Setup
+
+### 1. MongoDB
+
+Start MongoDB on your machine. The default connection string targets a local instance:
+
+```
+mongodb://127.0.0.1:27017/blueprint_db
+```
+
+### 2. Backend
+
+```bash
+cd backend
+npm install
+cp .env.example .env
+```
+
+On Windows (PowerShell):
+
+```powershell
+Copy-Item .env.example .env
+```
+
+Edit `.env` and set a strong `JWT_SECRET`. Other defaults work for local development.
+
+```bash
+npm run dev
+```
+
+API base: **http://localhost:5000/api**
+
+- Health: `GET /api/health`
+- Auth: `POST /api/auth/register`, `POST /api/auth/login`, `GET /api/auth/me`
+- Items (protected): `GET/POST /api/items`, `GET/PUT/DELETE /api/items/:id`
+
+### 3. Frontend
+
+In a second terminal:
+
+```bash
+cd frontend
+npm install
+cp .env.example .env
+```
+
+Windows:
+
+```powershell
+Copy-Item .env.example .env
+```
+
+```bash
+npm run dev
+```
+
+App URL: **http://localhost:5173**
+
+## Test flow
+
+1. Open **http://localhost:5173/register** and create an account (name, email, password).
+2. You are redirected to **/items** with a JWT stored in `localStorage`.
+3. Create, edit, and delete items on the Items page.
+4. Log out, then sign in again at **/login** — your items remain tied to your user only.
+
+## Renaming for a new project
+
+1. Rename the `blueprint` folder and update `package.json` `name` fields in `backend` and `frontend`.
+2. Change `MONGO_URI` database name in `backend/.env`.
+3. Duplicate `Item` model/routes/controllers as a pattern for new resources.
+4. Add new pages and routes in the frontend following `Items.jsx`.
+
+## Scripts
+
+| Location   | Command        | Description              |
+|-----------|----------------|--------------------------|
+| backend   | `npm run dev`  | API with nodemon         |
+| backend   | `npm start`    | API (production-style)   |
+| frontend  | `npm run dev`  | Vite dev server          |
+| frontend  | `npm run build`| Production build         |
+
+## Environment variables
+
+**Backend (`backend/.env`)**
+
+| Variable     | Example                              |
+|-------------|--------------------------------------|
+| PORT        | 5000                                 |
+| MONGO_URI   | mongodb://127.0.0.1:27017/blueprint_db |
+| JWT_SECRET  | (long random string)                 |
+| CLIENT_URL  | http://localhost:5173                |
+
+**Frontend (`frontend/.env`)**
+
+| Variable       | Example                      |
+|---------------|------------------------------|
+| VITE_API_URL  | http://localhost:5000/api    |

package/templates/blueprint/backend/config/db.js

@@ -0,0 +1,12 @@
+const mongoose = require('mongoose');
+
+const connectDB = async () => {
+  try { 
+    await mongoose.connect('mongodb://localhost:27017/blueprint_db');
+    console.log('MongoDB connected');
+  } catch (error) {
+    console.error('MongoDB connection error:', error);
+  }
+};
+
+module.exports = connectDB;

package/templates/blueprint/backend/controllers/authController.js

@@ -0,0 +1,90 @@
+const bcrypt = require('bcrypt');
+const jwt = require('jsonwebtoken');
+const User = require('../models/User');
+const JWT_SECRET = 'change_this_to_a_long_random_secret';
+
+
+
+function createToken(userId) {
+  return jwt.sign({ userId },JWT_SECRET, { expiresIn: '7d' });
+}
+
+function formatUser(user) {
+  return {
+    id: user._id,
+    name: user.name,
+    email: user.email,
+  };
+}
+
+exports.register = async (req, res) => {
+  try {
+    const { name, email, password } = req.body;
+
+    if (!name || !email || !password) {
+      return res.status(400).json({ message: 'Name, email, and password are required' });
+    }
+
+    if (password.length < 6) {
+      return res.status(400).json({ message: 'Password must be at least 6 characters' });
+    }
+
+    const existing = await User.findOne({ email: email.toLowerCase() });
+    if (existing) {
+      return res.status(409).json({ message: 'Email already registered' });
+    }
+
+    const hashedPassword = await bcrypt.hash(password, 10);
+    const user = await User.create({
+      name,
+      email: email.toLowerCase(),//to ensure the email is always lowercase
+      password: hashedPassword,
+    });
+
+    const token = createToken(user._id);
+
+    res.status(201).json({
+      token,
+      user: formatUser(user),
+    });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.login = async (req, res) => {
+  try {
+    const { email, password } = req.body;
+
+    if (!email || !password) {
+      return res.status(400).json({ message: 'Email and password are required' });
+    }
+
+    const user = await User.findOne({ email: email.toLowerCase() });
+    if (!user) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    const match = await bcrypt.compare(password, user.password);
+    if (!match) {
+      return res.status(401).json({ message: 'Invalid email or password' });
+    }
+
+    const token = createToken(user._id);
+
+    res.json({
+      token,
+      user: formatUser(user),
+    });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.getMe = async (req, res) => {
+  try {
+    res.json({ user: formatUser(req.user) });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+};

package/templates/blueprint/backend/controllers/itemController.js

@@ -0,0 +1,74 @@
+const Item = require('../models/Item');
+
+exports.getItems = async (req, res) => {
+  try {
+    const items = await Item.find({ user: req.user._id }).sort({ createdAt: -1 });
+    res.json({ items });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.getItem = async (req, res) => {
+  try {
+    const item = await Item.findOne({ _id: req.params.id, user: req.user._id });
+    if (!item) {
+      return res.status(404).json({ message: 'Item not found' });
+    }
+    res.json({ item });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.createItem = async (req, res) => {
+  try {
+    const { title, description } = req.body;
+
+    if (!title) {
+      return res.status(400).json({ message: 'Title is required' });
+    }
+
+    const item = await Item.create({
+      title,
+      description: description || '',
+      user: req.user._id,
+    });
+
+    res.status(201).json({ item });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.updateItem = async (req, res) => {
+  try {
+    const { title, description } = req.body;
+
+    const item = await Item.findOne({ _id: req.params.id, user: req.user._id });
+    if (!item) {
+      return res.status(404).json({ message: 'Item not found' });
+    }
+
+    if (title !== undefined) item.title = title;
+    if (description !== undefined) item.description = description;
+
+    await item.save();
+
+    res.json({ item });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}
+
+exports.deleteItem = async (req, res) => {
+  try {
+    const item = await Item.findOneAndDelete({ _id: req.params.id, user: req.user._id });
+    if (!item) {
+      return res.status(404).json({ message: 'Item not found' });
+    }
+    res.json({ message: 'Item deleted' });
+  } catch (err) {
+    res.status(500).json({ message: err.message });
+  }
+}

package/templates/blueprint/backend/middleware/auth.js

@@ -0,0 +1,32 @@
+// this middleware is helping us to protect our routes so that only authenticated users can access the routes
+//it is checking if the user is authenticated by checking the token in the header(the header is the part of the request that contains the token)
+//if the user is not authenticated, it will return a 401 status code and a message that the user is not authorized
+//if the user is authenticated, it will return the user object
+//and the user object is the user that is authenticated
+
+const jwt = require('jsonwebtoken');
+const User = require('../models/User');
+const JWT_SECRET = 'change_this_to_a_long_random_secret';
+
+exports.protect = async (req, res, next) => {
+  try {
+    const header = req.headers.authorization;
+
+    if (!header || !header.startsWith('Bearer ')) {
+      return res.status(401).json({ message: 'Not authorized' });
+    }
+
+    const token = header.split(' ')[1];
+    const decoded = jwt.verify(token, JWT_SECRET);
+    const user = await User.findById(decoded.userId).select('-password');
+
+    if (!user) {
+      return res.status(401).json({ message: 'Not authorized' });
+    }
+
+    req.user = user;
+    next();
+  } catch (err) {
+    return res.status(401).json({ message: 'Not authorized' });
+  }
+};

package/templates/blueprint/backend/middleware/errorHandler.js

@@ -0,0 +1,23 @@
+
+
+exports.notFound = (req, res) => {
+  res.status(404).json({ message: 'Route not found' });
+}
+
+exports.errorHandler = (err, req, res, next) => {
+  console.error(err);
+
+  if (err.name === 'ValidationError') {
+    const messages = Object.values(err.errors).map((e) => e.message);
+    return res.status(400).json({ message: messages.join(', ') });
+  }
+
+  if (err.name === 'CastError') {
+    return res.status(400).json({ message: 'Invalid ID' });
+  }
+
+  const status = err.statusCode || 500;
+  const message = err.message || 'Server error';
+
+  res.status(status).json({ message });
+};

package/templates/blueprint/backend/models/Item.js

@@ -0,0 +1,26 @@
+const mongoose = require('mongoose');
+
+const itemSchema = new mongoose.Schema(
+  {
+    title: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    description: {
+      type: String,
+      default: '',
+      trim: true,
+    },
+    user: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'User',
+      required: true,
+    },
+  },
+  { timestamps: true }
+);
+
+const Item = mongoose.model('Item', itemSchema);
+
+module.exports = Item;

package/templates/blueprint/backend/models/User.js

@@ -0,0 +1,28 @@
+const mongoose = require('mongoose');
+
+const userSchema = new mongoose.Schema(
+  {
+    name: {
+      type: String,
+      required: true,
+      trim: true,
+    },
+    email: {
+      type: String,
+      required: true,
+      unique: true,
+      lowercase: true,
+      trim: true,
+    },
+    password: {
+      type: String,
+      required: true,
+      minlength: 6,
+    },
+  },
+  { timestamps: true }
+);
+
+const User = mongoose.model('User', userSchema);
+
+module.exports = User;