# GChain Quick Start Guide

Get GChain up and running in 5 minutes!

## Prerequisites
- ✅ Node.js 16+ installed
- ✅ MariaDB or MySQL installed and running
- ✅ npm installed

## Step 1: Clone/Navigate to Project
```bash
cd C:\_MyDocs\_Code\_GRF\GChain
```

## Step 2: Install Backend Dependencies
```bash
npm install
```

Expected packages:
- express@5.1.0
- mysql2@3.14.1
- bcrypt@6.0.0
- jsonwebtoken@9.0.2
- cors@2.8.5
- dotenv@16.5.0

## Step 3: Configure Database

The `.env` file is already created with default values:
```
DB_HOST=localhost
DB_USER=root
DB_PASSWORD=
DB_NAME=gchain_db
```

**If your MariaDB password is different**, edit `.env` and set `DB_PASSWORD`.

The database and tables will be created automatically on first run!

## Step 4: Start Backend Server
```bash
npm start
```

You should see:
```
✓ Database tables initialized successfully
✓ Connected to MariaDB database
✓ GChain server running on port 5000
```

If you see errors, see Troubleshooting section below.

**Keep this terminal window open!**

## Step 5: Install Frontend Dependencies

Open a **new terminal window**:
```bash
cd C:\_MyDocs\_Code\_GRF\GChain\client
npm install
```

This will install React, React Flow, Plotly, and all dependencies (~1-2 minutes).

## Step 6: Start Frontend
```bash
npm start
```

Your browser should automatically open to `http://localhost:3000`

You should see the GChain login page!

## Step 7: Create Account and Test

1. **Register a new account:**
   - Username: test
   - Email: test@test.com
   - Password: test123

2. **Create a new project:**
   - Click "New" button in header

3. **Add some components:**
   - Click "Sources" in left panel
   - Click "Input Source" to add to canvas
   - Add more components: LNA, Attenuator, Termination

4. **Connect components:**
   - Drag from the blue circle on the right of one component
   - To the blue circle on the left of the next component

5. **Edit parameters:**
   - Double-click any component
   - Change values (e.g., set LNA gain to 25 dB)
   - Click Save

6. **View results:**
   - Select a component by clicking it
   - Look at the right panel for calculated results
   - See cumulative gain, noise figure, output power, etc.

7. **Save your project:**
   - Click "Save" in the header
   - You should see "Saved!" message

8. **Test undo/redo:**
   - Ctrl+Z to undo last action
   - Ctrl+Y to redo

9. **Export:**
   - Click "Export ▼" dropdown
   - Try "PDF" - should download a PDF with your circuit
   - Try "Excel" - should download an Excel file with data

**Congratulations! GChain is working! 🎉**

---

## Troubleshooting

### Issue: "Database connection failed"

**Solution 1:** Check MariaDB is running
```bash
# Windows
services.msc
# Look for MariaDB/MySQL service

# Or check if port 3306 is listening
netstat -an | findstr 3306
```

**Solution 2:** Check credentials in `.env`
- Make sure DB_USER and DB_PASSWORD match your MariaDB setup
- Default MySQL user is usually `root` with no password

**Solution 3:** Create database manually
```sql
mysql -u root -p
CREATE DATABASE gchain_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### Issue: Frontend won't connect to backend

**Solution 1:** Check backend is running on port 5000
```bash
netstat -an | findstr 5000
```

**Solution 2:** Check proxy in client/package.json
- Should have: `"proxy": "http://localhost:5000"`

**Solution 3:** Clear browser cache and reload

### Issue: "Module not found" errors

**Solution:** Reinstall dependencies
```bash
# Backend
npm install

# Frontend
cd client
npm install
```

### Issue: Port 3000 or 5000 already in use

**Solution:** Change ports

For backend (port 5000):
- Edit `.env` and set `PORT=5001` (or any other port)
- Update `client/package.json` proxy to match: `"proxy": "http://localhost:5001"`

For frontend (port 3000):
- Edit `client/package.json` and add to scripts:
```json
"start": "PORT=3001 react-scripts start"
```

### Issue: Components won't drag or connect

**Solution:** This is a known minor issue
- Use "click to add" instead of drag-and-drop
- Click components in left panel to add to canvas
- Drag between the blue circles to connect

### Issue: Calculations show NaN or incorrect values

**Solution 1:** Check component parameters
- Make sure all required parameters have valid numbers
- Edit the component and verify values

**Solution 2:** Check signal chain
- Ensure components are connected in order
- Source must be first in chain

**Solution 3:** Open browser console (F12)
- Check for JavaScript errors
- Look for calculation warnings

### Issue: Can't login after registering

**Solution:** Check browser console (F12)
- Look for API errors
- Verify backend is running
- Check network tab for failed requests

---

## Quick Commands Reference

### Backend
```bash
# Start server
npm start

# Start with auto-reload (development)
npm run dev

# Check if running
netstat -an | findstr 5000
```

### Frontend
```bash
cd client

# Start development server
npm start

# Build for production
npm run build
```

### Database
```bash
# Connect to MariaDB
mysql -u root -p

# Show databases
SHOW DATABASES;

# Use GChain database
USE gchain_db;

# Show tables
SHOW TABLES;

# View users
SELECT * FROM users;

# View projects
SELECT * FROM projects;
```

---

## Next Steps

Once you have GChain running:

1. **Read the README.md** for detailed documentation
2. **Check IMPLEMENTATION_STATUS.md** to see what's complete and what's next
3. **Review the original planning** in `docs/GMODEL_PLANNING.md`
4. **Try building a simple RF chain** (source → LNA → filter → PA → termination)
5. **Experiment with compression** (increase source power until components turn yellow/orange)
6. **Test undo/redo** extensively
7. **Try exporting** to PDF and Excel

---

## Common RF Chain Examples

### Simple Receiver Chain
```
Input Source (-90 dBm, 2400 MHz)
  ↓
LNA (Gain: 20 dB, NF: 1.5 dB, P1dB: 15 dBm)
  ↓
Bandpass Filter (Center: 2400 MHz, BW: 100 MHz, Loss: 2 dB)
  ↓
Attenuator (10 dB)
  ↓
Termination (50Ω)
```

Expected results:
- Total gain: 8 dB (20 - 2 - 10)
- System NF: ~1.8 dB
- Output power: -82 dBm

### Power Amplifier Chain
```
Input Source (-10 dBm, 2400 MHz)
  ↓
Driver Amplifier (Gain: 15 dB)
  ↓
Power Amplifier (Gain: 30 dB, P1dB: 40 dBm)
  ↓
Lowpass Filter (Cutoff: 3000 MHz, Loss: 1 dB)
  ↓
Cable (1m, 0.5 dB/m)
  ↓
Termination (50Ω)
```

Expected results:
- Total gain: 43.5 dB
- Output power: 33.5 dBm
- Check for compression warnings!

---

## Performance Tips

1. **Keep chains under 50 components** for best performance
2. **Save frequently** - auto-save is not yet enabled
3. **Use Ctrl+Z liberally** - undo history saves your work
4. **Name your components** - double-click and change the name
5. **Export often** - PDFs are great for documentation

---

## Getting Help

1. **Check the console** (F12 in browser) for error messages
2. **Review IMPLEMENTATION_STATUS.md** for known issues
3. **Check the original spec** in `docs/GMODEL_PLANNING.md`
4. **Look at the code** - it's well-commented!

---

## Files You Can Safely Modify

- `.env` - Database credentials and configuration
- `client/src/styles/theme.js` - Colors and styling
- `client/src/data/componentLibrary.js` - Add/modify components
- `README.md` - Add your own notes

## Files You Should NOT Modify (unless you know what you're doing)

- `server.js` - Backend core
- `client/src/store/useStore.js` - State management
- `client/src/utils/rfCalculations.js` - RF calculation engine
- Database schema (tables are auto-created)

---

**Happy RF Modeling! 📡🎉**

Questions? Check README.md and IMPLEMENTATION_STATUS.md for details!