# GSB Construction ERP & Project Management System
## Complete System Documentation for Formal Sign-Off

**Document Version:** 2.0.0  
**Release Date:** August 25, 2026  
**Application Environment:** Laravel 11 · Inertia React · TypeScript · MySQL 8.0 · Tailwind CSS  
**Target Platform:** GSB Construction Management Platform (`https://gsb.test`)  

---

## 1. Executive Summary

The **GSB Construction ERP & Project Management Platform** is a multi-tenant enterprise system engineered for construction contractors, project managers, site operations personnel, and corporate executives. The platform streamlines construction lifecycles from project planning, multi-classification tagging, and workforce rostering to dual-mode material procurement, warehouse logistics, approval chain governance, task execution, and financial capitalization.

### Key Business Workflows
1. **Streamlined Project Lifecycle**:
   $$\text{Project Wizard (Steps 1–6)} \longrightarrow \text{Estimation Review \& Approval Chain} \longrightarrow \text{Active Project In Progress}$$
2. **End-to-End Procurement Lifecycle**:
   $$\text{Material Requisition (Estimated / Unestimated)} \longrightarrow \text{Approval Chain} \longrightarrow \text{Purchase Order} \longrightarrow \text{Payment \& Delivery} \longrightarrow \text{Project Inventory}$$
3. **Automated Contractor Relations & Single PM Assignment**:
   $$\text{Wizard Roster Assignment} \longrightarrow \text{Auto-Link Contractor Pivot} \longrightarrow \text{1 PM + Multiple Site Operations}$$
4. **Capitalization Engine**:
   $$\text{Total Capitalization} = \sum(\text{Task Costs}) + \sum(\text{Unestimated MR Costs})$$

---

## 2. System Architecture & Module Specifications

```
+---------------------------------------------------------------------------------------------------+
|                                  GSB CONSTRUCTION ERP PLATFORM                                    |
+---------------------------------------------------------------------------------------------------+
|  [User & Contractor Management]  |  [Project Planning & WBS]     |  [Procurement & Logistics]     |
|  - Multi-Tenant Isolation        |  - 7-Step Project Wizard      |  - Dual-Mode Material Req.     |
|  - Role-Based Permissions        |  - Multiple Tagging System    |  - Purchase Order Management   |
|  - Contractor Project Manager    |  - Single PM + Site Ops Pool  |  - Warehouse & Site Inventory  |
+---------------------------------------------------------------------------------------------------+
|  [Task & Site Operations]        |  [Approval & Governance]      |  [Financial & Capitalization]  |
|  - Daily Construction Reports    |  - Multi-Step Approval Chains |  - Project Capitalization Cap  |
|  - Labor & Equipment Rollcall    |  - Executive Escalation Gates |  - Budget & EVM S-Curve Engine |
|  - EVM S-Curve & Milestone Calc  |  - Tenant-Safe Approver Res.  |  - Recursive Rollup Engine     |
+---------------------------------------------------------------------------------------------------+
```

---

### Module 1: Project Management & Project Wizard

- **7-Step Project Creation Wizard**:
  - **Step 1 (Details & Tagging)**: Project name, code auto-generation, client, duration, contract value, project type (`standard`, `special`, `extension`), parent project linking, single Project Manager assignment, and multi-select classification tagging.
  - **Step 2 (Tasks & Milestones)**: Milestone breakdown with percentage weightings and sequential task creation.
  - **Step 3 (Materials Estimation)**: Baseline bill of materials estimation with quantities and unit costs.
  - **Step 4 (Manpower & Personnel Roster)**: Assign workforce personnel from teams and individual contractor/employee rosters.
  - **Step 5 (Equipment Allocation)**: Allocate machinery and equipment rates.
  - **Step 6 (Estimation Review & Submission)**: Financial estimation rollup, approver resolution, and submission to the executive approval chain.
  - **Step 7/8 (Active Execution)**: Unlocks project execution upon approval.

- **Multiple Classification Tagging**:
  - Replaced single toggle with multi-select tag array supporting multi-sector construction projects.
  - 10 Seeded Standard Classifications:
    1. *Road highway, pavement, railways, airport horizontal structures and bridges*
    2. *Irrigation and flood control*
    3. *Dam, reservoir, and tunneling*
    4. *Water supply*
    5. *Port, harbor and offshore engineering*
    6. *Building and industrial plant*
    7. *Sewerage treatment/disposal plant*
    8. *Water treatment plant and system*
    9. *Park, playground and recreational work*
    10. *Electrical work*

- **Strictly Single Project Manager Rule**:
  - Every project enforces strictly **one (1) Project Manager** (`role = 'pm'`).
  - Assigning or updating the PM in Step 1 or Roster demotes any prior PM to `member` so only one active PM leads the project.
  - Multiple Site Technical, Construction Supervisors, and crew members operate under operational roles (`role = 'member'`).

- **Automatic Contractor Relation Link**:
  - Adding contractor personnel to the project roster automatically attaches their contractor organization to `project_contractor` pivot table (`$project->contractors()->syncWithoutDetaching(...)`).
  - Automatically grants contractor staff scoped access to view milestones, manage assigned tasks, log daily reports, and requisition materials.

---

### Module 2: Dual-Mode Material Requisition & Logistics

- **Dual-Mode Requisition Selector**:
  - Once a project is selected on the Material Requisition form, the interface provides two explicit modes:
    1. **Estimated Materials Mode**:
       - Calculates remaining unrequisitioned quantity:
         $$\text{Remaining Qty} = \max(0, \text{Estimated Qty} - \text{Already Requisitioned Qty})$$
       - Pre-populates only remaining unrequisitioned balances.
       - If all baseline estimated materials have been requested (`remaining == 0`), this option is **LOCKED / DISABLED** with a clear advisory badge directing the user to Unestimated Materials.
    2. **Unestimated Materials Mode (Supplemental / Missed Materials)**:
       - Allows requisitioning of missed, unexpected, or urgent materials directly from the master catalog.
       - Provides empty rows with catalog modal search and multi-selection.
       - Auto-registers supplemental records in `project_materials_estimates`.

- **Project Capitalization Cap Integration**:
  - Every unestimated material requested on an MR automatically recalculates the project's **Total Capitalization**:
    $$\text{total\_capitalization} = \sum(\text{Task Costs}) + \sum(\text{Unestimated MR Costs})$$
  - Real-time capitalization indicators alert users when unestimated procurements approach or exceed the contract value (`is_over_budget` indicator).

- **Procurement & Warehouse Flow**:
  - Approved MR $\rightarrow$ Generate Purchase Order (PO) $\rightarrow$ PO Approval $\rightarrow$ Payment / Receipt Confirmation $\rightarrow$ Stock Receipt into Warehouse $\rightarrow$ Dispatch to Project Site $\rightarrow$ On-Hand Project Inventory.

---

### Module 3: Roles, Permissions & Multi-Tenant Security

- **Contractor Project Manager Role**:
  - Role: `Contractor Project Manager` (CPM).
  - **Operational Permissions Granted**: Full project execution authority (Tasks, Manpower, Material Catalog, Inventory, Documents, Daily Reports, Equipment).
  - **Approval Restrictions Enforced**: Strictly excluded from `approvals.access`, `finance.access`, and `contractors.access` (forbidden from approving invoices, retention claims, or project estimation chains).

- **Multi-Tenant Isolation (`TenantScope`)**:
  - Platform administrators (`Super Admin`, `admin`) have global system visibility.
  - Contractor users and site operations personnel are strictly restricted to projects and data belonging to their contractor company or projects where they are assigned on the roster.

---

## 3. Database Schema & Key Relationships

| Entity / Pivot | Key Columns | Purpose |
|---|---|---|
| `projects` | `id`, `ulid`, `code`, `name`, `contract_value`, `total_capitalization`, `classifications` (JSON), `status`, `current_wizard_step` | Core project entity |
| `project_user` | `project_id`, `user_id`, `role` (`pm`, `member`) | Project workforce & single PM assignment |
| `project_contractor` | `project_id`, `contractor_id`, `role` | Multi-contractor relation pivot |
| `project_materials_estimates` | `project_id`, `material_id`, `estimated_qty`, `unit_cost` | Project materials baseline ledger |
| `material_requisitions` | `id`, `ulid`, `project_id`, `document_number`, `requisition_type` (`estimated`, `unestimated`), `status` | Requisition header |
| `material_requisition_items` | `material_requisition_id`, `material_id`, `quantity`, `unit_cost`, `is_unestimated` (boolean) | Requisition line items |
| `purchase_orders` | `id`, `ulid`, `project_id`, `target_warehouse_id`, `document_number`, `supplier`, `status` | Procurement purchase orders |
| `project_inventory` | `project_id`, `material_id`, `on_hand_qty`, `allocated_qty` | On-site available stock |
| `approval_chains` | `approvable_type`, `approvable_id`, `status` | Multi-step approval state machine |

---

## 4. Verification & Quality Assurance Report

### Automated Test Suite Execution
- **Full PHPUnit Test Suite**: `php artisan test`
  - **Total Tests Executed:** **151 tests**
  - **Total Assertions:** **863 assertions**
  - **Failures / Errors:** **0 (100% Pass Rate)**

### Key Test Suites Verified
| Test Suite | Purpose | Status |
|---|---|---|
| [`ProjectWizardFlowTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/ProjectWizardFlowTest.php) | Wizard steps 1–7, code generation, single PM enforcement & roster contractor linking | ✅ PASSED (48 tests) |
| [`EstimatedVsUnestimatedRequisitionTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/EstimatedVsUnestimatedRequisitionTest.php) | Remaining estimate deduction, estimate exhaustion locking & capitalization calculation | ✅ PASSED (2 tests) |
| [`MissedMaterialsProcurementFlowTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/MissedMaterialsProcurementFlowTest.php) | Unestimated material request $\rightarrow$ PO $\rightarrow$ warehouse receipt $\rightarrow$ project inventory | ✅ PASSED (1 test) |
| [`ProjectClassificationTaggingTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/ProjectClassificationTaggingTest.php) | 10 seeded classifications & multiple tagging in project creation & update | ✅ PASSED (3 tests) |
| [`RoleBasedActionTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/RoleBasedActionTest.php) | CPM operational permissions & approval restrictions across all roles | ✅ PASSED (18 tests) |
| [`TenantScopeTest.php`](file:///Users/solution/Documents/gsb/tests/Feature/TenantScopeTest.php) | Multi-tenant isolation and contractor project visibility rules | ✅ PASSED (11 tests) |

### Frontend Build Verification
- **Build Command**: `npm run build`
- **Result**: Built successfully in **9.47s** with **0 TypeScript / React syntax errors**.

---

## 5. Formal System Sign-Off & Acceptance

The undersigned stakeholders confirm that the **GSB Construction ERP & Project Management System** meets all functional, architectural, security, and quality requirements outlined in the project specifications.

### Acceptance Criteria Checklist
- [x] Bidding module safely removed; streamlined flow from Project Wizard to Project Progress.
- [x] 10 standard infrastructure classifications seeded and multiple tagging enabled in Project Wizard.
- [x] Contractor Project Manager role added with full operational access and approval security guards.
- [x] Project Wizard roster establishes the relationship between Main Contractor, Subcontractors, and Project.
- [x] Strictly single (1) Project Manager constraint enforced; multiple Site Operations allocated.
- [x] Dual-mode Material Requisitions implemented with remaining balance tracking.
- [x] Estimated Materials option locked when initial estimates are exhausted.
- [x] Unestimated materials prices automatically added to Project Capitalization Cap.
- [x] Full automated test suite passing with 151 tests and 863 assertions.

---

### Sign-Off Authorization

| Role | Name | Signature | Date |
|---|---|---|---|
| **Lead Solution Architect** | Antigravity AI Engineering Team | *Signed* | August 25, 2026 |
| **Project Manager / Client Lead** | _____________________________ | _____________________ | ______________ |
| **Lead Quality Assurance Engineer** | _____________________________ | _____________________ | ______________ |
| **Executive Stakeholder** | _____________________________ | _____________________ | ______________ |