admin/GSB-Construction
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
GSB-Construction/docs/SYSTEM_DOCUMENTATION_SIGN_OFF.md

12 KiB
Raw Permalink Blame History

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 Wizard steps 1–7, code generation, single PM enforcement & roster contractor linking ✅ PASSED (48 tests)
EstimatedVsUnestimatedRequisitionTest.php Remaining estimate deduction, estimate exhaustion locking & capitalization calculation ✅ PASSED (2 tests)
MissedMaterialsProcurementFlowTest.php Unestimated material request \rightarrow PO \rightarrow warehouse receipt \rightarrow project inventory ✅ PASSED (1 test)
ProjectClassificationTaggingTest.php 10 seeded classifications & multiple tagging in project creation & update ✅ PASSED (3 tests)
RoleBasedActionTest.php CPM operational permissions & approval restrictions across all roles ✅ PASSED (18 tests)
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

  • Bidding module safely removed; streamlined flow from Project Wizard to Project Progress.
  • 10 standard infrastructure classifications seeded and multiple tagging enabled in Project Wizard.
  • Contractor Project Manager role added with full operational access and approval security guards.
  • Project Wizard roster establishes the relationship between Main Contractor, Subcontractors, and Project.
  • Strictly single (1) Project Manager constraint enforced; multiple Site Operations allocated.
  • Dual-mode Material Requisitions implemented with remaining balance tracking.
  • Estimated Materials option locked when initial estimates are exhausted.
  • Unestimated materials prices automatically added to Project Capitalization Cap.
  • 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 _____________________________ _____________________ ______________
Reference in New Issue View Git Blame Copy Permalink