markdown
# MAGNUM ERP - System Architecture

## Overview
MAGNUM ERP is a department-based Enterprise Resource Planning system built with FastAPI, SQLAlchemy, and PostgreSQL. It features role-based access control, department-specific dashboards, and comprehensive business process management for engineering and contracting companies.

---

## System Architecture Diagram
┌─────────────────────────────────────────────────────────────────────────────┐
│ MAGNUM ERP SYSTEM │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PRESENTATION LAYER (Frontend) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Dashboard │ │ Customers│ │Enquiries │ │ BOQ │ │ Projects │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Materials│ │Task Board│ │ Users │ │ Reports │ │ Admin │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────▼───────────────────────────────────┐ │
│ │ API LAYER (FastAPI Routes) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Auth │ │ Customer │ │ Enquiry │ │ BOQ │ │ Material │ │ │
│ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Project │ │Task Board│ │ Users │ │Dashboard │ │ Reports │ │ │
│ │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ Routes │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────▼───────────────────────────────────┐ │
│ │ SERVICE LAYER (Business Logic) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Enquiry │ │ BOQ │ │ Customer │ │ Material │ │ Project │ │ │
│ │ │ Service │ │ Service │ │ Service │ │ Service │ │ Service │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Task │ │ User │ │ │
│ │ │ Service │ │ Service │ │ │
│ │ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────▼───────────────────────────────────┐ │
│ │ DATA LAYER (SQLAlchemy Models) │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ User │ │Customer │ │ Enquiry │ │ BOQ │ │ Material │ │ │
│ │ │ Models │ │ Models │ │ Models │ │ Models │ │ Models │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Project │ │ Task │ │Document │ │Department│ │ Role │ │ │
│ │ │ Models │ │ Models │ │ Models │ │ Models │ │ Models │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────────────────────▼───────────────────────────────────┐ │
│ │ DATABASE (PostgreSQL) │ │
│ │ ┌─────────────────────────────────────────────────────────────┐ │ │
│ │ │ Tables: users, departments, roles, customers, enquiries, │ │ │
│ │ │ boqs, boq_items, materials, material_prices, projects, │ │ │
│ │ │ tasks, enquiry_documents, project_documents, audit_logs │ │ │
│ │ └─────────────────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘

text

---

## Core Modules

### 1. Authentication & Authorization
- **JWT-based authentication** with HTTP-only cookies
- **Role-Based Access Control (RBAC)** - Admin, Director, Engineer, etc.
- **Department-Based Permissions** - QC, IT, Finance, Procurement, Admin, Management
- **Permission System** - Granular permissions per module

### 2. User Management
- User creation, editing, deactivation
- Department and role assignment
- User permissions management

### 3. Customer Management
- Complete CRUD operations
- Customer dashboard with enquiry history
- Soft delete with data preservation

### 4. Enquiry Management
- Enquiry creation with document upload
- Status tracking (New → Assigned → Quoted → Won/Lost)
- Customer linking with deleted customer handling
- Soft delete with BOQ preservation

### 5. BOQ (Bill of Quantities) Builder
- Quotation creation from enquiries
- Dynamic item management
- PDF and Word export
- Status tracking (Draft → Submitted → Approved → Suspended)

### 6. Material Management
- Material catalog with pricing history
- Search and filter capabilities
- Price tracking with audit trail

### 7. Project Management
- Project creation from enquiries/BOQs
- Work order generation
- Procurement material list
- Project analytics (budget, timeline, progress)

### 8. Task Board
- ClickUp-style task management
- Role-based views (Admin, Department Head, Personal)
- Comments, checklist, tags, activity log

### 9. Dashboard
- Department-specific KPIs and widgets
- Role-based data visibility
- Real-time counts and recent activity

---

## Database Schema

### Core Tables
departments roles
├── id ├── id
├── name ├── name
├── abbreviation ├── department_id → departments.id
├── description ├── level (1-5)
└── is_active └── permissions (JSON)

users customers enquiries
├── id ├── id ├── id
├── username ├── company_name ├── enquiry_number
├── email ├── customer_code ├── customer_id → customers.id
├── hashed_password ├── contact_name ├── subject
├── full_name ├── email ├── status
├── department_id ├── telephone ├── priority
├── role_id └── is_active ├── description
├── is_active ├── assigned_to
├── is_department_head ├── due_date
└── permissions (JSON) ├── date_received
├── is_deleted (soft delete)
└── deleted_at

boqs boq_items materials
├── id ├── id ├── id
├── enquiry_id ├── boq_id ├── material_code
├── quotation_number├── line_number ├── description
├── currency ├── description ├── category
├── subtotal ├── qty ├── unit
├── vat_percent ├── unit ├── current_price
├── grand_total ├── rate └── status
└── status └── amount

projects tasks audit_logs
├── id ├── id ├── id
├── project_code ├── title ├── user_id → users.id
├── project_name ├── description ├── action
├── customer_id ├── status ├── details (JSON)
├── enquiry_id ├── priority ├── ip_address
├── boq_id ├── assigned_to └── created_at
├── client_order ├── due_date
├── work_order_ref ├── department
├── budget ├── tags (JSON)
├── actual_cost ├── comments (JSON)
├── progress └── checklist (JSON)
└── status

text

---

## Security Architecture

### Permission Hierarchy
Level 1: Admin (Full System Access)
Level 2: Director (Department Oversight)
Level 3: Department Head (Department Management)
Level 4: Engineer (Technical Work)
Level 5: Staff (Basic Access)

text

### Department Permissions

| Department | View Quotations | View Customers | View Materials | View Tasks |
|------------|-----------------|----------------|----------------|------------|
| QC         | ❌              | ❌             | ✅             | ✅         |
| IT         | ❌              | ❌             | ❌             | ✅         |
| Finance    | ✅              | ✅             | ❌             | ✅         |
| Procurement| ✅              | ✅             | ✅             | ✅         |
| Admin      | ❌              | ❌             | ❌             | ✅         |
| Management | ✅              | ✅             | ✅             | ✅         |

---

## Technology Stack

| Layer | Technology |
|-------|-----------|
| **Backend Framework** | FastAPI (Python) |
| **ORM** | SQLAlchemy 2.0 |
| **Database** | PostgreSQL |
| **Authentication** | JWT with HTTP-only cookies |
| **Password Hashing** | Argon2id (pwdlib) |
| **Templating** | Jinja2 |
| **Reporting** | ReportLab (PDF), python-docx (Word) |
| **Frontend** | HTML5, CSS3, Bootstrap 5 |
| **Icons** | Bootstrap Icons |

---

## API Endpoints

### Authentication
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/auth/login` | Login page |
| POST | `/auth/login` | Login handler |
| GET | `/auth/logout` | Logout |
| GET | `/auth/status` | Check auth status |

### Users (Admin Only)
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/users` | List users |
| GET | `/users/new` | New user form |
| POST | `/users/new` | Create user |
| GET | `/users/{id}/edit` | Edit user form |
| POST | `/users/{id}/edit` | Update user |

### Customers
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/customers` | List customers |
| GET | `/customers/new` | New customer form |
| POST | `/customers/new` | Create customer |
| GET | `/customers/{id}` | Customer dashboard |
| GET | `/customers/{id}/edit` | Edit customer |
| POST | `/customers/{id}/delete` | Delete customer |

### Enquiries
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/enquiries` | List enquiries |
| GET | `/enquiries/new` | New enquiry form |
| POST | `/enquiries/new` | Create enquiry |
| GET | `/enquiries/{id}` | Enquiry workspace |
| POST | `/enquiries/{id}/delete` | Soft delete enquiry |

### BOQ
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/boq` | BOQ workspace |
| GET | `/boq/builder/{id}` | BOQ builder |
| POST | `/boq/save/{id}` | Save BOQ |
| GET | `/boq/view/{id}` | View BOQ |
| GET | `/boq/download-pdf/{id}` | Download PDF |
| GET | `/boq/download-word/{id}` | Download Word |

### Projects
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/projects` | Project list |
| GET | `/projects/new` | New project form |
| POST | `/projects/new` | Create project |
| GET | `/projects/{id}` | Project workspace |
| GET | `/projects/reports` | Project reports |

### Task Board
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/task-board` | Task board |
| GET | `/task-board/new` | New task form |
| POST | `/task-board/new` | Create task |
| GET | `/task-board/{id}` | Task detail |
| POST | `/task-board/{id}/status` | Update status |
| POST | `/task-board/{id}/comment` | Add comment |

---

## Deployment

### Requirements
- Python 3.11+
- PostgreSQL 14+
- pip (Python package manager)

### Environment Variables
```env
DATABASE_URL=postgresql://user:password@localhost:5432/magnum_erp
SECRET_KEY=your_secret_key
JWT_SECRET=your_jwt_secret
Installation
bash
# Clone repository
git clone <repository_url>
cd magnum-erp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Setup database
python setup_database.py

# Run application
python main.py
Performance Considerations
Database Indexing: All foreign keys and frequently searched fields are indexed

Query Optimization: Service layer handles complex queries efficiently

Caching: Ready for Redis integration (optional)

Connection Pooling: SQLAlchemy connection pooling enabled

Future Enhancements
Email Notifications - Automated alerts for task assignments

REST API - Full RESTful API for external integrations

Mobile App - React Native mobile application

Advanced Analytics - PowerBI/Tableau integration

Document Management - Advanced document version control

Inventory Management - Real-time stock tracking

HR Module - Employee management and payroll

Contributing
Fork the repository

Create a feature branch

Commit changes with descriptive messages

Submit pull request for review

License
This project is proprietary to Magnum Engineering & General Contractors Ltd.
Unauthorized use, copying, or distribution is prohibited.

Documentation Version 1.0 - July 2026

text

---

## 📄 File 2: `DOCUMENTATION.md` (User Guide)

```markdown
# MAGNUM ERP - User Documentation

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Dashboard](#dashboard)
4. [Customer Management](#customer-management)
5. [Enquiry Management](#enquiry-management)
6. [BOQ Builder](#boq-builder)
7. [Material Management](#material-management)
8. [Project Management](#project-management)
9. [Task Board](#task-board)
10. [User Management](#user-management)
11. [Reports](#reports)
12. [FAQ](#faq)

---

## Introduction

MAGNUM ERP is a comprehensive business management system designed for Magnum Engineering & General Contractors Ltd. It helps manage customers, enquiries, quotations, projects, materials, and tasks efficiently.

### Key Features

- **Department-Specific Dashboards** - Each department sees relevant data
- **Role-Based Access Control** - Secure access based on user role
- **Complete Project Lifecycle** - From enquiry to project completion
- **Integrated BOQ Builder** - Create professional quotations
- **Task Management** - ClickUp-style task board
- **Real-Time Updates** - Live data across all modules

---

## Getting Started

### First-Time Login

1. Open your browser and go to: `http://localhost:8000/auth/login`
2. Enter the default credentials:
   - **Username**: `admin`
   - **Password**: `admin123`
3. Click **Login**
4. **IMPORTANT**: Change your password immediately after first login

### Changing Password

1. Click on your username in the top right corner
2. Select **Change Password**
3. Enter current password and new password
4. Click **Save**

### Navigation

The main navigation bar contains:
- **Dashboard** - Home page with department-specific KPIs
- **Customers** - Manage customer database
- **Enquiries** - Track and manage enquiries
- **BOQ Builder** - Create quotations
- **Materials** - Manage material catalog
- **Projects** - Project management
- **Task Board** - Task management
- **Users** - User management (Admin only)
- **Reports** - Generate reports

---

## Dashboard

The dashboard is your home page. It displays department-specific information based on your role.

### QC Department Dashboard

**Visible KPIs:**
- Pending Inspections
- Tests Scheduled
- Non-conformities
- Today's Tasks

**Quick Actions:**
- New Inspection
- Log Non-conformity
- View Test Results

### IT Department Dashboard

**Visible KPIs:**
- Open Tickets
- Systems Online
- Pending Updates
- Security Alerts

**Quick Actions:**
- New Ticket
- System Check
- User Access

### Finance Department Dashboard

**Visible KPIs:**
- Pending Invoices
- Budget Utilized
- Pending Approvals
- Cash Flow

**Quick Actions:**
- New Invoice
- Approve Payment
- Generate Report

### Procurement Dashboard

**Visible KPIs:**
- Open RFQs
- Pending Orders
- Supplier Performance
- Stock Alerts

**Quick Actions:**
- New RFQ
- Create PO
- Supplier Evaluation

### Management Dashboard

**Visible KPIs:**
- Total Staff
- Revenue
- Projects
- Risks

**Quick Actions:**
- View All Departments
- Strategic Report
- Risk Assessment

---

## Customer Management

### Adding a New Customer

1. Go to **Customers** → **New Customer**
2. Fill in the required fields:
   - **Company Name** (required)
   - **Trading Name** (optional)
   - **Registration Number** (optional)
   - **VAT Number** (optional)
   - **Physical Address** (street, city, province, postal code)
   - **Contact Person** (name, email, telephone)
3. Click **Save Customer**

### Viewing Customer Details

1. Click on any customer in the customer list
2. The customer dashboard shows:
   - **Overview** - Basic information
   - **Enquiries** - All enquiries for this customer
   - **Quotations** - All BOQs for this customer
   - **Documents** - All uploaded documents
   - **Projects** - All projects for this customer

### Editing a Customer

1. Go to the customer's dashboard
2. Click **Edit Customer**
3. Update the information
4. Click **Save Changes**

### Deleting a Customer

⚠️ **Warning**: Only Administrators can delete customers. This action cannot be undone!

1. Go to the customer's dashboard
2. Click **Delete Customer**
3. Confirm deletion
4. The customer will be permanently deleted and all related enquiries will have customer_id set to NULL

---

## Enquiry Management

### Creating a New Enquiry

1. Go to **Enquiries** → **New Enquiry**
2. Select or create a customer:
   - **Existing Customer**: Select from dropdown
   - **New Customer**: Click "New Customer" and fill in details
3. Fill in enquiry details:
   - **Subject** (required)
   - **Enquiry Type** (Electrical, Mechanical, Civil, Solar, HVAC)
   - **Source** (Email, Walk-in, Telephone, Website, Tender, Referral)
   - **Priority** (Low, Normal, High, Urgent)
   - **Description** (detailed requirements)
   - **Assigned To** (engineer responsible)
   - **Received By** (who received the enquiry)
   - **Date Received** (when it was received)
   - **Due Date** (when it's needed)
4. **Upload Documents** (optional)
   - Click **Choose Files** to select documents
   - Supported formats: PDF, Word, Excel, Images
5. Click **Save Enquiry**

### Managing an Enquiry

1. Go to the enquiry workspace
2. The workspace shows:
   - **Enquiry Details** - All enquiry information
   - **Documents** - Uploaded documents
   - **BOQ Status** - Whether a quotation exists
   - **Actions** - Create BOQ, Edit, Delete

### Updating Enquiry Status

1. Go to the enquiry workspace
2. Click the **Status** dropdown
3. Select the new status:
   - **New** - Initial state
   - **Assigned** - Assigned to engineer
   - **Design** - In design phase
   - **Estimating** - Cost estimation in progress
   - **Quoted** - Quotation sent to customer
   - **Won** - Project won
   - **Lost** - Project lost
   - **Cancelled** - Enquiry cancelled

### Creating a BOQ from Enquiry

1. Go to the enquiry workspace
2. Click **Create Quotation**
3. If a BOQ already exists, you'll be redirected to view it
4. If no BOQ exists, you'll be redirected to the BOQ Builder

### Deleting an Enquiry

⚠️ **Warning**: Only Administrators can delete enquiries.

1. Go to the enquiry workspace
2. Click **Delete Enquiry**
3. Confirm deletion
4. The enquiry will be soft-deleted (hidden from view but preserved in database)
5. All BOQs linked to the enquiry will have enquiry_id set to NULL

---

## BOQ Builder

### Creating a Quotation

1. Go to **BOQ** → **Create Quotation**
2. Select an enquiry without an existing BOQ
3. In the BOQ Builder:

   **Step 1: Add Items**
   - Enter item description, quantity, unit, and rate
   - Click **Add Item** or press Enter
   - Add as many items as needed

   **Step 2: Add Costs**
   - **Labour** - Direct labor costs
   - **Consumables** - Consumable materials
   - **Equipment** - Equipment hire/usage
   - **Other Charges** - Miscellaneous costs

   **Step 3: Configure**
   - **Currency** - Select currency (USD, KES, etc.)
   - **Exchange Rate** - If using foreign currency
   - **VAT %** - Default is 15%
   - **Engineer Comments** - Notes/justification

4. Click **Save Quotation**

### Viewing a Quotation

1. Go to **BOQ**
2. Click on any quotation in the list
3. The quotation view shows:
   - **Quotation Details** - Number, status, date
   - **Customer Information** - Customer details
   - **BOQ Items** - All items with quantities and rates
   - **Cost Summary** - Subtotal, VAT, Grand Total
   - **Engineer Comments** - Notes

### Downloading a Quotation

1. Go to the quotation view
2. Click:
   - **Download PDF** - For professional PDF quotation
   - **Download Word** - For editable Word document

### Updating BOQ Status

1. Go to the quotation view
2. Click the **Status** dropdown
3. Select new status:
   - **Draft** - Work in progress
   - **Submitted** - Sent to customer
   - **Approved** - Approved by management
   - **Suspended** - On hold

### Reassigning a Quotation

⚠️ **Warning**: Only Administrators can reassign quotations.

1. Go to the quotation view
2. Click **Reassign Quotation**
3. Select the new assigned engineer
4. Click **Save**

### Deleting a Quotation

1. Go to the quotation view
2. Click **Delete Quotation**
3. Confirm deletion
4. The BOQ and all its items will be permanently deleted

---

## Material Management

### Adding a New Material

1. Go to **Materials** → **New Material**
2. Fill in the details:
   - **Description** (required)
   - **Category** (e.g., Cables, Steel, Electronics)
   - **Manufacturer**
   - **Supplier**
   - **Part Number**
   - **Unit** (m, kg, pcs, etc.)
   - **Current Price**
   - **Minimum Stock**
   - **Reorder Level**
   - **Location**
   - **Status** (Active, Inactive, Discontinued)
3. Click **Save Material**

### Managing Materials

1. Go to **Materials**
2. Use the **Search** bar to find materials
3. Use **Category** and **Status** filters to narrow results
4. Click on any material to view its workspace:
   - **Material Details** - All information
   - **Price History** - Last 3 prices
   - **Related Data** - Projects using this material

### Updating Material Price

1. Go to the material workspace
2. Enter the new price
3. Click **Update Price**
4. The old price will be preserved in history

---

## Project Management

### Creating a New Project

1. Go to **Projects** → **New Project**
2. Select or create:
   - **Customer** (required)
   - **Enquiry** (optional)
   - **BOQ** (optional - auto-fills job description)
3. Fill in project details:
   - **Project Name** (required)
   - **Work Order Reference** (auto-generated or manual)
   - **User Initials** (for work order generation)
   - **Job Description**
   - **Scope of Work**
   - **Dates** (Start Date, Expected End Date)
   - **Financials** (Budget)
   - **Status** (Pipeline, Design, Construction, etc.)
   - **Priority** (Low, Medium, High, Critical)
   - **Assigned To** (Project Manager)
4. Click **Create Project**

### Managing a Project

1. Go to the project workspace
2. The workspace shows:
   - **Project Overview** - All project details
   - **Task Analytics** - Task breakdown
   - **Financial Analytics** - Budget vs Actual
   - **Timeline** - Project timeline
   - **Materials** - Materials from BOQ

### Updating Project Status

1. Go to the project workspace
2. Click the **Status** dropdown
3. Select the new status:
   - **Pipeline** - Initial stage
   - **Design** - Design phase
   - **Construction** - Execution phase
   - **On Hold** - Temporary pause
   - **Completed** - Project finished
   - **Cancelled** - Project cancelled

### Updating Project Progress

1. Go to the project workspace
2. Enter the progress percentage (0-100)
3. Click **Update Progress**

### Adding Remarks

1. Go to the project workspace
2. Enter your comment in the **Remarks** box
3. Click **Add Remark**
4. Remarks are timestamped with the user's name

### Procurement View

1. Go to the project workspace
2. Click **Procurement**
3. View:
   - **Material List** - All materials needed
   - **Client Order Number**
   - **Procurement Status** (Pending, Ordered, Received, Completed)
4. Update procurement status and client order number

---

## Task Board

The Task Board is a ClickUp-style task management system.

### Role-Based Views

**Admin/Director View**:
- All tasks across all departments
- Can assign tasks to anyone
- Can delete tasks

**Department Head View**:
- All tasks in their department
- Can assign tasks within department
- Can view department statistics

**Personal View**:
- Only tasks assigned to the user
- Can update own task status
- Can comment and add checklist items

### Creating a Task

1. Go to **Task Board** → **New Task**
2. Fill in the details:
   - **Title** (required)
   - **Description**
   - **Task Type** (Fabrication, Machining, Assembly, etc.)
   - **Status** (New Request → Completed)
   - **Priority** (Critical, High, Medium, Low)
   - **Assigned To**
   - **Due Date**
   - **Start Date**
   - **Estimated Hours**
   - **Enquiry** (optional link)
   - **Project** (optional link)
   - **Department**
   - **Work Order Number**
   - **Client Name**
   - **Machine/Equipment**
   - **Tags** (comma-separated)
3. Click **Create Task**

### Task Detail View

1. Click on any task in the task board
2. The detail view shows:
   - **Task Information** - All task details
   - **Checklist** - Add and toggle checklist items
   - **Comments** - Add and view comments
   - **Activity Log** - All task activities
   - **Quick Actions** - Update status, edit, delete

### Updating Task Status

1. In the task detail view, click the **Status** dropdown
2. Select the new status:
   - **New Request**
   - **Assigned**
   - **Design**
   - **Material Planning**
   - **In Progress**
   - **QA/Review**
   - **Completed**
   - **Blocked**
   - **Cancelled**

### Using Checklist

1. In the task detail view, go to **Checklist**
2. Enter an item and click **Add**
3. Click the checkbox to toggle completion
4. Completed items are automatically tracked

### Comments

1. In the task detail view, go to **Comments**
2. Enter your comment
3. Click **Post Comment**
4. Comments are timestamped with the user's name

### Adding Tags

1. In the task detail view, go to **Tags**
2. Enter a tag and press Enter
3. Tags help categorize tasks
4. Click the **X** on a tag to remove it

---

## User Management (Admin Only)

### Adding a New User

1. Go to **Users** → **New User**
2. Fill in the details:
   - **Username** (required, unique)
   - **Full Name**
   - **Email** (required, unique)
   - **Password** (required)
   - **Department** (select from dropdown)
   - **Role** (select from dropdown)
   - **Active** (checkbox)
   - **Department Head** (checkbox)
3. Click **Save User**

### Editing a User

1. Go to **Users**
2. Click **Edit** on the user's row
3. Update the information
4. Click **Save Changes**

### Viewing User Profile

1. Go to **Users**
2. Click **Profile** on the user's row
3. View:
   - **User Information** - All user details
   - **Department Colleagues** - Other users in same department

### Managing User Permissions

1. Go to **Users**
2. Click **Permissions** on the user's row
3. Toggle permissions on/off
4. Click **Save Permissions**

### Activating/Deactivating Users

1. Go to **Users**
2. Click:
   - **Activate** (green button) to activate an inactive user
   - **Deactivate** (red button) to deactivate an active user
3. Deactivated users cannot log in

### Deleting a User

⚠️ **Warning**: Users cannot be restored after deletion!

1. Go to **Users**
2. Click **Delete** (trash icon) on the user's row
3. Confirm deletion
4. The user will be permanently deleted

---

## Reports

### Generating Reports

1. Go to **Reports**
2. Select the report type:
   - **BOQ Reports** - Quotation statistics
   - **Project Reports** - Project analytics
   - **Task Reports** - Task statistics
3. Apply filters:
   - **Period** (Day, Week, Month, Custom)
   - **Status** (filter by status)
   - **Engineer/Assignee** (filter by person)

### Exporting Reports

1. Generate the report with your filters
2. Click:
   - **Export PDF** - For professional PDF report
   - **Export CSV** - For spreadsheet analysis

---

## FAQ

### General

**Q: I forgot my password. How do I reset it?**
A: Contact your system administrator to reset your password.

**Q: How do I change my password?**
A: Click on your username in the top right corner and select "Change Password".

**Q: Why can't I see certain data?**
A: Your access is determined by your department and role. Contact your manager if you need additional permissions.

### Customers

**Q: Can I recover a deleted customer?**
A: No, customer deletion is permanent. All related enquiries will have customer_id set to NULL.

**Q: Why does a customer show as "Deleted Customer"?**
A: The customer was deleted but the enquiry/project was preserved. The customer data is no longer available.

### Enquiries

**Q: What happens to BOQs when I delete an enquiry?**
A: BOQs are preserved but the enquiry_id is set to NULL. The BOQ will show "Deleted Enquiry".

**Q: Can I restore a soft-deleted enquiry?**
A: Yes, contact your system administrator to restore it.

### BOQ

**Q: How do I create a quotation from an enquiry?**
A: Go to the enquiry workspace and click "Create Quotation".

**Q: What formats can I export a quotation to?**
A: PDF and Word (.docx) formats are supported.

### Tasks

**Q: Why can't I see certain tasks?**
A: Task visibility depends on your role. Admin/Director sees all tasks. Department Head sees department tasks. Staff sees only their assigned tasks.

**Q: How do I assign a task to someone else?**
A: Admin/Director/Department Heads can assign tasks. Go to the task detail view and update the "Assigned To" field.

### Projects

**Q: How is the work order reference generated?**
A: Format: `MEGCL/DD/MM/INITIALS/XXX` (e.g., MEGCL/25/07/PM/001). It's auto-generated or manually entered.

**Q: Can I edit a project after it's created?**
A: Yes, all project fields can be edited except the project code.

---

## Support

For technical support, contact:
- **System Administrator**: admin@magnum.com
- **IT Department**: it@magnum.com

---

*Documentation Version 1.0 - July 2026*