5why-analyzer/docs/SDD.md

# System Design Document (SDD)
## 5 Why Root Cause Analyzer

**Project Name**: 5 Why Root Cause Analyzer
**Version**: 1.0.0
**Date**: 2025-12-05
**Status**: Production Ready

---

## 1. Executive Summary

The 5 Why Root Cause Analyzer is an enterprise-grade web application that leverages AI (Ollama) to perform structured root cause analysis using the 5 Why methodology. The system analyzes problems from three perspectives (technical, process, human) to identify root causes and suggest solutions.

### Key Features
- AI-powered 5 Why analysis with Ollama (qwen2.5:3b model)
- Multi-perspective analysis (technical, process, human factors)
- 7 language support (繁中, 簡中, English, 日本語, 한국어, Tiếng Việt, ภาษาไทย)
- Role-based access control (user, admin, super_admin)
- Complete audit trail
- Admin dashboard with statistics
- User management system

---

## 2. System Architecture

### 2.1 High-Level Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Client Layer                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  React 18 + Vite + Tailwind CSS                  │  │
│  │  - Login Page                                     │  │
│  │  - Analysis Tool                                  │  │
│  │  - History Viewer                                 │  │
│  │  - Admin Dashboard                                │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────────────┘
                  │ HTTP/HTTPS (Session Cookies)
                  │
┌─────────────────▼───────────────────────────────────────┐
│                  API Gateway Layer                      │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Express.js Server                                │  │
│  │  - Helmet (Security Headers)                      │  │
│  │  - CORS (Cross-Origin)                            │  │
│  │  - Rate Limiting (100 req/15min)                  │  │
│  │  - Session Management (express-session)           │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────────────┘
                  │
    ┌─────────────┴──────────────┐
    │                            │
┌───▼─────────────────┐  ┌──────▼──────────────────┐
│  Routes Layer       │  │  AI Service             │
│  ┌───────────────┐  │  │  ┌──────────────────┐  │
│  │ Auth Routes   │  │  │  │ Ollama API       │  │
│  │ Analyze Routes│  │  │  │ qwen2.5:3b       │  │
│  │ Admin Routes  │  │  │  │ (External)       │  │
│  └───────────────┘  │  │  └──────────────────┘  │
└───┬─────────────────┘  └─────────────────────────┘
    │
┌───▼─────────────────────────────────────────────┐
│           Business Logic Layer                  │
│  ┌────────────────┐  ┌─────────────────────┐   │
│  │ Middleware     │  │ Models              │   │
│  │ - auth.js      │  │ - User.js           │   │
│  │ - errorHandler │  │ - Analysis.js       │   │
│  └────────────────┘  │ - AuditLog.js       │   │
│                      └─────────────────────┘   │
└───┬─────────────────────────────────────────────┘
    │
┌───▼─────────────────────────────────────────────┐
│              Data Layer                         │
│  ┌──────────────────────────────────────────┐  │
│  │  MySQL 9.4.0 Database                     │  │
│  │  - 8 Tables (users, analyses, etc.)       │  │
│  │  - 2 Views (statistics)                   │  │
│  │  - Connection Pool (mysql2)               │  │
│  └──────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
```

### 2.2 Technology Stack

**Frontend**:
- React 18.2 (UI framework)
- Vite 5.0 (build tool)
- Tailwind CSS 3.4 (styling)
- Context API (state management)
- Fetch API (HTTP client)

**Backend**:
- Node.js 18+ (runtime)
- Express 4.18 (web framework)
- mysql2 3.6 (database driver)
- bcryptjs 2.4 (password hashing)
- express-session 1.17 (session management)
- helmet 7.1 (security headers)
- express-rate-limit 7.1 (rate limiting)

**Database**:
- MySQL 9.4.0
- InnoDB engine
- utf8mb4_unicode_ci collation

**AI/LLM**:
- Ollama API (https://ollama_pjapi.theaken.com)
- Model: qwen2.5:3b
- Streaming: No (full response)

---

## 3. Database Design

### 3.1 Entity Relationship Diagram

```
┌──────────────┐         ┌─────────────────┐
│    users     │────1:N──│    analyses     │
│              │         │                 │
│ - id (PK)    │         │ - id (PK)       │
│ - employee_id│         │ - user_id (FK)  │
│ - username   │         │ - finding       │
│ - email      │         │ - job_content   │
│ - role       │         │ - status        │
│ - password   │         └─────────┬───────┘
└──────┬───────┘                   │
       │                           │
       │                     ┌─────▼──────────────┐
       │                     │ analysis_perspectives│
       │                     │                     │
       │                     │ - id (PK)           │
       │                     │ - analysis_id (FK)  │
       │                     │ - perspective_type  │
       │                     │ - root_cause        │
       │                     │ - solution          │
       │                     └─────────┬───────────┘
       │                               │
       │                         ┌─────▼─────────┐
       │                         │ analysis_whys │
       │                         │               │
       │                         │ - id (PK)     │
       │                         │ - perspective_id│
       │                         │ - why_level   │
       │                         │ - question    │
       │                         │ - answer      │
       │                         └───────────────┘
       │
       │
   ┌───▼───────────┐
   │  audit_logs   │
   │               │
   │ - id (PK)     │
   │ - user_id (FK)│
   │ - action      │
   │ - entity_type │
   │ - ip_address  │
   │ - created_at  │
   └───────────────┘

Additional Tables:
- llm_configs (LLM API configurations)
- system_settings (application settings)
- sessions (express-session storage)
```

### 3.2 Table Specifications

**users** (User accounts)
- Primary Key: `id` (INT AUTO_INCREMENT)
- Unique Keys: `email`, `employee_id`
- Indexes: `role`, `is_active`

**analyses** (Analysis records)
- Primary Key: `id` (INT AUTO_INCREMENT)
- Foreign Key: `user_id` → `users(id)`
- Indexes: `user_id`, `status`, `created_at`

**analysis_perspectives** (Multi-angle analysis)
- Primary Key: `id` (INT AUTO_INCREMENT)
- Foreign Key: `analysis_id` → `analyses(id) ON DELETE CASCADE`
- Index: `analysis_id`, `perspective_type`

**analysis_whys** (5 Why details)
- Primary Key: `id` (INT AUTO_INCREMENT)
- Foreign Key: `perspective_id` → `analysis_perspectives(id) ON DELETE CASCADE`
- Index: `perspective_id`, `why_level`

**audit_logs** (Security audit trail)
- Primary Key: `id` (INT AUTO_INCREMENT)
- Foreign Key: `user_id` → `users(id) ON DELETE SET NULL`
- Indexes: `user_id`, `action`, `created_at`

---

## 4. API Design

### 4.1 RESTful Endpoints

**Authentication** (4 endpoints):
- `POST /api/auth/login` - User login
- `POST /api/auth/logout` - User logout
- `GET /api/auth/me` - Get current user
- `POST /api/auth/change-password` - Change password

**Analysis** (5 endpoints):
- `POST /api/analyze` - Create new analysis
- `POST /api/analyze/translate` - Translate analysis
- `GET /api/analyze/history` - Get user history
- `GET /api/analyze/:id` - Get analysis detail
- `DELETE /api/analyze/:id` - Delete analysis

**Admin** (8 endpoints):
- `GET /api/admin/dashboard` - Get dashboard stats
- `GET /api/admin/users` - List all users
- `POST /api/admin/users` - Create user
- `PUT /api/admin/users/:id` - Update user
- `DELETE /api/admin/users/:id` - Delete user
- `GET /api/admin/analyses` - List all analyses
- `GET /api/admin/audit-logs` - View audit logs
- `GET /api/admin/statistics` - Get system stats

### 4.2 Response Format

All API responses follow a consistent structure:

**Success**:
```json
{
  "success": true,
  "data": { /* response data */ },
  "message": "操作成功"
}
```

**Error**:
```json
{
  "success": false,
  "error": "ErrorType",
  "message": "錯誤訊息"
}
```

---

## 5. Security Design

### 5.1 Authentication & Authorization

**Authentication Method**: Session-based
- Session storage: Server-side (in-memory)
- Cookie name: `5why.sid`
- Cookie attributes: `httpOnly`, `maxAge: 24h`
- Session duration: 24 hours

**Authorization Levels**:
1. **user**: Regular user (analysis creation, history viewing)
2. **admin**: Administrator (+ user management, system monitoring)
3. **super_admin**: Super administrator (+ all admin functions)

**Middleware Chain**:
```javascript
requireAuth → requireAdmin → requireSuperAdmin
                    ↓
              Route Handler
```

### 5.2 Security Measures

**Password Security**:
- Algorithm: bcrypt
- Salt rounds: 10
- No plaintext storage
- Hash verification on login

**SQL Injection Prevention**:
- Parameterized queries (100% coverage)
- mysql2 prepared statements
- No string concatenation

**XSS Prevention**:
- React auto-escaping
- Helmet security headers
- CSP ready (disabled in dev)

**CSRF Protection**:
- SameSite cookies (recommended)
- Session-based authentication
- CORS configuration

**Rate Limiting**:
- Window: 15 minutes
- Limit: 100 requests per IP
- Applied to all /api/* routes

**Audit Logging**:
- All authentication events
- CRUD operations
- IP address tracking
- User agent logging

---

## 6. AI Integration Design

### 6.1 Ollama API Integration

**Endpoint**: `https://ollama_pjapi.theaken.com/api/generate`

**Request Flow**:
```
User Input → Backend → Ollama API → Parse Response → Save to DB
```

**Prompt Engineering**:
```javascript
const prompt = `
你是一個專業的根因分析專家。請使用 5 Why 分析法...

【發現的現象】
${finding}

【工作內容/背景】
${jobContent}

請從以下${perspectives.length}個角度進行分析：
${perspectives.map(p => `- ${perspectiveNames[p]}`).join('\n')}

請用${languageNames[outputLanguage]}回答...
`;
```

**Response Parsing**:
- JSON format expected
- 3 perspectives (technical, process, human)
- Each perspective: 5 whys, root cause, solution
- Error handling for malformed responses

### 6.2 Analysis State Machine

```
pending → processing → completed
            ↓
          failed
```

**States**:
- `pending`: Analysis created, waiting to process
- `processing`: Sent to Ollama, awaiting response
- `completed`: Successfully analyzed and saved
- `failed`: Error occurred during processing

---

## 7. Frontend Architecture

### 7.1 Component Hierarchy

```
App
├── AuthProvider
│   └── AppContent
│       ├── LoginPage (if not authenticated)
│       └── Layout (if authenticated)
│           ├── Navigation
│           ├── UserMenu
│           └── Page Content
│               ├── AnalyzePage
│               ├── HistoryPage
│               └── AdminPage
│                   ├── DashboardTab
│                   ├── UsersTab
│                   ├── AnalysesTab
│                   └── AuditTab
```

### 7.2 State Management

**Global State** (Context API):
- `AuthContext`: User authentication state
- `ToastContext`: Notification system (Phase 6)

**Local State** (useState):
- Component-specific UI state
- Form data
- Loading states
- Error messages

### 7.3 Routing Strategy

**Client-side routing**: State-based navigation
- No react-router (simplified)
- `currentPage` state in AppContent
- Navigation via `onNavigate` callback

**Pages**:
- `analyze`: Analysis tool
- `history`: Analysis history
- `admin`: Admin dashboard

---

## 8. Deployment Architecture

### 8.1 Development Environment

```
┌─────────────────────────────────────────┐
│  Development Machine                    │
│  ┌───────────────────────────────────┐  │
│  │  Frontend (Vite Dev Server)       │  │
│  │  http://localhost:5173             │  │
│  └───────────────────────────────────┘  │
│  ┌───────────────────────────────────┐  │
│  │  Backend (Node.js)                │  │
│  │  http://localhost:3001             │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘
         │                    │
         │                    │
    ┌────▼────────┐    ┌─────▼────────────┐
    │   MySQL     │    │   Ollama API     │
    │  (Remote)   │    │   (External)     │
    │  Port 33306 │    │   HTTPS          │
    └─────────────┘    └──────────────────┘
```

### 8.2 Production Architecture (Recommended)

```
┌─────────────────────────────────────────────────────┐
│               Load Balancer / Reverse Proxy         │
│                    (Nginx / Apache)                 │
│                    HTTPS / SSL                      │
└────────┬────────────────────────────────┬───────────┘
         │                                │
    ┌────▼──────────┐              ┌─────▼──────────┐
    │  Static Files │              │  API Server    │
    │  (React Build)│              │  (Node.js)     │
    │  Port 80/443  │              │  Port 3001     │
    └───────────────┘              └────┬───────────┘
                                        │
                            ┌───────────┴──────────┐
                            │                      │
                      ┌─────▼─────┐        ┌──────▼──────┐
                      │   MySQL   │        │ Ollama API  │
                      │  (Local)  │        │ (External)  │
                      └───────────┘        └─────────────┘
```

### 8.3 Environment Variables

**Required**:
- `DB_HOST`: MySQL host
- `DB_PORT`: MySQL port (33306)
- `DB_USER`: Database user
- `DB_PASSWORD`: Database password
- `DB_NAME`: Database name
- `SESSION_SECRET`: Session encryption key
- `OLLAMA_API_URL`: Ollama API endpoint
- `OLLAMA_MODEL`: AI model name

**Optional**:
- `NODE_ENV`: Environment (development/production)
- `PORT`: Server port (default: 3001)
- `CLIENT_PORT`: Frontend port (default: 5173)

---

## 9. Performance Considerations

### 9.1 Database Optimization

**Connection Pooling**:
- Pool size: 10 connections
- Queue limit: 0 (unlimited)
- Connection timeout: Default

**Indexes**:
- All foreign keys indexed
- Query optimization indexes on:
  - `users.email`, `users.employee_id`
  - `analyses.user_id`, `analyses.status`
  - `audit_logs.user_id`, `audit_logs.created_at`

**Query Optimization**:
- Pagination on all list queries
- Lazy loading of related data
- Efficient JOIN operations

### 9.2 Caching Strategy

**Current**: No caching implemented

**Recommendations**:
- Session caching (Redis)
- Static asset caching (CDN)
- API response caching for stats

### 9.3 AI Response Time

**Typical Analysis Duration**: 30-60 seconds
- Depends on Ollama server load
- Network latency
- Model complexity

**Optimization**:
- Async processing (already implemented)
- Status updates to user
- Timeout handling (60s max)

---

## 10. Monitoring & Logging

### 10.1 Application Logging

**Audit Logs** (Database):
- Authentication events
- CRUD operations
- Admin actions
- IP addresses

**Server Logs** (Console):
- Request logging (development)
- Error logging (all environments)
- Database connection events

### 10.2 Monitoring Metrics

**Recommended Monitoring**:
- API response times
- Database query performance
- Session count
- Active users
- Analysis completion rate
- Error rates

**Tools** (Not implemented, recommended):
- PM2 for process management
- Winston for structured logging
- Prometheus + Grafana for metrics

---

## 11. Scalability

### 11.1 Current Limitations

- In-memory session storage (single server only)
- No horizontal scaling support
- Synchronous AI processing

### 11.2 Scaling Recommendations

**Horizontal Scaling**:
1. Move sessions to Redis
2. Load balancer (Nginx)
3. Multiple Node.js instances
4. Database read replicas

**Vertical Scaling**:
1. Increase server resources
2. MySQL optimization
3. Connection pool tuning

**AI Processing**:
1. Queue system (Bull/Redis)
2. Worker processes for AI calls
3. Multiple Ollama instances

---

## 12. Maintenance & Updates

### 12.1 Database Migrations

**Current**: Manual SQL execution

**Recommended**:
- Migration tool (Flyway/Liquibase)
- Version-controlled migrations
- Rollback capability

### 12.2 Backup Strategy

**Database Backups**:
- Daily full backups
- Point-in-time recovery
- Off-site storage

**Code Backups**:
- Git version control (Gitea)
- Regular commits
- Tag releases

### 12.3 Update Procedures

1. Test in development environment
2. Database migration (if needed)
3. Code deployment
4. Health check verification
5. Monitor logs

---

## 13. Known Limitations

1. **Single Language Output**: Analysis in selected language only (no on-the-fly translation)
2. **Session Storage**: In-memory (not suitable for multi-server)
3. **No Real-time Updates**: Page refresh required for new data
4. **Limited Error Recovery**: Failed analyses need manual retry
5. **No Data Export**: CSV export not yet implemented

---

## 14. Future Enhancements

### Phase 6-9 (Planned)
- Toast notification system
- CSV import/export
- Table sorting
- Enhanced loading states
- Security hardening

### Future Versions
- Multi-LLM support (Gemini, DeepSeek, OpenAI)
- PDF report generation
- Batch analysis processing
- Email notifications
- Two-factor authentication
- Real-time collaboration
- Mobile app

---

## 15. Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-12-05 | Initial release with full features |
| 0.1.0 | 2025-12-05 | Prototype with basic analysis |

---

**Document Status**: Final
**Approved By**: Development Team
**Last Updated**: 2025-12-05
**Next Review**: Before v2.0 release