MGSLG Analytics Platform - Quick Start Guide

MGSLG Analytics Platform - Quick Start Guide

🚀 Starting the Application

Option 1: Start Everything (Recommended)

cd /Users/nhla/Desktop/PROJECTS/2025/mathew-goniwe
./start_dev.sh

This starts both backend and frontend automatically.

---

Option 2: Start Manually

Terminal 1 - Backend (Python):

cd /Users/nhla/Desktop/PROJECTS/2025/mathew-goniwe/backend
source .venv/bin/activate
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Terminal 2 - Frontend (Next.js):

cd /Users/nhla/Desktop/PROJECTS/2025/mathew-goniwe/frontend
pnpm install  # First time only
pnpm run dev

---

🌐 Access the Application

Once started, open your browser:

Service	URL	Description
Frontend	http://localhost:3000	Main dashboard
Backend	http://localhost:8000	API server
API Docs	http://localhost:8000/docs	Interactive API documentation

---

🛑 Stopping the Application

If using start_dev.sh:

./stop_dev.sh

Manual stop:

# Stop backend
lsof -ti:8000 | xargs kill

# Stop frontend
lsof -ti:3000 | xargs kill

---

✅ Verify Everything is Working

1. Check Backend Health:

curl http://localhost:8000/api/health

Expected response:

{
  "success": true,
  "data": {
    "status": "healthy",
    "version": "1.0.0"
  }
}

2. Check Database Data:

curl http://localhost:8000/api/dashboard/kpis

Expected response:

{
  "success": true,
  "data": [
    {
      "title": "Total Participants",
      "value": 1500,
      ...
    }
  ]
}

3. Check Frontend:

• Open http://localhost:3000
• You should see the main dashboard
• KPIs should show real data (1,500 participants)

---

🔧 Troubleshooting

Port Already in Use

# Check what's using the ports
lsof -i :8000 -i :3000

# Kill specific port
lsof -ti:8000 | xargs kill  # Backend
lsof -ti:3000 | xargs kill  # Frontend

Backend Database Connection Error

# Check if database exists
psql -U nhla -d mgslg_analytics -c "SELECT COUNT(*) FROM participants;"

# If database doesn't exist, run:
cd backend
python seed_database.py

Frontend Can’t Connect to Backend

1. Check backend is running: curl http://localhost:8000/api/health
2. Check frontend env: echo $NEXT_PUBLIC_API_URL (should be empty for localhost)
3. Restart frontend: cd frontend && pnpm run dev

Dependencies Missing

Backend:

cd backend
source .venv/bin/activate
pip install -r requirements.txt

Frontend:

cd frontend
pnpm install

---

📊 Understanding the Stack

Backend (FastAPI + Python)

• Framework: FastAPI 0.104.1
• Database: PostgreSQL (mgslg_analytics)
• ORM: SQLAlchemy 2.0.23 (async)
• Package Manager: pip
• Virtual Environment: .venv/

Frontend (Next.js + TypeScript)

• Framework: Next.js 14.0.0
• Package Manager: pnpm (NOT npm!)
• API Client: Custom fetch-based client
• State: React hooks

Database

• Type: PostgreSQL
• Name: mgslg_analytics
• Records: 1,500 participants, 3,724 enrollments
• Location: Local (localhost:5432)

---

📁 Project Structure

mathew-goniwe/
├── backend/               # Python/FastAPI backend
│   ├── app/
│   │   ├── main.py       # FastAPI application
│   │   ├── api/routes/   # API endpoints
│   │   ├── models/       # Database models
│   │   └── core/         # Config, database
│   ├── .venv/            # Python virtual environment
│   ├── seed_database.py  # Database seeding script
│   └── requirements.txt  # Python dependencies
│
├── frontend/             # Next.js/TypeScript frontend
│   ├── src/
│   │   ├── pages/        # Next.js pages
│   │   ├── components/   # React components
│   │   ├── hooks/        # Custom hooks
│   │   └── lib/          # API client
│   ├── node_modules/     # Node dependencies
│   └── package.json      # pnpm dependencies
│
├── start_dev.sh          # Start all servers
├── stop_dev.sh           # Stop all servers
├── QUICK_START.md        # This file
├── DEPLOYMENT_GUIDE.md   # Railway deployment
└── IMPLEMENTATION_SUMMARY.md  # Full report

---

🎯 Common Tasks

Reseed Database

cd backend
source .venv/bin/activate
python seed_database.py

View Backend Logs

tail -f /tmp/mgslg-backend.log

View Frontend Logs

tail -f /tmp/mgslg-frontend.log

Check Running Processes

ps aux | grep -E "uvicorn|next-server"

Test All API Endpoints

# Health check
curl http://localhost:8000/api/health

# Dashboard KPIs
curl http://localhost:8000/api/dashboard/kpis

# Geographic data
curl http://localhost:8000/api/dashboard/geographic

# ML predictions
curl http://localhost:8000/api/ml/career-progression?limit=5

# Predictive insights
curl http://localhost:8000/api/ml/predictive-insights

---

📚 Additional Resources

• Full Documentation: See README.md
• Deployment Guide: See DEPLOYMENT_GUIDE.md
• Implementation Report: See IMPLEMENTATION_SUMMARY.md
• Local Demo Setup: See LOCAL-DEMO-SETUP.md

---

💡 Tips

1. Always activate the virtual environment before running Python commands
2. Use pnpm, not npm for frontend dependencies
3. Backend must be running before frontend can fetch data
4. Database must be seeded for real data to appear
5. Check logs (/tmp/mgslg-*.log) if something doesn’t work

---

🎉 You’re Ready!

The MGSLG Analytics Platform is now running locally with:

• ✅ 1,500 real participants
• ✅ Functional ML analytics
• ✅ Interactive dashboard
• ✅ Complete API documentation

Next Steps:

1. Open http://localhost:3000 in your browser
2. Explore the dashboard and ML analytics
3. Check API docs at http://localhost:8000/docs
4. Review DEPLOYMENT_GUIDE.md for production deployment

---

Need Help?

• Check IMPLEMENTATION_SUMMARY.md for detailed info
• Review API docs at http://localhost:8000/docs
• Check logs in /tmp/mgslg-*.log

Last Updated: September 30, 2025