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:

python app.py

Or using npm:

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:

npm run server

Terminal 2 - Frontend:

npm run client

---

🔧 Initial Setup (First Time Only)

1. Install Dependencies

npm install

2. Configure Environment

# 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)

npm run db:init

4. Test Database Connection

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
• API Documentation: docs/API_DOC.md
• System Design: docs/SDD.md
• Deployment Guide: docs/DEPLOYMENT_CHECKLIST.md
• Security Audit: docs/security_audit.md
• Project Status: 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

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 🤖