# TaxCore Connection Configuration - Quick Reference

## Site-Specific Configuration

| Hostname | Connection Mode | Endpoint | Reason |
|----------|----------------|----------|--------|
| **localhost:8080** | ✅ Direct Node.js | `http://localhost:3001/sale` | Local dev - fast iteration |
| **frcs.cybexpte.com** | 🔄 PHP Proxy | `../api/POS/taxcore` | Staging server - backend debugging |
| **test.*.com** | 🔄 PHP Proxy | `../api/POS/taxcore` | Test environments |
| **staging.*.com** | 🔄 PHP Proxy | `../api/POS/taxcore` | Staging environments |
| **Production domains** | ✅ Direct Node.js | `http://hostname:3001/sale` | Performance |

## Data Flow

### localhost:8080 (Local Development)
```
Browser → Node.js (port 3001) → TaxCore API
```
✅ **Fast** - No PHP overhead  
✅ **Direct** - Immediate feedback  
✅ **Simple** - Fewer moving parts  

### frcs.cybexpte.com (Staging Server)
```
Browser → PHP (port 8080) → Node.js (port 3001) → TaxCore API
```
✅ **Debuggable** - Can add error_log() in PHP  
✅ **Traceable** - Can inspect requests in backend  
✅ **Testable** - Can validate business logic  

### Production Domains
```
Browser → Node.js (port 3001) → TaxCore API
```
✅ **Fast** - Optimized for performance  
✅ **Scalable** - Handles high transaction volume  
✅ **Reliable** - Fewer points of failure  

## Quick Setup

### For Local Development (localhost:8080)
```bash
# No configuration needed!
# Just start services and open:
http://localhost:8080/FrontEnd/Dashboard.html

# Auto-detects: Direct Node.js connection ✅
```

### For Staging Server (frcs.cybexpte.com)
```bash
# No configuration needed!
# Deploy code to frcs.cybexpte.com

# Auto-detects: PHP Proxy ✅
# Can add debugging in api/controllers/PosController.php
```

### For Production Servers
```bash
# No configuration needed!
# Deploy code to production domain (e.g., pos.taf.com)

# Auto-detects: Direct Node.js connection ✅
```

## Manual Overrides (If Needed)

### Force localhost to use PHP Proxy
```javascript
// In browser console on localhost:8080
localStorage.setItem('taxcore_test_site', 'true');
location.reload();
```

### Force frcs.cybexpte.com to use Direct Node.js
```javascript
// In browser console on frcs.cybexpte.com
localStorage.setItem('taxcore_test_site', 'false');
location.reload();
```

### Reset to Auto-detect
```javascript
localStorage.removeItem('taxcore_test_site');
localStorage.removeItem('taxcore_direct');
location.reload();
```

## Verification

### Check Current Mode
Open browser console and look for:

**On localhost:8080:**
```
🚀 Local development: localhost (using direct Node.js)
🚀 PRODUCTION | 🔌 TaxCore Connection Mode: DIRECT to Node.js
📡 Endpoint: http://localhost:3001/sale
```

**On frcs.cybexpte.com:**
```
🧪 Test site detected: frcs.cybexpte.com (configured for PHP proxy)
🧪 TEST SITE | 🔌 TaxCore Connection Mode: PROXY via PHP
📡 Endpoint: ../api/POS/taxcore
```

## Troubleshooting

### Issue: localhost:8080 using PHP proxy (wrong!)
**Check:**
```javascript
console.log(localStorage.getItem('taxcore_test_site'));
// Should be: null (auto-detect) or 'false'
```

**Fix:**
```javascript
localStorage.removeItem('taxcore_test_site');
location.reload();
```

### Issue: frcs.cybexpte.com using direct Node.js (wrong!)
**Check:**
```javascript
console.log(localStorage.getItem('taxcore_test_site'));
// Should be: null (auto-detect) or 'true'
```

**Fix:**
```javascript
localStorage.removeItem('taxcore_test_site');
localStorage.removeItem('taxcore_direct');
location.reload();
```

### Issue: Can't connect to TaxCore service
**Check Node.js service is running:**
```bash
# Check health
curl http://localhost:3001/health

# If not running, start it:
cd /var/www/html/TAF/websocket-server
node taxcore-service.js &

# Or restart Docker:
docker-compose restart taxcore-service
```

## Configuration Files

### For Node.js Service
**File:** `websocket-server/.env`
```bash
TAXCORE_SERVICE_PORT=3001
TAXCORE_TAX_URL=https://api.sandbox.vms.frcs.org.fj/api
TAXCORE_VSDC_URL=http://devesdc.sandbox.vms.frcs.org.fj:8888/YOUR-UUID/api
TAXCORE_PFX_PATH=/var/www/html/TAF/FRCS_Certs_Install/YOUR-CERT.pfx
TAXCORE_PFX_PASSWORD=YOUR-PASSWORD
TAXCORE_PIN_JSON=YOUR-PIN
TAXCORE_DEBUG=true
```

### For PHP Backend
**File:** `api/controllers/PosController.php`

PHP automatically reads environment variables for TaxCore configuration:
```php
$this->taxcoreServiceUrl = getenv('TAXCORE_SERVICE_URL') ?: "http://localhost:3001";
```

## When to Use Each Mode

### Use Direct Node.js When:
- ✅ Local development (fast iteration needed)
- ✅ Production environment (performance critical)
- ✅ High transaction volume
- ✅ Want simplest architecture

### Use PHP Proxy When:
- ✅ Staging/test server (debugging needed)
- ✅ Need to inspect/log requests server-side
- ✅ Need to add business logic before TaxCore
- ✅ Testing backend integration

## Summary

```
┌─────────────────────┬─────────────────┬──────────────────────┐
│ Environment         │ Connection Mode │ Why?                 │
├─────────────────────┼─────────────────┼──────────────────────┤
│ localhost:8080      │ Direct Node.js  │ Fast development     │
│ frcs.cybexpte.com   │ PHP Proxy       │ Backend debugging    │
│ Production domains  │ Direct Node.js  │ Performance          │
└─────────────────────┴─────────────────┴──────────────────────┘
```

**No configuration needed - just deploy and it works!** 🎉

---

Last Updated: October 2, 2025  
Related: `docs/TaxCore_Test_Site_Configuration.md`