Platform guide
XYZ — PRD overview
Enterprise AI-driven construction procurement (Product Requirements Document v5). Twenty modules, seven approval gates, and a BOQ-to-contract pipeline with cost, risk, and commercial controls.
Key terms
Definitions from the PRD module specifications.
- BOQ (Bill of Quantities)
- Priced construction line items (description, quantity, unit, rate, amount) ingested from Excel/CSV. Entry point for all procurement data (Module 3).
- WBS (Work Breakdown Structure)
- Scope hierarchy inferred from BOQ descriptions (building → zone → floor → area). Proposed, reviewed, and approved at Gate 0 before applying paths to items. Gate 0 is optional and can be disabled in workflow settings.
- WP (Work Package)
- Procurement unit: classified BOQ lines grouped by WP code from the company WP library (up to 256 codes). Each WP receives budget split, execution strategy, RFQ(s), and contract(s).
- Classification
- Assigning each BOQ line to a WP code via a three-layer cascade: vector similarity (~80% of items), keyword dictionary, then LLM fallback. Low-confidence lines go to a human review queue (Module 4).
- Sub-package
- When execution strategy is SPLIT (or HYBRID), a WP is divided into 2–6 procurable slices — each with its own vendors, RFQ, bid, and contract path.
- RFQ (Request for Quotation)
- Formal tender for a sub-package: scope, BOQ lines, deadline, commercial terms. Lifecycle: draft → published → closed → awarded or cancelled. Publishing may require Gate 4 approval (configurable).
- Bid
- Vendor's priced response to a published RFQ, submitted through the Vendor Portal (Module 10).
- MCDA
- Multi-Criteria Decision Analysis on bids (Module 11). Default weights: price 35%, technical 25%, schedule 15%, track record 15%, risk 10% — configurable per project.
- Award
- Formal recommendation to appoint a winning vendor after MCDA evaluation. Gate 3 is always required and cannot be disabled (financial commitment).
- Gate (0–6)
- Seven approval checkpoints enforced by the Workflow Engine (Module 19): G0 WBS · G1 work packages · G2 execution strategy · G3 award · G4 RFQ publish · G5 contract activation · G6 quantity revision / VO.
- Authority matrix
- Per-role SAR limits and approval types (wbs, package, strategy, rfq, award, contract, quantity revision, cost, etc.) configured in Company Settings → Approval Authority.
- Contract
- Procurement contract auto-created when an award is approved; engineer reviews and activates at Gate 5. Tracks milestones, amendments, and lifecycle status.
- VO (Variation Order)
- Groups multiple approved quantity revisions with a single cost delta and commercial narrative. Submitted for approval at Gate 6; batch-approves linked revisions on approval.
- EVM (Earned Value Management)
- Daily cost snapshots vs revised budget baseline — CPI, SPI, EAC, trend analysis, and anomaly detection (Module 15). Baseline uses revised_budget after quantity changes.
- Responsibility matrix
- Maps implicit BOQ cost assumptions (scaffolding, cranes, permits, accommodation, etc.) to contractor, employer, or shared ownership — used for commercial alignment and VO cost impact (Module 14).
Approval gates
Seven gates orchestrated by the Workflow Engine (Module 19).
| Gate | Approval | Requirement |
|---|---|---|
| G0 | WBS approval | Optional (can be disabled) |
| G1 | Work package approval | Before strategy / RFQ path |
| G2 | Execution strategy approval | Before vendor matching & RFQs |
| G3 | Award approval | Always required |
| G4 | RFQ publish approval | Optional (project config) |
| G5 | Contract activation | Before contract is active |
| G6 | Quantity revision & VO | Post-baseline changes |
20 modules
Numbered modules from PRD v5 (Company Settings through Dashboard & Reports).
Company Settings
Master governance layer (Admin only): profile, users, roles & permissions, approval authority, workflows, approval cycles, WP library, strategy/budget templates, classification governance, vendor taxonomy, notification rules, governance config.
Downstream: All company rules inherit into every project and module below.
Project Settings
Per-project setup before procurement: profile, team, commercial config, WP activation, budget/strategy overrides, workflow overrides, procurement parameters, documents.
Downstream: Project overrides resolve above company defaults; feeds BOQ through cost modules.
BOQ Upload & Smart Parse
Ingest Excel/CSV BOQ (Smart Parse + COPY ingestion). Includes WBS pattern extraction, LLM hierarchy consolidation, proposal review, and Gate 0 WBS approval.
Downstream: Parsed lines → Classification Engine; WBS paths → downstream grouping.
Classification Engine
Assign WP codes via vector → keyword → LLM cascade; review queue for uncertain lines; governance thresholds from Company Settings.
Downstream: Classified items → Work Packages (auto-group by WP code).
Work Packages
Auto-generate packages from classified lines (totals, item counts). Gate 1 package approval before strategy and tendering.
Downstream: Approved packages → Budget Engine and Execution Strategy.
Budget Engine
Deterministic 6-category split per WP (supply, material, equipment, manpower, subcontract, misc) via 4-level template resolution chain.
Downstream: Category distribution → Cost Control variance analysis.
Execution Strategy
Human procurement decision per WP: SINGLE, SPLIT, HYBRID, or IN-HOUSE. Strategy wizard and templates; Gate 2 approval before vendor/RFQ work.
Downstream: Sub-packages → Vendor Matching and RFQ Management.
Vendor Management & Matching
Qualified vendor registry with prequalification and performance scoring. Matching engine: capability 40%, budget fit 35%, performance 25%.
Downstream: Shortlists → RFQ vendor invitations.
RFQ Management
Create RFQs from approved sub-packages, invite vendors, manage deadlines/clarifications, publish (Gate 4 when enabled), close and award.
Downstream: Published RFQs → Vendor Portal; responses → Bid Evaluation.
Vendor Portal
Isolated external interface: view RFQ scope, enter line pricing, upload documents, submit bids (token links or vendor accounts).
Downstream: Bid submissions → Bid Evaluation & Awards (staff side).
Bid Evaluation & Awards
MCDA scoring, comparison matrix, commercial risk assessment, AI award narrative, outlier detection. Gate 3 mandatory award approval.
Downstream: Approved award → Contract Management (auto-create).
Contract Management
Contracts from approved awards; milestones, amendments, 6-state lifecycle. Gate 5 contract activation.
Downstream: Active contracts → Cost Control committed/actual values and Quantity Updates.
Quantity Update
Immutable BOQ baseline with revision history; quantity revisions and Variation Orders at Gate 6.
Downstream: Approved revisions/VOs → revised budget and Cost Control.
Responsibility Matrix
Commercial control: make implicit unit-rate assumptions visible (who pays scaffolding, cranes, permits, etc.).
Downstream: Ownership rules → bid commercial alignment and VO cost impact.
Cost Control & EVM
Daily financial snapshots, CPI/SPI/EAC, trend analysis, anomaly detection against revised budget.
Downstream: Aggregates budget, contract, and quantity data → Dashboard & Reports.
Risk Monitoring
Automated daily scans plus manual risks across cost, schedule, vendor, scope, compliance, and safety categories; mitigation tracking.
Downstream: Risk flags → Notifications and executive Dashboard.
Audit Trail
Immutable log of every create/update/delete with user, timestamp, old/new values — cannot be edited or deleted.
Downstream: All modules that change data.
Notifications
Event-driven in-app inbox and email (approvals, bids, deadlines, risks, SLA) per notification rules in Company Settings.
Downstream: Workflow Engine and module events.
Workflow Engine
Generic state machine for seven entity types: guards, multi-stage approvals, escalation, SLA, audit and notification triggers.
Downstream: Powers every gate (G0–G6) across procurement modules.
Dashboard, Reports & Analytics
Project KPI landing page (pipeline, financials, activity feed) and parameterized PDF/Excel reports.
Downstream: Read-only aggregation across all modules.
Roles
Six default system roles (FR-COM-03) plus external vendors.
- Admin50Company Settings and full platform configuration. Only role with company-level admin access.
- Decision Maker30Executive approver in workflow hierarchy; higher authority for award and financial decisions.
- Procurement Manager20Owns execution strategy (SINGLE/SPLIT/HYBRID/IN-HOUSE) and procurement pipeline decisions.
- Finance Controller15Budget oversight, cost/EVM, quantity revisions, VOs, and commercial financial approvals.
- Procurement Engineer10BOQ ingest, WBS, classification review, packages, RFQs, bids — technical procurement execution.
- Viewer0Read-only access; cannot be designated as a workflow approver.
- Vendor—External Vendor Portal only (Module 10) — not a staff role.
Procurement flow
End-to-end sequence across PRD modules. RFQ publish (G4) happens before award (G3). Workflow Engine, Audit, and Notifications run throughout.
Configure governance, WP library, workflows, authority, templates.
Create project; inherit or override company defaults.
Smart Parse / COPY ingestion; optional WBS pattern extraction.
Review hierarchy; Gate 0 approval (optional gate).
Vector → keyword → LLM cascade; clear review queue.
Auto-group by WP code; Gate 1 approval.
6-category split per WP from template chain.
SINGLE / SPLIT / HYBRID / IN-HOUSE; Gate 2.
Weighted shortlist per sub-package.
Invite vendors; Gate 4 when enabled.
Vendors submit pricing; staff run MCDA evaluation.
Recommend winner; Gate 3 (always required).
Auto-create from award; Gate 5 activation.
Revisions and variation orders; Gate 6.
Cost/EVM, Risk, Responsibility matrix, Dashboard — parallel through project life.