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:

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

Error:

{
  "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:

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:

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