5why-analyzer/START_HERE.md

# 5 Why Root Cause Analyzer - Quick Start Guide

## 🚀 Quick Start (Easiest Method)

### Prerequisites
- **Python 3.7+** installed
- **Node.js 18+** installed
- **npm** installed
- Dependencies installed (`npm install`)
- `.env` file configured

### Start the Application

Simply run:

```bash
python app.py
```

Or using npm:

```bash
npm start
```

This will:
1. ✅ Check all prerequisites (Node.js, npm, dependencies, .env)
2. ✅ Start the backend server (http://localhost:3001)
3. ✅ Start the frontend server (http://localhost:5173)
4. ✅ Monitor both processes
5. ✅ Gracefully shutdown on Ctrl+C

### What You'll See

```
======================================================================
  5 Why Root Cause Analyzer - v1.0.0
  Enterprise-grade Root Cause Analysis Tool
======================================================================

[INFO] Running pre-flight checks...
[SUCCESS] Node.js detected: v20.x.x
[SUCCESS] npm detected: 10.x.x
[SUCCESS] Dependencies installed (node_modules found)
[SUCCESS] Environment file (.env) found
[SUCCESS] All pre-flight checks passed!

[INFO] Starting backend server...
[SUCCESS] Backend server started successfully
[INFO] Backend running at: http://localhost:3001

[INFO] Starting frontend development server...
[SUCCESS] Frontend server started successfully
[INFO] Frontend running at: http://localhost:5173

======================================================================
Both services are running!
======================================================================

Access the application:
  Frontend: http://localhost:5173
  Backend API: http://localhost:3001
  API Health: http://localhost:3001/health

Test Accounts:
  Admin: admin@example.com / Admin@123456
  User1: user001@example.com / User@123456
  User2: user002@example.com / User@123456

Press Ctrl+C to stop all services
```

---

## 📋 Manual Start (Alternative Method)

If you prefer to start services manually in separate terminals:

### Terminal 1 - Backend:
```bash
npm run server
```

### Terminal 2 - Frontend:
```bash
npm run client
```

---

## 🔧 Initial Setup (First Time Only)

### 1. Install Dependencies
```bash
npm install
```

### 2. Configure Environment
```bash
# Copy the example environment file
cp .env.example .env

# Edit .env with your settings
# Required: Database credentials, session secret, etc.
```

### 3. Initialize Database (if needed)
```bash
npm run db:init
```

### 4. Test Database Connection
```bash
npm run db:test
```

---

## 🌐 Access Points

Once running, access the application at:

- **Frontend**: http://localhost:5173
- **Backend API**: http://localhost:3001
- **Health Check**: http://localhost:3001/health
- **Database Health**: http://localhost:3001/health/db

---

## 👥 Default Test Accounts

| Role | Email | Password |
|------|-------|----------|
| Super Admin | admin@example.com | Admin@123456 |
| User | user001@example.com | User@123456 |
| User | user002@example.com | User@123456 |

**⚠️ IMPORTANT**: Change the admin password after first login!

---

## 🛑 Stopping the Application

### If using app.py:
Press **Ctrl+C** - This will gracefully stop both services

### If using manual method:
Press **Ctrl+C** in each terminal window

---

## ❌ Troubleshooting

### "Node.js is not installed"
- Install Node.js 18+ from https://nodejs.org/
- Ensure it's added to your PATH

### "Dependencies not installed"
- Run: `npm install`

### ".env file not found"
- Copy `.env.example` to `.env`
- Configure database and other settings

### "Port 3001 already in use"
- Check if another instance is running
- Kill the process: `taskkill /F /PID <pid>` (Windows) or `kill <pid>` (Linux)
- Or change PORT in .env

### "Port 5173 already in use"
- Vite will automatically use the next available port
- Or kill the process using port 5173

### Backend/Frontend won't start
- Check the console output for error messages
- Verify database connection in .env
- Ensure MySQL is running and accessible
- Check logs: Backend terminal for API errors, Frontend terminal for React errors

---

## 📚 Additional Resources

- **Full README**: [README_FULL.md](README_FULL.md)
- **API Documentation**: [docs/API_DOC.md](docs/API_DOC.md)
- **System Design**: [docs/SDD.md](docs/SDD.md)
- **Deployment Guide**: [docs/DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md)
- **Security Audit**: [docs/security_audit.md](docs/security_audit.md)
- **Project Status**: [PROJECT_STATUS.md](PROJECT_STATUS.md)

---

## 🎯 Features

- ✅ 5 Why Root Cause Analysis with AI (Ollama)
- ✅ Multi-language support (7 languages)
- ✅ Multi-perspective analysis (Technical, Process, Human)
- ✅ Analysis history tracking
- ✅ Admin dashboard with statistics
- ✅ User management (RBAC)
- ✅ Audit logging
- ✅ Session-based authentication
- ✅ API rate limiting
- ✅ Security rating: A (92/100)

---

## 🚀 Production Deployment

For production deployment, see: [docs/DEPLOYMENT_CHECKLIST.md](docs/DEPLOYMENT_CHECKLIST.md)

Key steps:
1. Build frontend: `npm run build`
2. Set `NODE_ENV=production` in .env
3. Use PM2 for process management
4. Configure Nginx reverse proxy
5. Set up SSL with Let's Encrypt
6. Configure firewall rules

---

## 📞 Support

- **Repository**: https://gitea.theaken.com/donald/5why-analyzer
- **Version**: 1.0.0
- **Status**: ✅ Production Ready

---

**Made with Claude Code** 🤖