Erlyc
Erlyc
Toggle sidebar
Log in
Log in
Showcase
Report this showcase item

Tell us what is wrong — spam, offensive content, stolen work…
Shared artifacts

EPC Business Materials Management

S

Stormgulf

published 1 hour ago · 1 view

58 features
EPC Business Materials Management — Screen map
Project anatomy

Built with google/gemini-3.7-flash

47
Entities
47
DB tables
38
Screens
8
Modules
47
Models
91
Relations
8
Roles
10
Requirements
8
Journeys
0 comments
Log in to like, rate, or join the conversation. Log in
Original prompt

Create a comprehensive enterprise materials management application for EPC projects covering the full lifecycle from engineering material definition through procurement, supplier execution, logistics, warehousing, construction issue, reconciliation and project closeout. Support multiple companies, projects, contractors, suppliers, disciplines, areas, work packages, warehouses, currencies and languages, with project-specific numbering, workflows, permissions and reference data. Engineering teams should manage material classes, commodity codes, specifications, catalogues, manufacturers, units of measure, tags, equipment references, bulk materials, BOMs/MTOs, engineering quantities, revisions, allowances and required-on-site dates. Allow MTO data to be imported from engineering systems, validated, compared between revisions, consolidated by project/area/discipline/work package and converted into procurement requirements while maintaining full traceability to the engineering source and historical revisions. Provide Material Requisition workflows where engineers select materials and quantities, specify technical requirements, approved manufacturers, required dates, inspection requirements, documentation requirements and attachments, then route requisitions through configurable approvals. Support revisions, holds, cancellations and item-level procurement status. Procurement teams should create inquiry packages and RFQs from approved requisitions, select bidders, issue packages, manage supplier acknowledgements and clarifications, receive quotation revisions, compare commercial offers, record deviations, perform technical and commercial bid evaluations, manage negotiations and approval of award recommendations, and convert awarded lines into purchase orders, subcontracts or framework call-offs. Manage purchase orders with revisions, line items, quantities, prices, currencies, taxes, Incoterms, payment terms, delivery schedules, destinations, warranties, approved vendors/manufacturers, attachments, correspondence, variation orders and approval thresholds. Keep complete traceability between engineering requirements, requisitions, RFQs, bids and purchase-order lines. Provide a secure supplier portal where suppliers can access only their own RFQs and orders, submit quotations, acknowledge orders, answer clarifications, update manufacturing progress, provide inspection notifications, packing and shipment information, invoices and required vendor documents. Include supplier management with qualification status, approved vendor lists, commodity capabilities, project approvals, contacts, quality findings, delivery history and supplier performance evaluations. Provide procurement expediting using planned, forecast and actual milestones for document submission, engineering approval, raw materials, fabrication, testing, inspection, packing and readiness for shipment. Expeditors should record progress percentages, forecast dates, comments, supplier commitments, meeting notes, risks and recovery actions. Highlight overdue milestones and forecast delivery risks through dashboards and exception reports. Include vendor document control linked to suppliers, requisitions, purchase orders, equipment and material items. Manage document requirements, registers, document numbers, revisions, submission schedules, review cycles, transmittals, comments, approval codes and overdue documents. Allow documents to be stored directly or linked to an external document management system. Support quality surveillance and inspection through inspection requirements, assignments, inspection notifications, inspection/test records, certificates, non-conformities, punch items and release-for-shipment decisions, with traceability to suppliers, PO lines and tagged equipment. Logistics teams should manage shipping releases, consignments, packages, crates, containers and transport legs from supplier through consolidation, ports, customs and project destinations. Capture dimensions, weights, hazardous-material details, freight forwarders, carriers, transport mode, Incoterms, ETD/ETA, actual dates, customs information and shipping documents. Support partial deliveries, consolidated shipments and shipments containing materials from several purchase orders. Provide packing-list management down to package and material level so users can identify exactly what has been packed, shipped, is in transit, customs-cleared, received, damaged or missing. Site material management should cover warehouses, laydown yards, storage zones and bins. Support expected receipts, goods receipt, quantity and condition checks, over/short/damaged reports, quarantine and quality holds, labeling, stock placement, transfers, cycle counts, physical inventory and preservation requirements. Maintain a complete inventory ledger and history of every material movement. Construction teams should create material requests and reservations against work packages, systems, areas or construction activities, check availability, obtain approvals where needed, pick and issue materials, and process partial issues, returns, transfers, damaged materials and consumables. Provide mobile-friendly workflows for warehouse and field users with barcode/QR scanning, photos and signatures. Support traceability for tagged equipment and controlled bulk materials using serial numbers, heat numbers, batch numbers, certificates and other identifiers when applicable. Provide continuous shortage and availability analysis comparing engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations and issued quantities. Show shortages, excesses and inconsistencies by project, discipline, area, system, work package and required date. Allow recovery actions such as additional procurement, expediting, stock transfer, substitution or engineering resolution. Manage engineering changes without losing historical information. When quantities, specifications or MTO revisions change, identify downstream impacts on requisitions, orders, manufacturing, shipments and site stock. Support controlled material substitution, technical deviations, cancellations and surplus decisions. Support construction completion and commissioning with material availability by system and turnover package, outstanding-material lists, commissioning consumables, temporary materials, special tools, operational spares and capital spares. At project closeout, reconcile engineering quantities, purchased quantities, shipped quantities, received quantities, issued quantities, returns, damaged quantities and remaining inventory. Manage surplus disposition through reuse on another project, return to supplier, transfer to client, sale or disposal and produce final material reconciliation reports. Provide role-based access for engineering, project management, procurement, buyers, expeditors, quality, logistics, warehouse, construction, subcontractors, suppliers, finance, client representatives and administrators. Permissions should be restrictable by project, organization, discipline, location, warehouse and supplier. Include approval authority limits, delegation, substitute approvers and configurable escalation rules. Maintain complete audit history for revisions, approvals, quantity changes, status changes and critical data modifications. Provide comments, assignments, reminders and notifications for approvals, supplier delays, overdue documents, inspections, shipments, expected receipts, shortages, preservation tasks and other exceptions. Create operational and management dashboards covering engineering readiness, requisitions, RFQs, procurement cycle time, commitments, supplier performance, expediting, manufacturing progress, vendor documentation, inspections, logistics, inventory, shortages, material availability, construction issues and surplus. Users should be able to drill from high-level KPIs to project, order and individual material-line details. Provide powerful global search, advanced filters, configurable columns, saved views, grouping, pivot-style analysis and reporting. Support Excel/CSV import with mapping, validation, preview and detailed error handling, and export reports and filtered datasets to Excel, CSV and PDF. Provide integration interfaces for engineering/design systems, ERP and finance platforms, project scheduling, document management, supplier systems and logistics services. Centrally govern common master data such as commodities, material classes, manufacturers, units, currencies, Incoterms, suppliers and quality codes while supporting project-specific extensions. Design the application for very large EPC datasets while keeping navigation clear and fast. The core principle must be end-to-end material traceability: from an engineering MTO item users must be able to follow the complete chain through requisition, RFQ, bid evaluation, purchase order, supplier progress, documents, inspection, shipment, packing list, receipt, warehouse location, reservation, construction issue and final reconciliation, and navigate the same chain backwards from any physical material item.

Discovery boards
Project Brief
Product Intention
What I think you want to build
interpretation
critical

The user needs end-to-end material traceability across the entire EPC project lifecycle, from engineering definition through procurement, logistics, warehousing, construction issue, and closeout.

The product idea explicitly states this as the core principle, repeated multiple times throughout the description. User accepted without comment.

interpretation

The user needs a multi-tenant, multi-project, multi-organization platform where different companies (EPC contractor, subcontractors, suppliers, client) interact through role-based access and project-specific configurations.

User confirmed explicitly: 'Confirmed: multi-tenant, multi-project, multi-organization platform with role-based access and project-specific configurations.'

interpretation

The product is a replacement for a fragmented ecosystem of spreadsheets, legacy ERP modules, and disconnected point solutions currently used to manage materials across EPC projects.

User accepted without comment.

interpretation

This is a commercial SaaS product to sell to EPC contractors, not an internal tool for a single company.

User confirmed: 'The multi-company, multi-tenant, supplier portal, and configurable workflow requirements strongly suggest a commercial SaaS product.'

Target Users
Likely target users
interpretation

Engineering discipline leads and material coordinators who define material classes, commodity codes, specifications, and BOMs/MTOs, and need to track engineering revisions and convert requirements into procurement requests.

User accepted without comment.

interpretation

Procurement professionals (buyers, expeditors, supplier quality engineers) who manage RFQs, bid evaluations, purchase orders, supplier progress tracking, and vendor documentation.

User accepted without comment.

interpretation

Logistics and warehouse personnel who manage shipments, packing lists, goods receipt, inventory, storage locations, and material movements across sites and laydown yards.

User accepted without comment.

interpretation

Construction and commissioning teams who request materials against work packages, check availability, issue materials to the field, and track material availability by system and turnover package.

User accepted without comment.

interpretation

External suppliers who need a secure portal to access their RFQs and orders, submit quotations, acknowledge orders, update manufacturing progress, and submit documentation.

User accepted without comment.

interpretation

Project management and client representatives who need dashboards, KPIs, drill-downs, and exception reports to monitor material status, shortages, and project health.

User accepted without comment.

Problems
Problems worth solving
interpretation
critical

Stated problem: Material data is fragmented across engineering, procurement, logistics, and construction systems, making it impossible to trace a material item from engineering definition through final reconciliation.

The prompt explicitly states the core principle. User accepted without comment.

interpretation

Stated problem: Engineering changes ripple through the supply chain without clear visibility into downstream impacts on requisitions, orders, manufacturing, shipments, and site stock.

The prompt explicitly describes engineering change management. User accepted without comment.

interpretation

Stated problem: Shortages and excesses are discovered too late because there is no continuous comparison of engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations, and issued quantities.

The prompt explicitly describes shortage analysis. User accepted without comment.

interpretation

Underlying job-to-be-done: Project stakeholders need to answer 'where is my material and when will it arrive?' at any point in the project lifecycle without manually chasing data across multiple systems and spreadsheets.

User confirmed: 'This is the core JTBD and should anchor all UX and data model decisions.'

interpretation

Implied problem not stated: Supplier performance and reliability are difficult to assess systematically because delivery history, quality findings, and performance evaluations are scattered across projects and systems.

User accepted without comment.

interpretation

Implied problem not stated: Audit and compliance requirements for regulated industries (oil & gas, nuclear, pharmaceuticals) demand immutable records of material provenance, approvals, and quality documentation that current systems cannot provide.

User accepted with comment: 'Audit history and immutable records are table-stakes for regulated EPC industries. The audit_logs and versioning feature tags already cover this.'

Outcomes
Desired outcomes
interpretation
critical

Users can trace any material item from engineering MTO through requisition, RFQ, bid evaluation, purchase order, supplier progress, documents, inspection, shipment, packing list, receipt, warehouse location, reservation, construction issue, and final reconciliation — in both directions.

This is the explicitly stated core principle of the product. User accepted without comment.

interpretation

Shortages and excesses are identified continuously and automatically, with recovery actions (additional procurement, expediting, stock transfer, substitution, engineering resolution) initiated before they impact construction schedules.

User accepted without comment.

interpretation

Engineering changes are managed with full visibility into downstream impacts, allowing stakeholders to make informed decisions about substitutions, deviations, cancellations, and surplus before they cause delays or excess inventory.

User accepted without comment.

interpretation

Suppliers have a single portal to interact with the EPC contractor, reducing email chains, phone calls, and manual status updates while providing real-time visibility into order status, documentation requirements, and payment milestones.

User accepted without comment.

interpretation

Project closeout reconciliation is automated, with engineering quantities, purchased quantities, shipped quantities, received quantities, issued quantities, returns, damaged quantities, and remaining inventory reconciled into final reports without manual spreadsheet work.

User accepted without comment.

Usage Context
Usage context
interpretation

Users access the system primarily from desktop workstations in office environments for engineering, procurement, and management functions, while warehouse and field personnel use mobile devices with barcode/QR scanning, photos, and signatures.

User accepted with comment: 'Desktop-first for office roles, mobile-optimized for warehouse/field. Offline support should be a later-phase enhancement, not a v1 blocker.'

interpretation

The system is used across multiple time zones and locations, with projects potentially spanning multiple countries, requiring timezone-aware timestamps and multi-currency support.

User accepted without comment.

interpretation

The system is used in environments with intermittent connectivity (construction sites, warehouses, supplier facilities), requiring graceful degradation when connectivity is lost. Full offline-capable mobile workflows are a later-phase enhancement.

User accepted with comment: 'Graceful degradation first; full offline-capable mobile workflows are a later-phase enhancement.'

Scope Boundaries
Scope boundaries
interpretation

This is NOT a general-purpose ERP system. It focuses specifically on materials management and traceability for EPC projects, not financial accounting, HR, payroll, or other ERP functions.

User accepted without comment.

interpretation

This is NOT a document management system. While it manages vendor documents and links to external DMS, it does not replace a full-featured document management platform with version control, collaboration, and archival capabilities.

User accepted without comment.

interpretation

This is NOT a project scheduling or planning tool. While it integrates with project scheduling systems and tracks material availability by work package, it does not replace Primavera P6 or similar scheduling software.

User accepted without comment.

interpretation

This is NOT a 3D model viewer or engineering design tool. While it imports MTO data from engineering systems, it does not create or edit engineering designs.

User accepted without comment.

Risks
Blind spots and risks
risk

Technical risk: The data model must support very large EPC datasets (potentially millions of material items, thousands of purchase orders, hundreds of thousands of documents) while maintaining fast navigation and traceability queries across the entire chain. Design baseline is the 'Large' tier (100k-1M material items, 500-2000 concurrent users), with architecture that scales to 'Very large' (>1M items, >2000 users) via partitioning, read replicas, and async materialized views for traceability queries.

User accepted with comment: 'Design for the Large tier as the baseline, with architecture that scales to Very large via partitioning, read replicas, and async materialized views for traceability queries.'

risk

User adoption risk: The system spans many roles (engineering, procurement, logistics, warehouse, construction, suppliers) with different workflows and needs. Getting all stakeholders to adopt a single system may face resistance, especially from suppliers who may already use their own systems.

User accepted with comment: 'Real risk. Mitigate by making the supplier portal low-friction (email-based invites, minimal onboarding) and providing clear value to suppliers.'

risk

Scope/feasibility risk: The scope is extremely broad, covering the entire EPC materials lifecycle. Building all capabilities at once risks a shallow implementation where no single workflow is deep enough to be useful.

User accepted with comment: 'Real risk. Mitigate with the phased depth-first roadmap: engineering-to-procurement traceability first, then logistics/warehousing, then construction/closeout.'

risk

Technical risk: Integration with external systems (engineering tools, ERP, scheduling, DMS, supplier systems, logistics services) is complex and may require custom connectors for each customer's specific toolchain, increasing implementation cost and time.

User accepted with comment: 'Mitigate with a standards-first integration layer (Excel/CSV import, REST API, webhooks) and named connectors for dominant systems (Aveva, Hexagon/SmartPlant, SAP, Oracle) built as adapters.'

risk

User adoption risk: Warehouse and field personnel may resist using mobile devices for material transactions if the mobile UX is not significantly faster and easier than paper-based processes or simple spreadsheets.

User accepted with comment: 'Mitigate with barcode/QR scanning, minimal taps for common transactions, and offline-tolerant mobile UX.'

risk

Risk: The integrated supplier portal (same backend, separate UX) creates a security boundary challenge. External supplier users must be strictly isolated to their own RFQs and orders, requiring robust row-level security and careful API authorization to prevent data leakage between tenants and suppliers.

The user's confirmation of the integrated supplier portal (dec_002) opens up a security risk that must be addressed. Row-level security and API authorization for external users are critical.

High-Impact Decisions
High-impact decisions
decision
critical

Decision: The product will be built as a multi-tenant SaaS platform with per-tenant isolation (schema or row-level partitioning), with the option for dedicated infrastructure for very large customers.

User confirmed: 'Multi-tenant SaaS is the right default for a commercial product targeting multiple EPC contractors. Per-tenant isolation via schema or row-level partitioning, with the option for dedicated infrastructure for very large customers.'

decision

Decision: The supplier portal will be an integrated part of the main application with role-based access for external users, but with a separate UX surface for suppliers. This keeps a single source of truth and simplifies traceability while giving suppliers a focused, simplified experience.

User confirmed: 'Integrated backend with role-based access, separate UX surface for suppliers.'

decision

Decision: The product will use a transaction-centric data model with documents as first-class entities linked to transactions. Material movements and status changes are the primary artifacts; documents attach to them and carry their own lifecycle (revisions, review cycles, approval codes).

User confirmed: 'Transaction-centric data model with documents as first-class entities linked to transactions.'

decision

Decision: The product will use a hybrid material master: global core (commodity codes, classes, manufacturers, UoMs) with project-specific extensions and optional synchronization. This matches the prompt's 'centrally governed master data with project-specific extensions.'

User confirmed: 'Hybrid: global core material master with project-specific extensions and optional synchronization.'

decision
critical

Decision: The product will use a phased depth-first roadmap. Start with engineering-to-procurement traceability (MTO import, requisitions, RFQs, POs, supplier progress) as the core value chain, then expand to logistics, warehousing, construction, and closeout in subsequent phases.

User confirmed: 'Phased depth-first is the correct approach. Start with engineering-to-procurement traceability.'

decision

Decision: The integration strategy will be standards-first (Excel/CSV import with mapping and validation, REST API, webhooks) with named connectors for the dominant EPC toolchain (Aveva, Hexagon/SmartPlant, SAP, Oracle) built as adapters over the REST/import layer, not hard dependencies.

User confirmed via blocker answer: 'Build a standards-first integration layer as the primary interface. Provide named connectors for the dominant EPC toolchain: Aveva, Hexagon, SAP, and Oracle. These connectors should be adapters over the REST/import layer, not hard dependencies.'

tradeoff

Tradeoff: The phased depth-first roadmap means logistics, warehousing, construction, and closeout workflows will not be available in the initial release. Early adopters who need full lifecycle coverage may be disappointed, but this approach ensures the core engineering-to-procurement chain is deep and reliable before expanding.

The user's acceptance of the phased depth-first roadmap (dec_005) creates a tradeoff between early breadth and core depth. This tradeoff should be explicitly acknowledged.

decision

Decision: Should the product support project-specific numbering schemes (e.g., requisition numbers, PO numbers) as a first-class configuration, or enforce a global numbering scheme with project prefixes?

The prompt mentions project-specific numbering, and the hybrid material master decision (dec_004) implies project-specific configurations. This decision affects data model and UI complexity.

decision

Decision: Should the product support multi-currency with per-project base currency and automatic conversion, or require manual currency conversion for cross-currency transactions?

The prompt mentions multiple currencies, and the multi-tenant SaaS decision (dec_001) implies global operations. This decision affects data model and reporting complexity.

Needs & Data
Core Domain Objects
What entities exist in the product world, with key attributes and relationships.
interpretation
critical

Material: The central entity representing any physical item managed by the system. Key attributes: material_id, material_class_id, commodity_code, specification_id, description, uom_id, material_type (tagged/bulk), manufacturer_id, model_number, status, created_at, updated_at, deleted_at. Relationships: belongs to MaterialClass, has many MaterialSpecifications, has many MaterialTags (for tagged items), has many InventoryItems, has many RequisitionLines, has many POLines.

Material is the anchor for all traceability chains. It must support both tagged equipment and bulk materials (claim_041).

interpretation

Project: Represents an EPC project. Key attributes: project_id, project_code, project_name, client_id, contractor_id, base_currency, status, start_date, end_date, created_at, updated_at. Relationships: has many Areas, has many WorkPackages, has many Disciplines, has many Warehouses, has many Requisitions, has many PurchaseOrders, has many Suppliers (through project approvals).

Project is the top-level organizational unit. Claim_048 confirms hierarchical project structures.

interpretation

MTORevision: Represents a version of engineering material take-off data. Key attributes: mto_revision_id, project_id, revision_number, revision_date, source_system, import_batch_id, status (draft/validated/approved/superseded), created_at, updated_at. Relationships: belongs to Project, has many MTOItems, has many Requisitions (created from it).

MTO revisions are the source of engineering requirements and must be versioned for traceability (claim_043).

interpretation

MTOItem: A single line in an MTO revision. Key attributes: mto_item_id, mto_revision_id, material_id, quantity, uom_id, discipline_id, area_id, work_package_id, system_id, required_on_site_date, allowance_percentage, status, created_at, updated_at. Relationships: belongs to MTORevision, belongs to Material, has many RequisitionLines, has many ShortageAnalysisRecords.

MTO items are the granular engineering requirements that drive procurement. They must link to requisitions for traceability.

interpretation

Requisition: A material requisition created from MTO items. Key attributes: requisition_id, requisition_number, project_id, revision_number, status (draft/in_review/approved/rejected/on_hold/cancelled), required_date, technical_requirements, inspection_requirements, documentation_requirements, created_by, approved_by, created_at, updated_at, deleted_at. Relationships: belongs to Project, has many RequisitionLines, has many RFQs, has many Attachments.

Requisitions are the bridge between engineering and procurement. They must support revisions, holds, and cancellations.

interpretation

PurchaseOrder: A purchase order or subcontract. Key attributes: po_id, po_number, project_id, supplier_id, currency, incoterms, payment_terms, status (draft/issued/acknowledged/in_progress/partially_received/completed/cancelled), total_value, created_at, updated_at, deleted_at. Relationships: belongs to Project, belongs to Supplier, has many POLines, has many Shipments, has many Invoices, has many VendorDocuments.

Purchase orders are the contractual commitment to suppliers. They must link back to requisitions and RFQs for traceability.

interpretation

InventoryItem: A physical material item or quantity in a warehouse. Key attributes: inventory_item_id, material_id, warehouse_id, storage_location_id, quantity, uom_id, serial_number, heat_number, batch_number, status (available/reserved/quarantined/damaged/issued), received_date, created_at, updated_at, deleted_at. Relationships: belongs to Material, belongs to Warehouse, has many MaterialMovements, has many Reservations.

Inventory items are the physical manifestation of materials at site. They must support traceability identifiers (serial, heat, batch).

interpretation

MaterialMovement: An immutable record of a material movement. Key attributes: movement_id, inventory_item_id, movement_type (receipt/transfer/issue/return/adjustment), from_location_id, to_location_id, quantity, uom_id, actor_id, timestamp, reference_document_type, reference_document_id, created_at. Relationships: belongs to InventoryItem, belongs to Warehouse (from/to), belongs to User (actor).

Material movements form the inventory ledger. Claim_042 requires immutable movement records.

interpretation

Supplier: A supplier or manufacturer. Key attributes: supplier_id, supplier_code, supplier_name, qualification_status, contact_info, created_at, updated_at, deleted_at. Relationships: has many SupplierCommodityCapabilities, has many ProjectApprovals, has many PurchaseOrders, has many QualityFindings, has many PerformanceEvaluations.

Suppliers are key external entities. Claim_046 requires qualification status, AVL, and performance tracking.

interpretation

VendorDocument: A document submitted by a supplier or generated by the system. Key attributes: document_id, document_number, document_type, supplier_id, po_id, revision_number, status (submitted/in_review/approved/rejected/overdue), submission_date, review_due_date, approval_code, file_reference, created_at, updated_at, deleted_at. Relationships: belongs to Supplier, belongs to PurchaseOrder, has many Transmittals, has many ReviewComments.

Vendor documents are first-class entities with their own lifecycle (claim_049).

interpretation

Shipment: A consignment of materials from supplier to site. Key attributes: shipment_id, shipment_number, supplier_id, po_id, freight_forwarder_id, transport_mode, incoterms, etd, eta, actual_departure_date, actual_arrival_date, status (planned/in_transit/customs_cleared/received), created_at, updated_at, deleted_at. Relationships: belongs to Supplier, belongs to PurchaseOrder, has many Packages, has many TransportLegs, has many ShippingDocuments.

Shipments are the logistics link between supplier and site. They must support partial deliveries and consolidated shipments.

interpretation

Reservation: A reservation of inventory for a construction work package. Key attributes: reservation_id, inventory_item_id, work_package_id, quantity, uom_id, status (reserved/issued/returned/cancelled), reserved_by, reserved_date, issued_date, created_at, updated_at, deleted_at. Relationships: belongs to InventoryItem, belongs to WorkPackage, has many IssueTransactions.

Reservations link inventory to construction needs. They are essential for shortage analysis and material availability.

Solution Shape
Recommended Product Concept
A concise product thesis the user can endorse or reject.
recommendation
critical

A traceability-first materials management platform for EPC projects: every screen, workflow, and data model decision serves the single goal of letting any stakeholder answer 'where is my material and when will it arrive?' by navigating a complete, bidirectional material lineage graph from engineering definition through procurement, logistics, warehousing, construction issue, and closeout.

Synthesizes the confirmed core principle (claim_001), the confirmed core JTBD (claim_014), and the confirmed transaction-centric data model (dec_003). This thesis rejects a module-based approach that would recreate the silos the product replaces.

decision
critical

Decision: Should the product be organized around a traceability-first navigation model (material lineage graph as the central surface) or a module-based navigation model (separate engineering, procurement, logistics, and construction modules)?

This is the single most consequential solution-shape decision. A traceability-first model makes the lineage graph the primary navigation surface and treats modules as secondary views. A module-based model optimizes for departmental workflows but risks recreating the silos the product replaces.

Main User Journey
Recommended end-to-end user flow.
recommendation

Main journey: (1) User lands on a role-aware workspace showing work queues and exceptions relevant to their role. (2) User searches or scans a material, tag, requisition, PO, or shipment to locate the item of interest. (3) User opens the material's traceability view, showing the complete lineage graph from engineering MTO through current status. (4) User identifies the current stage and any blockers (overdue milestone, shortage, quality hold, shipment delay). (5) User drills into the specific transaction or document causing the blocker. (6) User takes action (approve, expedite, transfer, substitute, issue) directly from the context. (7) User verifies the action propagated correctly through the lineage graph. (8) User saves or shares a filtered view of the material's status for reporting or escalation.

This journey is material-centric and bidirectional, reflecting the confirmed core JTBD (claim_014) and the confirmed outcome of bidirectional traceability (claim_017). It is not a linear wizard; users can enter at any step and navigate in either direction.

decision

Decision: What should be the primary entry point for the main journey? (A) Material-centric entry: search or scan any material, then navigate the chain. (B) Project-centric entry: select project, then drill into areas, work packages, materials. (C) Role-centric entry: land on role-specific dashboard, then navigate to work queues.

The entry point determines the first screen users see and the mental model they form. A material-centric entry reinforces traceability; a role-centric entry optimizes for daily task completion. The confirmed core JTBD (claim_014) suggests material-centric, but role-based work queues are also critical for adoption.

Capability Groups
Feature clusters organized by user goal.
recommendation

Capability group 'Define': Engineering material definition — material classes, commodity codes, specifications, catalogues, manufacturers, units of measure, tags, equipment references, bulk materials, BOMs/MTOs, engineering quantities, revisions, allowances, required-on-site dates, MTO import with validation and comparison, consolidation by project/area/discipline/work package, and conversion to procurement requirements with full traceability to engineering source.

This group captures the engineering-side capabilities from the prompt, organized around the user goal of defining what materials are needed and where. It is the starting point of the traceability chain.

recommendation

Capability group 'Procure': Procurement workflow — material requisitions with configurable approvals, inquiry packages and RFQs, bidder selection, supplier acknowledgements and clarifications, quotation revisions, commercial offer comparison, deviation recording, technical and commercial bid evaluations, negotiations, award recommendations, purchase orders with revisions and variation orders, subcontracts, framework call-offs, and approval thresholds.

This group captures the procurement-side capabilities from the prompt, organized around the user goal of acquiring materials at the right price and quality. It is the second stage of the traceability chain.

recommendation

Capability group 'Supplier Portal': Secure supplier-facing surface — access to own RFQs and orders, quotation submission, order acknowledgement, clarification responses, manufacturing progress updates, inspection notifications, packing and shipment information, invoice submission, and vendor document submission. Strict row-level isolation to own data only.

Confirmed by dec_002 (integrated backend, separate UX) and claim_020 (single portal outcome). This is a first-class capability group with its own UX surface, not a sub-feature of procurement.

recommendation

Capability group 'Track': Supplier management, expediting, vendor document control, quality surveillance and inspection — qualification status, approved vendor lists, commodity capabilities, project approvals, contacts, quality findings, delivery history, performance evaluations, planned/forecast/actual milestones, progress percentages, forecast dates, supplier commitments, meeting notes, risks, recovery actions, overdue milestone highlighting, document requirements and registers, submission schedules, review cycles, transmittals, comments, approval codes, inspection requirements, assignments, notifications, test records, certificates, non-conformities, punch items, and release-for-shipment decisions.

This group captures the supplier-facing and quality-facing capabilities from the prompt, organized around the user goal of tracking supplier progress and ensuring quality before materials ship.

recommendation

Capability group 'Store': Logistics and warehousing — shipping releases, consignments, packages, crates, containers, transport legs, consolidation, ports, customs, project destinations, dimensions, weights, hazardous-material details, freight forwarders, carriers, transport mode, Incoterms, ETD/ETA, actual dates, customs information, shipping documents, partial deliveries, consolidated shipments, packing-list management down to package and material level, warehouses, laydown yards, storage zones, bins, expected receipts, goods receipt, quantity and condition checks, over/short/damaged reports, quarantine and quality holds, labeling, stock placement, transfers, cycle counts, physical inventory, preservation requirements, and complete inventory ledger.

This group captures the logistics and warehousing capabilities from the prompt, organized around the user goal of knowing where materials are physically located and in what condition.

recommendation

Capability group 'Issue': Construction material management — material requests and reservations against work packages, systems, areas, construction activities, availability checks, approvals, pick and issue, partial issues, returns, transfers, damaged materials, consumables, mobile-friendly workflows with barcode/QR scanning, photos, signatures, traceability for tagged equipment and controlled bulk materials using serial numbers, heat numbers, batch numbers, certificates, and construction completion and commissioning support with material availability by system and turnover package, outstanding-material lists, commissioning consumables, temporary materials, special tools, operational spares, and capital spares.

This group captures the construction-side capabilities from the prompt, organized around the user goal of getting the right materials to the right work package at the right time.

recommendation

Capability group 'Reconcile': Shortage analysis, engineering change management, and project closeout — continuous comparison of engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations, and issued quantities, shortage/excess/inconsistency identification by project, discipline, area, system, work package, and required date, recovery actions (additional procurement, expediting, stock transfer, substitution, engineering resolution), engineering change impact analysis on requisitions, orders, manufacturing, shipments, and site stock, controlled material substitution, technical deviations, cancellations, surplus decisions, closeout reconciliation of all quantity types, surplus disposition (reuse, return, transfer, sale, disposal), and final material reconciliation reports.

This group captures the analytical and closeout capabilities from the prompt, organized around the user goal of ensuring nothing is short, nothing is excess, and everything reconciles at the end.

recommendation
critical

Capability group 'Traceability View': Cross-cutting bidirectional traceability — a dedicated navigation surface accessible from any material, document, or transaction that shows the complete lineage graph from engineering MTO through requisition, RFQ, bid evaluation, purchase order, supplier progress, documents, inspection, shipment, packing list, receipt, warehouse location, reservation, construction issue, and final reconciliation, navigable in both directions with drill-down to individual transaction details.

Claim_017 explicitly requires bidirectional traceability. This must be a first-class navigation surface, not a dashboard widget or report. It is the single most important capability for the product concept.

recommendation

Capability group 'Govern & Integrate': Platform governance and integration — role-based access control with permissions restrictable by project, organization, discipline, location, warehouse, and supplier, approval authority limits, delegation, substitute approvers, configurable escalation rules, complete audit history for revisions, approvals, quantity changes, status changes, and critical data modifications, comments, assignments, reminders, notifications, global search, advanced filters, configurable columns, saved views, grouping, pivot-style analysis, reporting, Excel/CSV import with mapping and validation, export to Excel/CSV/PDF, REST API, webhooks, third-party connectors, centrally governed master data (commodities, material classes, manufacturers, units, currencies, Incoterms, suppliers, quality codes) with project-specific extensions, and integration interfaces for engineering/design systems, ERP, scheduling, DMS, supplier systems, and logistics services.

This group captures the platform-level capabilities from the prompt, organized around the user goal of governing access, data, and integrations across the entire system.

recommendation

Capability group 'Monitor': Dashboards and KPIs — operational and management dashboards covering engineering readiness, requisitions, RFQs, procurement cycle time, commitments, supplier performance, expediting, manufacturing progress, vendor documentation, inspections, logistics, inventory, shortages, material availability, construction issues, and surplus, with drill-down from high-level KPIs to project, order, and individual material-line details, scheduled reports, and exception reports.

This group captures the dashboard and reporting capabilities from the prompt, organized around the user goal of monitoring project health and identifying exceptions before they become problems.

Optional Phase-1 Cut
Recommended phase-1 cut, only when the user wants a staged rollout.
recommendation
critical

Phase-1 cut: Engineering-to-procurement traceability chain — MTO import with validation and comparison, material master (hybrid global core with project extensions), requisitions with configurable approvals, RFQs and bid evaluations, purchase orders with revisions, supplier portal (RFQ access, quotation submission, order acknowledgement, progress updates), expediting milestones, vendor document control, and the traceability view covering the engineering-to-PO chain. This phase delivers the core value proposition: trace any material from engineering requirement through purchase order with full lineage.

Directly reflects dec_005 (phased depth-first) and claim_038 (start with engineering-to-procurement traceability). This phase is deep enough to be useful on its own while establishing the traceability foundation for later phases.

Later Extensions
Features valuable after MVP.
recommendation

Later extension: Full offline-capable mobile workflows for warehouse and field users. Graceful degradation is the baseline; full offline with local data sync is a later enhancement.

Claim_024 confirms graceful degradation first, full offline later. This is a genuine later extension, not an MVP trim.

recommendation

Later extension: Advanced analytics and predictive insights — supplier performance scoring, delivery risk prediction, shortage forecasting, and procurement cycle time optimization using historical data.

The prompt focuses on descriptive dashboards and exception reports. Predictive analytics is a natural later extension once sufficient historical data accumulates.

recommendation

Later extension: Direct integrations with named EPC toolchain systems (Aveva, Hexagon/SmartPlant, SAP, Oracle) as pre-built connectors, beyond the standards-first REST/import layer.

Dec_006 confirms standards-first integration with named connectors as adapters. Pre-built connectors for specific systems are a later extension once the standards layer is stable.

Explicitly Excluded Scope
Things to not build now.
constraint

Excluded: General-purpose ERP functionality — financial accounting, HR, payroll, and other ERP functions are explicitly out of scope.

Claim_025 confirms this is NOT a general-purpose ERP system. This boundary is critical to prevent scope creep.

constraint

Excluded: Full-featured document management system — while the product manages vendor documents and links to external DMS, it does not replace a full DMS with version control, collaboration, and archival capabilities.

Claim_026 confirms this is NOT a document management system. Vendor document control is in scope; general DMS is not.

constraint

Excluded: Project scheduling and planning — while the product integrates with project scheduling systems and tracks material availability by work package, it does not replace Primavera P6 or similar scheduling software.

Claim_027 confirms this is NOT a project scheduling tool.

constraint

Excluded: 3D model viewer and engineering design tool — while the product imports MTO data from engineering systems, it does not create or edit engineering designs.

Claim_028 confirms this is NOT a 3D model viewer or engineering design tool.

Trade-offs and Tensions
Conflicts requiring resolution.
tradeoff

Tradeoff: Traceability-first navigation vs. role-optimized workflows. A traceability-first model makes the lineage graph the central surface, which is powerful for answering 'where is my material' but may slow down high-volume transactional work (buyers creating POs, warehouse staff receiving goods) that benefits from role-specific work queues and minimal navigation.

This tension is inherent in the product concept. The recommended position is a hybrid: role-aware workspaces as the landing surface with a prominent, always-available traceability view accessible from any entity. This preserves both daily task efficiency and the core traceability value proposition.

tradeoff

Tradeoff: Depth vs. breadth in phase-1. The confirmed phased depth-first roadmap (dec_005) means logistics, warehousing, construction, and closeout workflows are not available in phase-1. Early adopters who need full lifecycle coverage may be disappointed, but this approach ensures the core engineering-to-procurement chain is deep and reliable before expanding.

This tradeoff was already surfaced in the project brief (claim_031) and confirmed by the user. It is restated here because it directly shapes the MVP recommendation.

tradeoff

Tradeoff: Flexibility vs. consistency in project-specific configurations. The prompt requires project-specific numbering, workflows, permissions, and reference data. Too much flexibility makes the system hard to learn and maintain; too little makes it unusable for diverse EPC projects. The recommended position is a hybrid: global core with project-specific extensions (dec_004), with sensible defaults that projects can override only where necessary.

This tension is inherent in the confirmed hybrid material master decision (dec_004) and the prompt's requirement for project-specific configurations. The recommended position balances flexibility with consistency.

tradeoff

Tradeoff: Real-time traceability vs. performance at very large scale. Bidirectional traceability queries across millions of material items and hundreds of thousands of transactions may be expensive. The recommended position is async materialized views for traceability queries with eventual consistency (seconds to minutes), while transactional operations remain strongly consistent.

Claim_029 confirms the technical risk of very large datasets with fast traceability queries. This tradeoff directly addresses that risk with a concrete architectural position.

Design Principles
UX/product principles inferred.
recommendation
critical

Design principle: Traceability is the primary navigation metaphor. Every screen should make it possible to answer 'where is this material and what is its history?' in one click or scan.

Derived from claim_001 (core principle), claim_014 (core JTBD), and claim_017 (bidirectional traceability). This principle should guide all UX decisions.

recommendation

Design principle: Role-aware, not role-siloed. Users should land on a workspace tailored to their role (work queues, exceptions, KPIs) but should never be blocked from navigating the full traceability chain when needed.

Derived from claim_005-010 (diverse roles) and the tradeoff between traceability-first and role-optimized workflows. This principle resolves that tension.

recommendation

Design principle: Exception-first. The system should surface shortages, overdue milestones, quality holds, and shipment delays proactively, not require users to hunt for them.

Derived from claim_013 (shortages discovered too late) and the prompt's emphasis on exception reports and dashboards. This principle guides notification and dashboard design.

recommendation

Design principle: Mobile-first for field, desktop-first for office. Warehouse and field workflows must be optimized for mobile with barcode/QR scanning, minimal taps, photos, and signatures. Office workflows (engineering, procurement, management) must be optimized for desktop with dense data views, advanced filters, and pivot-style analysis.

Derived from claim_022 (desktop for office, mobile for warehouse/field) and claim_033 (warehouse resistance risk mitigated by barcode/QR scanning, minimal taps).

recommendation

Design principle: Immutable history, mutable present. All material movements, status changes, approvals, and critical data modifications must be recorded as immutable audit events. Users can change the current state but never rewrite history.

Derived from claim_016 (audit history is table-stakes) and claim_042 (immutable material movement transactions). This principle guides data model and UX decisions around edits and corrections.

recommendation

Design principle: Progressive disclosure for complexity. The system manages extremely complex data (millions of materials, thousands of POs, hundreds of thousands of documents). The UX must present simple, focused views by default with the ability to drill into full complexity when needed.

Derived from claim_029 (very large datasets) and the prompt's requirement for 'clear and fast navigation' despite complexity. This principle guides information architecture and screen design.

Spec Map
Product overview
A concise summary of the product, its core value proposition, and its primary users.
interpretation
critical

A traceability-first materials management platform for EPC projects. The product enables any stakeholder to answer 'where is my material and when will it arrive?' by navigating a complete, bidirectional material lineage graph from engineering definition through procurement, logistics, warehousing, construction issue, and closeout.

Consolidates the confirmed core principle (claim_001) and the solution shape product concept. This is the anchor for the entire spec.

interpretation

The product is a commercial multi-tenant SaaS platform sold to EPC contractors, with per-tenant isolation and optional dedicated infrastructure for very large customers.

Confirmed decision dec_001 and claim_004. This shapes architecture, security, and deployment.

interpretation

The product replaces fragmented spreadsheets, legacy ERP modules, and disconnected point solutions currently used to manage materials across EPC projects.

Confirmed claim_003. This positions the product as a unified platform, not a point solution.

decision
critical

Decision: Should the product be organized around a traceability-first navigation model (material lineage graph as the central surface) or a module-based navigation model (separate engineering, procurement, logistics, and construction modules)?

This was proposed in the solution shape board but not resolved. It fundamentally shapes the UX and information architecture.

risk

Risk: The scope is extremely broad, covering the entire EPC materials lifecycle. Building all capabilities at once risks a shallow implementation where no single workflow is deep enough to be useful.

Confirmed risk claim_031. Mitigation is the phased depth-first roadmap (dec_005).

tradeoff

Tradeoff: The phased depth-first roadmap means logistics, warehousing, construction, and closeout workflows will not be available in the initial release. Early adopters who need full lifecycle coverage may be disappointed, but this approach ensures the core engineering-to-procurement chain is deep and reliable before expanding.

Confirmed tradeoff from solution shape board. This is a permanent spec constraint.

User roles
All roles that interact with the system, with their responsibilities and key activities.
interpretation

Engineering discipline leads and material coordinators: Define material classes, commodity codes, specifications, catalogues, manufacturers, units of measure, tags, equipment references, bulk materials, BOMs/MTOs, engineering quantities, revisions, allowances, and required-on-site dates. Own the Define stage.

Confirmed claim_005 and dec_010 (Define stage owned by Engineering).

interpretation

Procurement professionals (buyers, expeditors, supplier quality engineers): Manage RFQs, bid evaluations, purchase orders, supplier progress tracking, vendor documentation, and expediting. Contribute commercial reference data to the Define stage. Own the Procure stage.

Confirmed claim_006 and dec_010 (Procurement contributes to Define).

interpretation

Logistics and warehouse personnel: Manage shipments, packing lists, goods receipt, inventory, storage locations, and material movements across sites and laydown yards. Own the Store stage.

Confirmed claim_007.

interpretation

Construction and commissioning teams: Request materials against work packages, check availability, issue materials to the field, and track material availability by system and turnover package. Own the Issue stage and drive continuous Analyze Shortages.

Confirmed claim_008 and dec_007 (Analyze Shortages driven by Construction & Commissioning).

interpretation

Project management and client representatives: Use dashboards, KPIs, drill-downs, and exception reports to monitor material status, shortages, and project health.

Confirmed claim_010.

interpretation

Project Controls: Drives project-end closeout reconciliation and surplus disposition. Owns the Closeout Reconcile stage.

Confirmed claim_052 and dec_007 (Closeout Reconcile driven by Project Controls).

interpretation

Governance & Audit role: Owns audit review, exception investigation, and compliance reporting. Platform automation enforces RBAC, approval limits, and immutable audit logging.

Confirmed claim_054 (hybrid governance model).

risk

Risk: Getting all stakeholders (engineering, procurement, logistics, warehouse, construction, suppliers) to adopt a single system may face resistance, especially from suppliers who may already use their own systems.

Confirmed risk claim_030. Mitigation: low-friction supplier portal.

Primary workflows
End-to-end user journeys organized by operating model stages.
interpretation

Define workflow (Engineering + Procurement): Import MTO data from engineering systems, validate against material master, compare revisions, consolidate by project/area/discipline/work package, and convert into procurement requirements. Engineering owns the workflow; Procurement contributes commercial reference data (AVLs, commodity capabilities, supplier qualifications).

Confirmed claim_056 and dec_010. This is the first stage of the operating model.

interpretation

Procure workflow (Procurement): Create material requisitions from approved MTO items, route through configurable approvals, create inquiry packages and RFQs, select bidders, manage clarifications, receive quotations, perform bid evaluations, negotiate, approve award recommendations, and convert awarded lines into purchase orders.

Confirmed claim_006. This is the second stage of the operating model.

interpretation

Supplier Portal workflow (Suppliers): Suppliers access their own RFQs and orders, submit quotations, acknowledge orders, answer clarifications, update manufacturing progress, provide inspection notifications, packing and shipment information, invoices, and vendor documents. Suppliers support only — they never drive a stage.

Confirmed claim_055 and dec_009.

interpretation

Track workflow (Procurement + Quality): Expediting with planned/forecast/actual milestones, vendor document control with submission schedules and review cycles, quality surveillance and inspection with notifications, test records, certificates, non-conformities, punch items, and release-for-shipment decisions.

Confirmed claim_006. This is the third stage of the operating model.

interpretation

Store workflow (Logistics + Warehouse): Manage shipping releases, consignments, packages, transport legs, customs, goods receipt, quantity and condition checks, quarantine, stock placement, transfers, cycle counts, and preservation. Maintain complete inventory ledger.

Confirmed claim_007. This is the fourth stage of the operating model.

interpretation

Issue workflow (Construction + Commissioning): Create material requests and reservations against work packages, check availability, obtain approvals, pick and issue materials, process partial issues, returns, transfers, damaged materials, and consumables. Mobile-friendly with barcode/QR scanning, photos, and signatures.

Confirmed claim_008. This is the fifth stage of the operating model.

interpretation

Analyze Shortages workflow (Construction & Commissioning): Continuous comparison of engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations, and issued quantities. Identify shortages, excesses, and inconsistencies. Initiate recovery actions (additional procurement, expediting, stock transfer, substitution, engineering resolution).

Confirmed claim_053 and dec_007 (split Reconcile stage).

interpretation

Closeout Reconcile workflow (Project Controls): Reconcile engineering quantities, purchased quantities, shipped quantities, received quantities, issued quantities, returns, damaged quantities, and remaining inventory. Manage surplus disposition (reuse, return, transfer, sale, disposal). Produce final material reconciliation reports.

Confirmed claim_052 and dec_007 (Closeout Reconcile driven by Project Controls).

decision

Decision: What should be the primary entry point for the main journey? (A) Material-centric entry: search or scan any material, then navigate the chain. (B) Project-centric entry: select project, then drill into areas, work packages, materials. (C) Role-centric entry: land on role-specific dashboard, then navigate to work queues.

This was proposed in the solution shape board but not resolved. It shapes the primary navigation and landing experience.

Functional requirements
Testable, traceable requirements with IDs.
recommendation
critical

FR-001: The system shall provide a bidirectional traceability view that allows any user to navigate from an engineering MTO item through requisition, RFQ, bid evaluation, purchase order, supplier progress, documents, inspection, shipment, packing list, receipt, warehouse location, reservation, construction issue, and final reconciliation — and navigate the same chain backwards from any physical material item.

Traceable to claim_001 (core principle). This is the anchor functional requirement.

recommendation
critical

FR-002: The system shall preserve full lineage between engineering MTO revisions, requisitions, RFQs, bids, POs, shipments, receipts, and issues, such that any downstream entity can be traced back to its engineering source and historical revisions.

Traceable to claim_043 (full lineage preservation).

recommendation

FR-003: The system shall track quantities at multiple levels: engineering requirement, requisition, ordered, shipped, received, reserved, issued, returned, damaged, and remaining.

Traceable to claim_044 (multi-level quantity tracking).

recommendation

FR-004: The system shall record every material movement (receipt, transfer, issue, return) as an immutable transaction with timestamp, actor, and location.

Traceable to claim_042 (immutable material movements).

recommendation

FR-005: The system shall support engineering change management with impact analysis on requisitions, orders, manufacturing, shipments, and site stock, without losing historical information.

Traceable to claim_012 (engineering change ripple).

recommendation

FR-006: The system shall provide continuous shortage and availability analysis comparing engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations, and issued quantities, showing shortages, excesses, and inconsistencies by project, discipline, area, system, work package, and required date.

Traceable to claim_013 (shortage discovery).

recommendation

FR-007: The system shall maintain complete audit history for revisions, approvals, quantity changes, status changes, and critical data modifications, with immutable records.

Traceable to claim_016 (audit history table-stakes).

recommendation

FR-008: The system shall provide a secure supplier portal where suppliers can access only their own RFQs and orders, submit quotations, acknowledge orders, answer clarifications, update manufacturing progress, provide inspection notifications, packing and shipment information, invoices, and required vendor documents.

Traceable to claim_020 (supplier portal).

recommendation

FR-009: The system shall automate project closeout reconciliation, reconciling engineering quantities, purchased quantities, shipped quantities, received quantities, issued quantities, returns, damaged quantities, and remaining inventory into final reports.

Traceable to claim_021 (automated closeout reconciliation).

decision

Decision: Should the product support project-specific numbering schemes (e.g., requisition numbers, PO numbers) as a first-class configuration, or enforce a global numbering scheme with project prefixes?

This was proposed in the project brief board but not resolved. It affects data model and business rules.

Screen / page inventory
Every screen needed for the user journeys, with purpose and key elements.
interpretation
critical

Screen: Traceability View. Purpose: Answer 'where is my material and when will it arrive?' by showing the complete lineage graph from engineering MTO through current status. Key elements: bidirectional lineage graph, drill-down to transaction details, current stage indicator, blocker highlighting, action buttons (approve, expedite, transfer, substitute, issue).

Traceable to claim_014 (core JTBD). This is the central screen.

interpretation

Screen: Role-aware Workspace. Purpose: Landing page showing work queues and exceptions relevant to the user's role. Key elements: work queue, exception list (overdue milestones, shortages, quality holds, shipment delays), KPIs, quick actions.

Traceable to claim_022 (desktop-first for office roles) and design principle 'Role-aware, not role-siloed'.

interpretation

Screen: MTO Import and Validation. Purpose: Import MTO data from engineering systems, validate, compare revisions, and consolidate. Key elements: file upload, mapping configuration, validation results, error list, revision comparison, consolidation by project/area/discipline/work package.

Traceable to claim_005 (engineering MTO management).

interpretation

Screen: Requisition Management. Purpose: Create and manage material requisitions with configurable approvals. Key elements: requisition list, requisition detail, line items, technical requirements, approval workflow, revision history, hold/cancel actions.

Traceable to claim_006 (procurement workflow).

interpretation

Screen: RFQ and Bid Evaluation. Purpose: Create inquiry packages, select bidders, manage clarifications, compare quotations, and evaluate bids. Key elements: RFQ list, bidder selection, clarification thread, quotation comparison table, deviation recording, technical/commercial evaluation, award recommendation.

Traceable to claim_006 (procurement workflow).

interpretation

Screen: Purchase Order Management. Purpose: Manage purchase orders with revisions, line items, and variation orders. Key elements: PO list, PO detail, line items, delivery schedules, approval thresholds, variation orders, traceability to requisitions and RFQs.

Traceable to claim_006 (procurement workflow).

interpretation

Screen: Supplier Portal. Purpose: Secure supplier-facing surface for RFQ access, quotation submission, order acknowledgement, progress updates, and document submission. Key elements: RFQ list (own only), quotation form, order list, progress update form, document upload, clarification thread.

Traceable to claim_009 and claim_020 (supplier portal).

interpretation

Screen: Expediting Dashboard. Purpose: Track supplier milestones (planned, forecast, actual) and highlight overdue milestones and forecast delivery risks. Key elements: milestone timeline, progress percentages, forecast dates, supplier commitments, risks, recovery actions, exception reports.

Traceable to claim_006 (expediting).

interpretation

Screen: Warehouse Receipt and Inventory. Purpose: Manage goods receipt, quantity and condition checks, stock placement, transfers, and inventory. Key elements: expected receipts list, receipt form with barcode/QR scanning, over/short/damaged report, storage location assignment, inventory ledger, cycle count.

Traceable to claim_007 (warehousing).

interpretation

Screen: Construction Issue. Purpose: Create material requests, check availability, pick and issue materials. Key elements: material request form, availability check, reservation, pick list, issue transaction, partial issue, return, mobile-friendly with barcode/QR scanning, photos, signatures.

Traceable to claim_008 (construction issue).

interpretation

Screen: Closeout Reconciliation. Purpose: Reconcile all quantity types and manage surplus disposition. Key elements: reconciliation report, quantity comparison table, surplus disposition actions (reuse, return, transfer, sale, disposal), final material reconciliation reports.

Traceable to claim_052 (Project Controls closeout).

decision

Decision: Should the mobile experience be a responsive web app or a native mobile app for warehouse and field workflows?

Claim_022 confirms mobile-optimized for warehouse/field, but the implementation approach (responsive web vs native) was not resolved.

Data model
Every entity and field, with relationships and constraints.
interpretation
critical

Entity: Material. Central entity representing any physical item. Attributes: material_id, material_class_id, commodity_code, specification_id, description, uom_id, material_type (tagged/bulk), manufacturer_id, model_number, status, created_at, updated_at, deleted_at. Relationships: belongs to MaterialClass, has many MaterialSpecifications, has many MaterialTags, has many InventoryItems, has many RequisitionLines, has many POLines.

Traceable to claim_040 (Material as central entity).

interpretation

Entity: Project. Represents an EPC project. Attributes: project_id, project_code, project_name, client_id, contractor_id, base_currency, status, start_date, end_date, created_at, updated_at. Relationships: has many Areas, has many WorkPackages, has many Disciplines, has many Warehouses, has many Requisitions, has many PurchaseOrders, has many Suppliers (through project approvals).

Traceable to claim_002 (multi-project platform).

interpretation

Entity: WorkPackage. Represents a work package within a project. Attributes: work_package_id, project_id, area_id, discipline_id, system_id, description, status, created_at, updated_at. Relationships: belongs to Project, belongs to Area, belongs to Discipline, has many MTOItems, has many Reservations.

Traceable to claim_048 (hierarchical project structures).

interpretation

Entity: MTORevision. Represents a version of engineering material take-off data. Attributes: mto_revision_id, project_id, revision_number, revision_date, source_system, import_batch_id, status (draft/validated/approved/superseded), created_at, updated_at. Relationships: belongs to Project, has many MTOItems, has many Requisitions (created from it).

Traceable to claim_043 (lineage preservation).

interpretation

Entity: MTOItem. A single line in an MTO revision. Attributes: mto_item_id, mto_revision_id, material_id, quantity, uom_id, discipline_id, area_id, work_package_id, system_id, required_on_site_date, allowance_percentage, status, created_at, updated_at. Relationships: belongs to MTORevision, belongs to Material, has many RequisitionLines, has many ShortageAnalysisRecords.

Traceable to claim_043 (lineage preservation).

interpretation

Entity: Requisition. A material requisition created from MTO items. Attributes: requisition_id, requisition_number, project_id, revision_number, status (draft/in_review/approved/rejected/on_hold/cancelled), required_date, technical_requirements, inspection_requirements, documentation_requirements, created_by, approved_by, created_at, updated_at, deleted_at. Relationships: belongs to Project, has many RequisitionLines, has many RFQs, has many Attachments.

Traceable to claim_043 (lineage preservation).

interpretation

Entity: PurchaseOrder. A purchase order or subcontract. Attributes: po_id, po_number, project_id, supplier_id, currency, incoterms, payment_terms, status (draft/issued/acknowledged/in_progress/partially_received/completed/cancelled), total_value, created_at, updated_at, deleted_at. Relationships: belongs to Project, belongs to Supplier, has many POLines, has many Shipments, has many Invoices, has many VendorDocuments.

Traceable to claim_043 (lineage preservation).

interpretation

Entity: InventoryItem. A physical material item or quantity in a warehouse. Attributes: inventory_item_id, material_id, warehouse_id, storage_location_id, quantity, uom_id, serial_number, heat_number, batch_number, status (available/reserved/quarantined/damaged/issued), received_date, created_at, updated_at, deleted_at. Relationships: belongs to Material, belongs to Warehouse, has many MaterialMovements, has many Reservations.

Traceable to claim_042 (immutable material movements).

interpretation

Entity: MaterialMovement. An immutable record of a material movement. Attributes: movement_id, inventory_item_id, movement_type (receipt/transfer/issue/return/adjustment), from_location_id, to_location_id, quantity, uom_id, actor_id, timestamp, reference_document_type, reference_document_id, created_at. Relationships: belongs to InventoryItem, belongs to Warehouse (from/to), belongs to User (actor).

Traceable to claim_042 (immutable material movements).

interpretation

Entity: Supplier. A supplier or manufacturer. Attributes: supplier_id, supplier_code, supplier_name, qualification_status, contact_info, created_at, updated_at, deleted_at. Relationships: has many SupplierCommodityCapabilities, has many ProjectApprovals, has many PurchaseOrders, has many QualityFindings, has many PerformanceEvaluations.

Traceable to claim_046 (supplier data linked to projects, commodities, POs).

interpretation

Entity: VendorDocument. A document submitted by a supplier or generated by the system. Attributes: document_id, document_number, document_type, supplier_id, po_id, revision_number, status (submitted/in_review/approved/rejected/overdue), submission_date, review_due_date, approval_code, file_reference, created_at, updated_at, deleted_at. Relationships: belongs to Supplier, belongs to PurchaseOrder, has many Transmittals, has many ReviewComments.

Traceable to claim_049 (documents as first-class entities).

interpretation

Entity: Shipment. A consignment of materials from supplier to site. Attributes: shipment_id, shipment_number, supplier_id, po_id, freight_forwarder_id, transport_mode, incoterms, etd, eta, actual_departure_date, actual_arrival_date, status (planned/in_transit/customs_cleared/received), created_at, updated_at, deleted_at. Relationships: belongs to Supplier, belongs to PurchaseOrder, has many Packages, has many TransportLegs, has many ShippingDocuments.

Traceable to claim_041 (tagged and bulk materials).

decision

Decision: Should the product support multi-currency with per-project base currency and automatic conversion, or require manual currency conversion for cross-currency transactions?

Claim_047 confirms multi-currency support is needed, but the conversion mechanism was not resolved.

Business rules
Validations, calculations, and decision logic.
recommendation

BR-001: Shortage calculation: shortage = engineering_requirement - (ordered + received - issued - damaged). Excess = (ordered + received) - engineering_requirement. Inconsistency = any mismatch between quantity types at any level.

Traceable to claim_044 (multi-level quantity tracking). This is the core shortage analysis rule.

recommendation

BR-002: Engineering change impact rule: When an MTO revision changes quantities or specifications, the system shall identify all downstream requisitions, orders, manufacturing, shipments, and site stock affected and flag them for review.

Traceable to claim_012 (engineering change ripple).

recommendation

BR-003: Audit immutability rule: Once a material movement, status change, approval, or critical data modification is recorded, it cannot be modified or deleted. Corrections are made through new transactions that reference the original.

Traceable to claim_016 (audit history table-stakes).

recommendation

BR-004: Soft delete rule: User-facing entities (requisitions, POs, suppliers, inventory items) use soft delete. Deleted records are preserved with deleted_at timestamp and excluded from active views but retained for audit history.

Traceable to claim_050 (soft delete).

decision

Decision: Should project-specific numbering schemes be enforced as a business rule (e.g., requisition numbers must follow project-specific patterns) or left as a configuration option?

Claim_045 confirms project-specific numbering is needed, but enforcement level was not resolved.

Permissions / access model
What each role can do, with scope restrictions.
interpretation

Permission: Engineering role can create, edit, and approve MTO revisions, material definitions, and requisitions. Scope: restricted by project, discipline, and area.

Traceable to claim_054 (RBAC enforced by platform automation) and claim_005 (engineering role).

interpretation

Permission: Procurement role can create and manage RFQs, bids, POs, and expediting. Scope: restricted by project, organization, and supplier.

Traceable to claim_054 (RBAC) and claim_006 (procurement role).

interpretation

Permission: Logistics and warehouse roles can manage shipments, receipts, inventory, and material movements. Scope: restricted by project, location, and warehouse.

Traceable to claim_054 (RBAC) and claim_007 (logistics/warehouse role).

interpretation

Permission: Construction role can create material requests, reservations, and issue materials. Scope: restricted by project, work package, and area.

Traceable to claim_054 (RBAC) and claim_008 (construction role).

interpretation

Permission: Supplier role can access only their own RFQs and orders, submit quotations, acknowledge orders, update progress, and submit documents. Scope: strictly isolated to own data via row-level security.

Traceable to claim_009 (supplier portal) and dec_002 (integrated with role-based access).

interpretation

Permission: Governance & Audit role can review audit logs, investigate exceptions, and generate compliance reports. Scope: tenant-wide read access to audit data.

Traceable to claim_054 (Governance & Audit role).

risk

Risk: The integrated supplier portal (same backend, separate UX) creates a security boundary challenge. External supplier users must be strictly isolated to their own RFQs and orders, requiring robust row-level security and careful API authorization to prevent data leakage between tenants and suppliers.

Confirmed risk from project brief board. This is a permanent spec risk.

decision

Decision: Should approval authority limits be configured per role, per user, or per project?

Claim_054 confirms approval limits are enforced, but the configuration granularity was not resolved.

Integrations
External systems and interfaces.
interpretation

Integration: Standards-first integration layer with REST API, webhooks, and Excel/CSV import/export. Named connectors for dominant EPC toolchain (Aveva, Hexagon/SmartPlant, SAP, Oracle) built as adapters over the REST/import layer.

Confirmed decision dec_006 (standards-first integration strategy).

interpretation

Integration: Engineering/design systems for MTO import. ERP and finance platforms for cost and payment data. Project scheduling systems for work package alignment. Document management systems for vendor document linking. Supplier systems and logistics services for shipment tracking.

Traceable to claim_032 (integration complexity) and the original prompt's integration requirements.

risk

Risk: Integration with external systems may require custom connectors for each customer's specific toolchain, increasing implementation cost and time.

Confirmed risk claim_032. Mitigation: standards-first integration layer.

decision

Decision: Should the REST API be versioned from day one (e.g., /api/v1/) or left unversioned until breaking changes are needed?

Claim_039 confirms REST API is a priority, but versioning strategy was not resolved.

Non-functional requirements
Performance, scalability, security, and operational requirements.
interpretation

NFR-001: The system shall support the 'Large' tier baseline: 100k-1M material items, 500-2000 concurrent users. Architecture shall scale to 'Very large' (>1M items, >2000 users) via partitioning, read replicas, and async materialized views for traceability queries.

Confirmed claim_029 (Large tier baseline, scale to Very large).

interpretation

NFR-002: The system shall support timezone-aware timestamps and multi-language reference data. All user-facing times shall be displayed in the user's local timezone.

Confirmed claim_023 (multi-timezone usage) and claim_051 (timezone-aware storage).

interpretation

NFR-003: The system shall degrade gracefully when connectivity is lost. Full offline-capable mobile workflows are a later-phase enhancement.

Confirmed claim_024 (graceful degradation first).

tradeoff

Tradeoff: Real-time traceability vs. performance at very large scale. Bidirectional traceability queries across millions of material items and hundreds of thousands of transactions may be expensive. Recommended position: async materialized views for traceability queries with eventual consistency (seconds to minutes), while transactional operations remain strongly consistent.

Confirmed tradeoff from solution shape board.

decision

Decision: Should traceability queries be served from async materialized views (eventual consistency) or from the transactional database (strong consistency)?

This tradeoff was proposed but not resolved. It affects performance and consistency guarantees.

Acceptance criteria
Observable, testable criteria for key capabilities.
recommendation
critical

AC-001: Given a material item with a complete lineage chain, when a user opens the traceability view, then the system shall display the complete bidirectional lineage graph from engineering MTO through current status within 3 seconds.

Traceable to claim_001 (core principle). Observable and testable.

recommendation

AC-002: Given a material movement (receipt, transfer, issue, return), when the movement is recorded, then the system shall create an immutable transaction with timestamp, actor, and location that cannot be modified or deleted.

Traceable to claim_042 (immutable material movements).

recommendation

AC-003: Given engineering requirements, requisition quantities, ordered quantities, shipped quantities, received inventory, reservations, and issued quantities, when the shortage analysis runs, then the system shall identify shortages, excesses, and inconsistencies by project, discipline, area, system, work package, and required date.

Traceable to claim_013 (shortage discovery).

recommendation

AC-004: Given a supplier user logged into the portal, when they access any RFQ or order, then the system shall only show RFQs and orders belonging to that supplier, with no data leakage from other suppliers or tenants.

Traceable to claim_009 (supplier portal isolation).

recommendation

AC-005: Given a project at closeout, when the reconciliation runs, then the system shall produce a final material reconciliation report reconciling engineering quantities, purchased quantities, shipped quantities, received quantities, issued quantities, returns, damaged quantities, and remaining inventory.

Traceable to claim_021 (automated closeout reconciliation).

Out of scope
Explicitly excluded capabilities.
constraint

Out of scope: General-purpose ERP functionality — financial accounting, HR, payroll, and other ERP functions are explicitly out of scope.

Confirmed claim_025 (not a general-purpose ERP).

constraint

Out of scope: Full-featured document management system — while the product manages vendor documents and links to external DMS, it does not replace a full DMS with version control, collaboration, and archival capabilities.

Confirmed claim_026 (not a DMS).

constraint

Out of scope: Project scheduling and planning — while the product integrates with project scheduling systems and tracks material availability by work package, it does not replace Primavera P6 or similar scheduling software.

Confirmed claim_027 (not a scheduling tool).

constraint

Out of scope: 3D model viewer and engineering design tool — while the product imports MTO data from engineering systems, it does not create or edit engineering designs.

Confirmed claim_028 (not a 3D model viewer).

constraint

Out of scope (phase 1): Full offline-capable mobile workflows. Graceful degradation is the baseline; full offline with local data sync is a later enhancement.

Confirmed claim_024 (graceful degradation first).

Remaining assumptions
Unconfirmed claims being relied on.
hypothesis

Assumption: Multi-currency support is needed with per-project base currency. This was accepted as an open decision but not explicitly confirmed by the user.

Claim_047 was accepted without resolution. This is an unconfirmed assumption being relied on.

hypothesis

Assumption: Project-specific numbering schemes are required as a first-class configuration. This was proposed but not resolved.

Claim_045 was accepted without resolution. This is an unconfirmed assumption being relied on.

hypothesis

Assumption: Multi-language UI is required. The original prompt mentions 'languages' but the user has not explicitly confirmed the scope of localization (which languages, which UI elements).

Claim_051 was accepted without resolution. This is an unconfirmed assumption being relied on.

hypothesis

Assumption: The mobile experience for warehouse and field workflows will be a responsive web app, not a native mobile app. This was not explicitly resolved.

Claim_022 confirms mobile-optimized but not the implementation approach. This is an unconfirmed assumption.

hypothesis

Assumption: Approval authority limits are configured per role with project override. This was not explicitly resolved.

Claim_054 confirms approval limits are enforced, but granularity is unconfirmed.

Workflow / Roles
Sandbox
Swimlane workflow
Sandbox
Specification

EPC Business Materials Management — Specification

Product overview

An enterprise, multi-tenant materials management and bidirectional traceability SaaS platform for EPC (Engineering, Procurement, Construction) capital projects. It connects engineering definitions, procurement packages, vendor fabrication, international logistics, laydown warehousing, and field construction into an unbroken immutable lineage graph, providing real-time shortage forecasting and closeout reconciliation.

Problem statement

In large-scale EPC projects, material data is fragmented across engineering MTO spreadsheets, ERP modules, logistics spreadsheets, and field logs. This causes severe lack of visibility, undetected supply chain delays, unaccounted material surpluses or shortages, costly engineering change ripple effects, and inaccurate closeout reconciliations.

Target users & roles

  • Engineering Lead / Material Coordinator — Defines material catalogs, specifications, imports and validates MTO revisions, tracks engineering design quantities, and initiates procurement requisitions.
  • Procurement Specialist / Buyer — Structures RFQ inquiry packages, evaluates technical and commercial supplier bids, issues purchase orders, and monitors commitment values.
  • Expeditor & Quality Inspector — Monitors supplier manufacturing milestones, tracks vendor document approval cycles, conducts inspections, issues quality findings, and grants release-for-shipment.
  • Logistics Coordinator & Warehouse Manager — Tracks shipping consignments, manages customs clearance, performs goods receipts, records over/short/damaged items, and manages storage bin placement.
  • Construction & Commissioning Lead — Reserves materials against work packages and systems, issues items to the field with mobile barcode scanning, handles returns, and tracks shortage alerts.
  • Project Controls Lead — Supervises project-wide material reconciliation, performs surplus disposition, monitors KPIs, and authorizes closeout reports.
  • Supplier Representative — External vendor responding to RFQs, submitting quotations, acknowledging POs, uploading manufacturing progress, and submitting shipping transmittals via isolated portal.
  • Governance & Compliance Auditor — Inspects immutable audit trails, verifies approval thresholds and delegation chains, and reviews regulatory compliance across all project entities.

User journeys

MTO Import to Purchase Order Issuance

  1. Engineering Lead uploads an MTO CSV/Excel revision file to the MTO Import screen.
  2. The system validates catalog codes against the Material Master, computes revision delta compared to baseline, and highlights quantity differences.
  3. Engineering Lead creates a Material Requisition for delta quantities and submits it through multi-tier approval.
  4. Upon requisition approval, Procurement Specialist bundles lines into an RFQ package and issues inquiry invitations to approved vendors via the Supplier Portal.
  5. Suppliers submit commercial and technical bids via their secure isolated portal view.
  6. Procurement Specialist performs automated bid comparison, records deviations, enters award recommendation, and gains procurement approval.
  7. System generates a Purchase Order with line-level traceability to original MTO items, issuing an acknowledgement request to the awarded supplier.

Supplier Progress, Quality Inspection, and Site Receipt

  1. Supplier acknowledges PO, updates fabrication milestone progress, and submits required vendor documents.
  2. Expeditor reviews document review cycles and receives an Inspection Notification from the supplier.
  3. Quality Inspector conducts surveillance, logs inspection findings and non-conformities, and issues a formal Release for Shipment.
  4. Supplier inputs packing list dimensions and consignment details; Logistics Coordinator assigns freight forwarder and tracks transit milestones.
  5. Consignment arrives at site; Warehouse Operator scans barcode/QR tags on packages via mobile responsive view.
  6. Operator records Goods Receipt, performs visual condition checks, logs an Over/Short/Damaged (OS&D) report if discrepancies exist, and assigns bin locations creating immutable Material Movement ledger records.

Work Package Reservation, Field Issue, and Project Closeout

  1. Construction Lead checks real-time material availability for Work Package WP-102 and creates a reservation.
  2. System confirms reserved stock and generates a digital pick-list for warehouse crew.
  3. Warehouse crew picks material, scans item QR/heat tags, captures field supervisor digital signature, and posts an Issue Transaction.
  4. System automatically updates inventory balance and recalculates live continuous shortage/excess analytics.
  5. At project commissioning completion, Project Controls Lead launches Closeout Reconciliation.
  6. System matches engineering MTO quantities, ordered quantities, received quantities, issued quantities, and scrap/returns.
  7. Project Controls Lead records surplus disposition actions (transfer, return to vendor, scrap, sale) and exports signed closeout reconciliation audit reports.

Functional requirements

FR-001: Bidirectional Lineage and Traceability Graph

The system shall maintain a persistent graph relationship from engineering MTO items through Requisitions, RFQs, Bids, POs, Expediting Milestones, Inspections, Shipments, Warehouse Stock, Reservations, and Field Issues, enabling instant two-way lookup.

Acceptance criteria:

  • Given a physical inventory item serial or heat number, when a user queries the Traceability Graph, then the system renders the entire upstream lineage back to the originating MTO item and engineering revision in less than 3 seconds.
  • Given an engineering MTO item, when navigated forward, then the system displays real-time status across procurement, shipment, warehousing, and field installation.

FR-002: MTO Import, Delta Comparison, and Requisition Generation

The system shall import tabular MTO data, validate commodity specs against the hybrid Material Master, compare revisions to detect additions/deletions/quantity shifts, and generate requisitions for procurement.

Acceptance criteria:

  • Given a newly imported MTO revision file, when compared against the approved revision, then the system calculates line-level deltas and prevents duplicate requisitioning of previously ordered quantities.
  • Given invalid commodity codes or missing mandatory engineering tags in the import file, when processed, then the system halts import with granular line-level validation errors.

FR-003: Procurement RFQ, Commercial Bid Evaluation, and PO Management

The system shall support inquiry packaging, supplier bidding, technical/commercial evaluation with deviations, approval workflows by monetary threshold, and PO creation with revision versioning.

Acceptance criteria:

  • Given an approved Requisition, when a Buyer builds an RFQ, then only suppliers listed on the Approved Vendor List (AVL) for that commodity class can be selected.
  • Given multiple vendor quotes, when the Buyer opens Commercial Bid Evaluation, then the system standardizes currencies using project exchange rates and displays normalized cost comparison tables.
  • Given a PO value exceeding $250,000 (ASSUMED: default project threshold), when submitted for award, then the system routes approval to Project Manager and Finance Approver before issuance.

FR-004: Isolated Supplier Portal

The system shall provide an isolated supplier workspace enforcing strict row-level security where external vendors manage RFQs, quotes, PO acknowledgements, progress updates, document uploads, and shipment releases.

Acceptance criteria:

  • Given an authenticated Supplier user, when accessing the RFQ or PO register, then only records associated with that supplier's organization ID are queryable.
  • Given an active PO, when the supplier submits a Vendor Document revision, then a transmittal notification is dispatched to the assigned engineering document reviewer.

FR-005: Logistics Consignment and Multi-Leg Shipment Tracking

The system shall track shipping releases, freight forwarders, carriers, transport legs, customs clearance statuses, container/package packing lists, and forecast vs actual arrival dates.

Acceptance criteria:

  • Given a PO line with issued Release for Shipment, when a Shipment record is created, then multiple PO lines across different POs can be consolidated into a single consignment with package-level line mappings.
  • Given customs clearance status update to 'Cleared', when recorded, then the system updates the consignment status and triggers an expected site receipt notification.

FR-006: Warehouse Goods Receipt, OS&D Logging, and Bin Management

The system shall manage site warehouses, laydown storage zones, bin locations, goods receipts with barcode/QR scanning, quarantine holds, and over/short/damaged exception logging.

Acceptance criteria:

  • Given an incoming shipment, when a Warehouse Operator scans package QR codes, then the system verifies received items against the packing list and highlights any discrepancy.
  • Given a damaged crate, when marked as OS&D, then the system flags items as 'Quarantined', prevents reservation, and creates an OS&D inspection report with photo attachments.

FR-007: Work Package Reservation, Picking, and Mobile Field Issue

The system shall enable construction teams to reserve materials against hierarchical Work Packages and systems, perform pick-lists, record mobile digital signatures, and execute material issue/return transactions.

Acceptance criteria:

  • Given an approved Material Request for Work Package WP-01, when warehouse stock is confirmed, then the system transitions stock status from 'Available' to 'Reserved' preventing double allocation.
  • Given a field material issue on a mobile device, when the receiver signs and the transaction is committed, then the physical stock is decremented and an immutable Material Movement entry is written.

FR-008: Continuous Shortage Analysis and Impact Evaluation

The system shall continuously calculate material shortages and excesses by comparing engineering required quantities with ordered, received, reserved, and issued quantities across all project hierarchy nodes.

Acceptance criteria:

  • Given an engineering MTO revision increase or delivery delay, when the shortage engine computes balance, then affected downstream work packages and turnover packages are flagged with critical shortage alerts.
  • Given a detected shortage, when a user opens the recovery action drawer, then the system suggests options for stock substitution, PO expediting, or surplus re-allocation.

FR-009: Project Closeout Reconciliation and Surplus Disposition

The system shall perform multi-variable quantitative reconciliation at project completion and orchestrate surplus asset disposition workflows.

Acceptance criteria:

  • Given a project closeout initiation, when reconciliation executes, then the system outputs a complete matrix of MTO Required vs Ordered vs Shipped vs Received vs Issued vs Damaged vs Scrap vs Remaining Stock.
  • Given remaining surplus inventory, when disposition is set to 'Transfer to Project B', then the system creates an outbound inter-project transfer and updates tenant asset registers.

FR-010: Immutable Audit Trail and Compliance Governance

The system shall record all status transitions, approval authorizations, quantity overrides, and critical configuration changes in an append-only, tamper-evident audit ledger.

Acceptance criteria:

  • Given any update or soft-deletion of a requisition, PO, or inventory balance, when executed, then an AuditLog record is created containing actor_id, timestamp, previous_state, new_state, and client IP.
  • Given an audit log query by a Governance Auditor, when filtered by entity and date range, then the system exports an unalterable chronological audit transmittal.

Screen / page inventory

  • Traceability Graph Explorer — Provides interactive bidirectional visual graph navigation and timeline tracking for any material tag, MTO item, PO line, or physical asset.
    • Elements: Global Search & Scan Bar (Tag, Heat Number, MTO Code, PO Number), Interactive Lineage Node Diagram (MTO -> REQ -> RFQ -> PO -> EXP -> SHP -> WHS -> ISS), Node Detail Inspector Drawer with real-time milestone timestamps, Blocker & Exception Warning Badges (Overdue, OS&D, Quality Hold), Action Toolbar (Expedite, Initiate Substitution, View Document Transmittal)
  • Role-Aware Operations Dashboard — Personalized landing surface aggregating pending work queues, critical shortage alerts, approval bottlenecks, and operational KPIs.
    • Elements: Summary KPI Cards (Traceability Coverage, Shortage Count, Procurement Cycle Time, Supplier OTD), My Pending Approvals & Action Queue Table, Critical Path Shortage Alert Widget grouped by Work Package, Expediting Risk & Milestone Exception Heatmap, Quick Navigation Shortcuts to MTO Import, PO Creation, and Warehouse Receipt
  • Engineering MTO Import & Delta Comparison — Enables engineering leads to upload, map, validate, and compare MTO revisions against existing project baselines.
    • Elements: File Dropzone (Excel/CSV) with auto-column mapping, Validation Error & Warning Grid with in-line correction, Revision Delta Comparison Matrix (Added, Removed, Modified quantities), Discipline & Work Package Filtering Facets, Create Requisition Action Button for verified deltas
  • Procurement & Commercial Bid Evaluation — Allows buyers to manage RFQ inquiry packages, review vendor responses, and perform commercial bid comparisons.
    • Elements: Inquiry Package Summary & Approved Vendor Selector, Multi-Supplier Bid Comparison Grid with normalized currency conversion, Technical Deviation & Commercial Exception Table, Award Recommendation Form with threshold approval routing, PO Generation & Direct Supplier Transmittal Trigger
  • Supplier Collaboration Portal — External secure vendor workspace for quoting RFQs, acknowledging POs, uploading progress milestones, and submitting documents.
    • Elements: My Active RFQs & Open Purchase Orders Table, Quotation Submission & Milestone Update Form, Vendor Document Transmittal Upload with Revision Tracker, Inspection Notification Dispatcher, Packing List Builder & Shipping Readiness Notice
  • Warehouse Goods Receipt & OS&D Inspection — Mobile-optimized interface for warehouse operators to scan incoming consignments, verify packing lists, and record discrepancies.
    • Elements: Expected Deliveries Register & Barcode/QR Camera Scanner, Package Verification Checklist (Dimensions, Weight, Heat Numbers), Bin Location Selector & Laydown Yard Storage Map, OS&D (Over, Short, Damaged) Exception Logger with camera photo upload, Goods Receipt Note (GRN) Finalization and Print Label Action
  • Construction Reservation & Mobile Material Issue — Field interface for checking availability, creating work package reservations, and executing digital sign-off material issues.
    • Elements: Work Package & System Material Availability Browser, Reservation Cart & Approval Request Submission, Digital Pick-List with storage bin guidance, Mobile Barcode Tag Scanner for physical issue validation, Digital Signature Pad & Issue Confirmation Transaction Logger
  • Project Closeout & Surplus Reconciliation — Management tool for Project Controls to reconcile total project materials and execute surplus asset disposition.
    • Elements: Full-Lifecycle Reconciliation Matrix (Engineered vs Ordered vs Received vs Installed vs Remaining), Discrepancy & Scrap Ledger Table, Surplus Disposition Workflow Panel (Transfer, Resale, Return, Scrap), Closeout Sign-off Authorization Routing, Comprehensive Audit Package Export Button (PDF/Excel)

Data model

Tenant

Field Type Notes
id string Primary Key, UUID format
name string Corporate entity name, max length 255
slug string Unique URL identifier, indexed
created_at datetime Timestamp ISO8601
updated_at datetime Timestamp ISO8601

User

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant isolation key, indexed
email string User email, unique per tenant
full_name string User display name
supplier_id foreign_key->Supplier Nullable, set only if external supplier user
status enum(active, suspended, invited) Account status
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Role

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant isolation key
name string Role name e.g. EngineeringLead, Buyer, Expeditor, WarehouseOp
description string Role responsibility summary
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Permission

Field Type Notes
id string Primary Key, UUID
role_id foreign_key->Role Associated role
action enum(create, read, update, delete, approve, export, issue, reconcile) Allowed action verb
resource string Domain resource e.g. MTO, Requisition, PurchaseOrder, Inventory
created_at datetime Creation timestamp
updated_at datetime Update timestamp

UserRole

Field Type Notes
id string Primary Key, UUID
user_id foreign_key->User Assigned user
role_id foreign_key->Role Assigned role
project_id foreign_key->Project Nullable project scope override
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Project

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant isolation key
code string Project code e.g. PRJ-LNG-2026, unique per tenant
name string Project name
base_currency string Base currency code ISO 4217 e.g. USD, EUR
status enum(active, on_hold, completed, closed) Lifecycle status
start_date datetime Project start date
end_date datetime Project target completion date
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

Area

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Belongs to Project
code string Area code e.g. AREA-100
name string Area name e.g. Liquefaction Train 1
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Discipline

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant reference
code string Discipline code e.g. PIPING, ELECTRICAL, CIVIL, INSTRUMENTATION
name string Discipline name
created_at datetime Creation timestamp
updated_at datetime Update timestamp

WorkPackage

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Belongs to Project
area_id foreign_key->Area Associated Area
discipline_id foreign_key->Discipline Associated Discipline
code string CWP/IWP code e.g. WP-PIP-101
name string Work package description
status enum(planned, in_progress, completed, turned_over) Execution status
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Commodity

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Global or tenant commodity
code string Commodity code e.g. VALVE-BALL, PIPE-CS
name string Commodity descriptive title
created_at datetime Creation timestamp
updated_at datetime Update timestamp

MaterialClass

Field Type Notes
id string Primary Key, UUID
commodity_id foreign_key->Commodity Belongs to Commodity
class_name string Class classification e.g. Class 1500 Flanged
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Manufacturer

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant reference
name string Manufacturer name
country string Country of origin ISO code
created_at datetime Creation timestamp
updated_at datetime Update timestamp

MaterialSpecification

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant reference
code string Engineering specification code e.g. ASME-B16.34
description string Technical specification details
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Material

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant isolation
project_id foreign_key->Project Project reference for project extensions
material_class_id foreign_key->MaterialClass Classification
specification_id foreign_key->MaterialSpecification Engineering spec
manufacturer_id foreign_key->Manufacturer Nullable approved manufacturer
code string Material catalog code, indexed
description string Full descriptive title
uom string Unit of measure e.g. EA, M, KG
material_type enum(tagged, bulk) Distinguishes serialized tags from bulk quantities
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

MaterialTag

Field Type Notes
id string Primary Key, UUID
material_id foreign_key->Material Belongs to Material
project_id foreign_key->Project Associated project
tag_number string Unique tag identifier e.g. 10-HV-0012, indexed
serial_number string Manufacturer serial number
created_at datetime Creation timestamp
updated_at datetime Update timestamp

MTORevision

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
revision_number string Revision identifier e.g. Rev A, Rev 0, Rev 1
source_system string Originating engineering tool e.g. Aveva, SmartPlant
status enum(draft, validated, approved, superseded) Revision lifecycle state
created_at datetime Creation timestamp
updated_at datetime Update timestamp

MTOItem

Field Type Notes
id string Primary Key, UUID
mto_revision_id foreign_key->MTORevision Belongs to MTO Revision
material_id foreign_key->Material Material reference
work_package_id foreign_key->WorkPackage Target work package
quantity integer Base engineering quantity (supports decimal scaling via UOM)
allowance_percentage integer Engineering scrap/contingency allowance percentage
required_on_site_date datetime Target construction need date
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Requisition

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
created_by_user_id foreign_key->User Author
requisition_number string Project-formatted requisition code, unique per project
status enum(draft, in_review, approved, rejected, on_hold, cancelled) Approval state
required_date datetime Requested material need date
technical_requirements string Engineering technical specifications summary
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

RequisitionLine

Field Type Notes
id string Primary Key, UUID
requisition_id foreign_key->Requisition Belongs to Requisition
mto_item_id foreign_key->MTOItem Source MTO item for complete lineage
material_id foreign_key->Material Material reference
quantity integer Quantity to procure
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Supplier

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant reference
supplier_code string Unique vendor identifier e.g. SUP-9001
name string Supplier corporate legal name
qualification_status enum(approved, conditional, disqualified, pending_review) AVL status
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

SupplierEvaluation

Field Type Notes
id string Primary Key, UUID
supplier_id foreign_key->Supplier Evaluated supplier
project_id foreign_key->Project Evaluating project
score integer Score from 0 to 100
evaluator_user_id foreign_key->User Evaluating inspector/buyer
evaluation_date datetime Evaluation date
notes string Evaluation notes and observations
created_at datetime Creation timestamp
updated_at datetime Update timestamp

RFQ

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
requisition_id foreign_key->Requisition Source requisition
rfq_number string RFQ package code, unique per project
title string Inquiry title
status enum(draft, issued, evaluation, awarded, cancelled) Procurement stage
due_date datetime Bid submission deadline
created_at datetime Creation timestamp
updated_at datetime Update timestamp

RFQBidder

Field Type Notes
id string Primary Key, UUID
rfq_id foreign_key->RFQ Associated RFQ
supplier_id foreign_key->Supplier Invited supplier
invited_at datetime Invitation timestamp
status enum(invited, acknowledged, submitted, declined) Supplier response state
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Quote

Field Type Notes
id string Primary Key, UUID
rfq_id foreign_key->RFQ Belongs to RFQ
supplier_id foreign_key->Supplier Submitting supplier
quote_number string Supplier commercial reference
currency string Quotation currency ISO code e.g. USD, EUR
total_price integer Monetary total in quote currency
status enum(submitted, under_review, shortlisted, awarded, rejected) Commercial evaluation state
created_at datetime Creation timestamp
updated_at datetime Update timestamp

QuoteLine

Field Type Notes
id string Primary Key, UUID
quote_id foreign_key->Quote Belongs to Quote
requisition_line_id foreign_key->RequisitionLine Requisition item reference
unit_price integer Quoted unit price
offered_lead_time_days integer Manufacturing lead time in days
technical_deviation string Recorded engineering deviations
created_at datetime Creation timestamp
updated_at datetime Update timestamp

BidEvaluation

Field Type Notes
id string Primary Key, UUID
rfq_id foreign_key->RFQ Evaluated RFQ
awarded_quote_id foreign_key->Quote Winning supplier quote
evaluator_user_id foreign_key->User Lead Buyer
recommendation_rationale string Commercial and technical justification
approved_by_user_id foreign_key->User Approving authority
status enum(pending_approval, approved, rejected) Evaluation approval status
created_at datetime Creation timestamp
updated_at datetime Update timestamp

PurchaseOrder

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
supplier_id foreign_key->Supplier Awarded supplier
quote_id foreign_key->Quote Source commercial quote
po_number string PO code e.g. PO-88001, unique per project
currency string PO commercial currency
total_amount integer Total contractual value
incoterms string Incoterms e.g. FOB, CIF, DDP
payment_terms string Commercial payment terms e.g. Net 45
status enum(draft, issued, acknowledged, in_progress, partially_received, completed, cancelled) Order state
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

POLine

Field Type Notes
id string Primary Key, UUID
purchase_order_id foreign_key->PurchaseOrder Belongs to Purchase Order
requisition_line_id foreign_key->RequisitionLine Link back to requisition and MTO line
material_id foreign_key->Material Material reference
quantity integer Contracted purchase quantity
unit_price integer Agreed line unit price
promised_delivery_date datetime Contractual delivery date
created_at datetime Creation timestamp
updated_at datetime Update timestamp

VendorDocument

Field Type Notes
id string Primary Key, UUID
purchase_order_id foreign_key->PurchaseOrder Associated PO
supplier_id foreign_key->Supplier Supplier author
document_number string Vendor document register number
document_type enum(drawing, calculation, test_certificate, welding_book, quality_plan) Document category
revision_number string Vendor revision e.g. Rev 1
status enum(submitted, in_review, approved, approved_with_comments, rejected, overdue) Review status
submission_date datetime Submission timestamp
file_url string Storage blob URL or external DMS link
created_at datetime Creation timestamp
updated_at datetime Update timestamp

DocumentReview

Field Type Notes
id string Primary Key, UUID
vendor_document_id foreign_key->VendorDocument Reviewed document
reviewer_user_id foreign_key->User Engineering lead reviewer
approval_code enum(code_1_approved, code_2_approved_with_comments, code_3_rejected, code_4_for_information) Standard EPC approval code
comments string Engineering review markup comments
reviewed_at datetime Review completion date
created_at datetime Creation timestamp
updated_at datetime Update timestamp

InspectionRequest

Field Type Notes
id string Primary Key, UUID
purchase_order_id foreign_key->PurchaseOrder Target PO
supplier_id foreign_key->Supplier Requesting supplier
inspection_type enum(factory_acceptance_test, pre_shipment, raw_material, hydrostatic_test) Inspection gate
proposed_date datetime Scheduled inspection date
status enum(requested, scheduled, completed, waived) Inspection state
created_at datetime Creation timestamp
updated_at datetime Update timestamp

InspectionRecord

Field Type Notes
id string Primary Key, UUID
inspection_request_id foreign_key->InspectionRequest Belongs to Inspection Request
inspector_user_id foreign_key->User Quality Inspector
result enum(passed, passed_with_punch_list, failed) Surveillance result
punch_list_items string Recorded non-conformities and remediation requirements
release_for_shipment boolean True if formal Release for Shipment is granted
certificate_number string Quality release certificate number
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Shipment

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Destination project
supplier_id foreign_key->Supplier Originating supplier
shipment_number string Consignment code e.g. SHP-0044
freight_forwarder string Logistics service provider name
transport_mode enum(ocean_freight, air_freight, road_truck, rail) Transit mode
etd datetime Estimated time of departure
eta datetime Estimated time of arrival at destination site
actual_arrival_date datetime Actual arrival date
status enum(planned, departed, in_transit, customs_hold, customs_cleared, delivered) Logistics state
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

ShipmentPackage

Field Type Notes
id string Primary Key, UUID
shipment_id foreign_key->Shipment Belongs to Shipment
po_line_id foreign_key->POLine Source PO line
package_number string Crate/Container/Pallet tag code
quantity integer Packed quantity
weight_kg integer Gross weight in kg
created_at datetime Creation timestamp
updated_at datetime Update timestamp

Warehouse

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
code string Warehouse/Yard code e.g. WHS-MAIN, YARD-02
name string Facility title e.g. Main Laydown Yard
location_address string Site coordinates or address
created_at datetime Creation timestamp
updated_at datetime Update timestamp

StorageLocation

Field Type Notes
id string Primary Key, UUID
warehouse_id foreign_key->Warehouse Belongs to Warehouse
zone string Zone e.g. Zone A, Rack 04
bin_number string Bin identifier e.g. BIN-A4-12
created_at datetime Creation timestamp
updated_at datetime Update timestamp

InventoryItem

Field Type Notes
id string Primary Key, UUID
material_id foreign_key->Material Material reference
warehouse_id foreign_key->Warehouse Current warehouse location
storage_location_id foreign_key->StorageLocation Exact bin location
po_line_id foreign_key->POLine Originating purchase order line
quantity integer Current physical stock quantity
serial_number string Item serial number if tagged
heat_number string Mill certificate heat/batch number for metallurgy
status enum(available, reserved, quarantined, damaged, issued) Stock status
received_date datetime Site goods receipt timestamp
created_at datetime Creation timestamp
updated_at datetime Update timestamp
deleted_at datetime Soft delete timestamp

MaterialMovement

Field Type Notes
id string Primary Key, UUID
inventory_item_id foreign_key->InventoryItem Affected stock item
actor_user_id foreign_key->User User performing transaction
movement_type enum(receipt, transfer, issue, return, adjustment, scrap) Movement transaction type
from_location_id foreign_key->StorageLocation Source bin location
to_location_id foreign_key->StorageLocation Destination bin location
quantity integer Transacted quantity
reference_document_type string Reference entity e.g. Shipment, Reservation, OS&D
reference_document_id string Reference UUID
timestamp datetime Immutable ledger timestamp
created_at datetime Creation timestamp

Reservation

Field Type Notes
id string Primary Key, UUID
work_package_id foreign_key->WorkPackage Target Work Package
inventory_item_id foreign_key->InventoryItem Reserved physical stock item
reserved_by_user_id foreign_key->User Construction requester
quantity integer Reserved quantity
status enum(active, issued, cancelled) Reservation state
created_at datetime Creation timestamp
updated_at datetime Update timestamp

IssueTransaction

Field Type Notes
id string Primary Key, UUID
reservation_id foreign_key->Reservation Associated reservation
issued_by_user_id foreign_key->User Warehouse operator issuing stock
received_by_name string Field supervisor name receiving material
signature_image_url string Captured digital signature blob URL
quantity integer Issued quantity
issued_at datetime Issue execution timestamp
created_at datetime Creation timestamp

ShortageRecord

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
work_package_id foreign_key->WorkPackage Impacted work package
material_id foreign_key->Material Shortage material reference
required_quantity integer Engineering requirement
available_quantity integer Current available unreserved stock
shortage_quantity integer Calculated deficit (required - available)
required_date datetime Construction need date
status enum(open, under_expediting, substituted, resolved) Shortage resolution state
created_at datetime Calculation timestamp
updated_at datetime Update timestamp

ReconciliationRecord

Field Type Notes
id string Primary Key, UUID
project_id foreign_key->Project Associated project
material_id foreign_key->Material Reconciled material
engineered_quantity integer Total approved MTO quantity
purchased_quantity integer Total PO ordered quantity
shipped_quantity integer Total supplier dispatched quantity
received_quantity integer Total warehouse received quantity
issued_quantity integer Total field issued quantity
damaged_quantity integer Total OS&D scrap/damaged quantity
surplus_quantity integer Remaining physical inventory (received - issued - damaged)
disposition_action enum(none, transfer_project, return_to_supplier, sell, scrap) Closeout surplus action
created_at datetime Reconciliation timestamp
updated_at datetime Update timestamp

CurrencyExchangeRate

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant reference
from_currency string Source ISO currency e.g. EUR
to_currency string Target base ISO currency e.g. USD
rate_multiplier integer Fixed point multiplier rate (e.g., 10850 for 1.0850)
effective_date datetime Effective date
created_at datetime Creation timestamp

AuditLog

Field Type Notes
id string Primary Key, UUID
tenant_id foreign_key->Tenant Tenant isolation
actor_user_id foreign_key->User User triggering modification
entity_type string Target entity name e.g. PurchaseOrder, InventoryItem
entity_id string UUID of modified entity
action string Action description e.g. STATUS_CHANGE, APPROVAL, DELETE
previous_values string JSON serialized previous state
new_values string JSON serialized new state
ip_address string Client network address
created_at datetime Immutable record timestamp

Business rules

  • BR-001: Shortage Calculation — The net shortage for any Material M in WorkPackage WP is computed as: shortage = max(0, MTO_required_qty - (ordered_qty + available_inventory_qty - reserved_other_qty)). If shortage > 0, an active ShortageRecord is maintained.
  • BR-002: Approval Authority Thresholds — Purchase Orders with total_amount <= $50,000 require Lead Buyer approval; orders between $50,001 and $250,000 require Procurement Manager approval; orders > $250,000 require Project Director and Finance Lead approval.
  • BR-003: Immutable Material Movements — No MaterialMovement record can be updated or deleted via API or UI. Stock corrections must be executed by creating an offsetting MaterialMovement transaction of type 'adjustment' referencing the original transaction.
  • BR-004: Release for Shipment Gate — A ShipmentPackage can only be associated with PO lines whose linked InspectionRecord has release_for_shipment=true, or where the inspection requirement for that commodity class was explicitly waived by Quality Lead.
  • BR-005: Soft Delete Lifecycle — All user-facing entities (Project, Material, Requisition, PurchaseOrder, Supplier, Shipment, InventoryItem) must use soft deletion by setting deleted_at. Queries for active business operations must filter by deleted_at IS NULL.
  • BR-006: Supplier Portal Data Boundary — Any database query initiated by a user with a non-null supplier_id must strictly enforce supplier_id equality in WHERE clauses, preventing cross-supplier RFQ/PO inspection.

Permissions

Role Capabilities
Engineering Lead create:MTORevision; update:MTORevision; approve:MTORevision; create:Requisition; update:Requisition; read:Material; read:TraceabilityGraph; read:ShortageRecord
Buyer / Procurement Specialist read:Requisition; create:RFQ; update:RFQ; create:BidEvaluation; approve:BidEvaluation; create:PurchaseOrder; update:PurchaseOrder; approve:PurchaseOrder; read:Supplier; read:TraceabilityGraph
Expeditor & Quality Inspector read:PurchaseOrder; update:VendorDocument; create:DocumentReview; create:InspectionRequest; update:InspectionRequest; create:InspectionRecord; update:InspectionRecord; read:TraceabilityGraph
Logistics & Warehouse Manager create:Shipment; update:Shipment; create:InventoryItem; update:InventoryItem; create:MaterialMovement; read:PurchaseOrder; read:StorageLocation; read:TraceabilityGraph
Construction & Commissioning Lead create:Reservation; update:Reservation; create:IssueTransaction; read:InventoryItem; read:WorkPackage; read:ShortageRecord; read:TraceabilityGraph
Project Controls Lead read:Project; read:ReconciliationRecord; update:ReconciliationRecord; export:ReconciliationRecord; read:ShortageRecord; read:TraceabilityGraph; read:AuditLog
Supplier Representative read:RFQ (own organization only); create:Quote; update:Quote; read:PurchaseOrder (own organization only); create:VendorDocument; create:InspectionRequest; create:ShipmentPackage
Governance & Compliance Auditor read:AuditLog; export:AuditLog; read:Tenant; read:Project; read:TraceabilityGraph

Integrations

  • Engineering Design Tools (Aveva E3D, Hexagon SmartPlant 3D): CSV/Excel and REST API MTO import adapter for automated material revision ingests.
  • Enterprise ERP & Finance Systems (SAP S/4HANA, Oracle ERP Cloud): Two-way webhook and REST interface synchronizing Purchase Orders, commitments, payment terms, and actual invoices.
  • Project Scheduling Tools (Primavera P6, MS Project): REST synchronization of Work Package milestone required-on-site dates.
  • Document Management Platforms (OpenText, Bentley ProjectWise): Document linking adapters for supplier technical data books and cert packages.

Non-functional requirements

  • NFR-001 (Scalability): The data model and query engine shall support 1,000,000+ active Material records, 50,000+ Purchase Orders, and 2,000 concurrent active users per tenant without degradation.
  • NFR-002 (Performance): Bidirectional traceability graph visual queries and MTO delta calculations shall render within 3.0 seconds at p95 under standard load.
  • NFR-003 (Security & Multi-tenancy): Enforce strict row-level security (RLS) isolating tenant data and supplier partitions; all data in transit must use TLS 1.3 and data at rest encrypted via AES-256.
  • NFR-004 (Graceful Mobile Degradation): The mobile warehouse and field interfaces shall maintain local cached read states and graceful reconnect queueing when network connectivity fluctuates on job sites.
  • NFR-005 (Auditability): AuditLog events are immutable and must be preserved for the statutory project retention duration (minimum 10 years for industrial EPC).

Edge cases

  • EC-001: MTO Revision Decreases Quantity for already Ordered/Shipped Lines — The system halts auto-reduction of PO quantities, creates a 'Surplus / Engineering Cancel Warning' notification, and prompts the Buyer to negotiate a PO variation order or divert surplus stock to other work packages.
  • EC-002: Supplier Submits Partial Shipment with Mixed Purchase Orders — The system accepts multi-PO package consolidation, creating distinct ShipmentPackage records linked to individual POLines while maintaining a single customs transport consignment.
  • EC-003: Over-Receipt at Laydown Yard (Received Qty > PO Qty) — The system logs an OS&D discrepancy report, flags excess material into 'Quarantined - Over-Receipt' status, and dispatches an approval request to the Buyer before allowing bin placement.
  • EC-004: Intermittent Field Connectivity during Mobile Barcode Issue — The mobile web app caches scanned item IDs and signatures in browser local storage, updating local stock counters visually, and syncs the immutable IssueTransaction payload automatically once site Wi-Fi/cellular connection is restored.

Out of scope

  • OOS-001: General-purpose financial ledger, general payroll, corporate HR, and corporate double-entry accounting (delegated to integrated ERP like SAP/Oracle).
  • OOS-002: Standalone 3D CAD/BIM model viewer or direct 3D engineering authoring tools (delegated to native engineering design systems).
  • OOS-003: Native Critical Path Method (CPM) project scheduling and Gantt resource leveling (delegated to Primavera P6 / MS Project).
  • OOS-004: Enterprise-wide generic document management system (vendor documents are managed strictly in connection with project transactions and external DMS links).

Assumptions & open items

Assumed:

  • Multi-currency calculations will use standard project-level fixed exchange rates recorded in CurrencyExchangeRate rather than real-time forex streaming.
  • Project-specific numbering schemes (e.g. PO-PRJ-XXXX) will follow configurable string format templates with project-scoped sequential integer auto-increment counters.
  • Mobile warehouse and field workflows will be delivered as an offline-tolerant responsive web application optimized for ruggedized handheld barcode scanners and tablets.
  • Default PO monetary approval thresholds ($50,000 / $250,000) are configured at tenant initiation and can be adjusted per project configuration.

Coverage notes

  • Functional requirements: 10 (with acceptance criteria: 10)
  • Open assumptions: 4 (unresolved/conflicted: 0)
  • Entities in data model: 44
  • Screens: 8, Roles: 8, Journeys: 3
Screen map
Sandbox
User journeys
EPC Business Materials Management — User Journeys
End-to-end operational narratives and exception workflows across engineering, procurement, logistics, warehousing, construction, and closeout governance.
1 Engineering MTO Ingest and Requisition Generation Engineering Lead / Material Coordinator critical weekly

Carlos, a lead material coordinator managing multi-discipline BOMs across major piping and structural work packages.

Goal: Import updated engineering MTOs, reconcile delta quantities against baseline, and generate requisitions for procurement.

Trigger: New MTO revision file exported from Aveva E3D design software.

Preconditions:
  • Project and discipline configurations are active.
  • Material master commodity catalog is loaded and mapped.
  1. 1 Engineering Lead / Material Coordinator Navigates to the MTO dropzone and uploads the latest revision CSV/Excel file. → File is uploaded and automated schema parsing begins. Engineering MTO Import & Delta Comparison
  2. 2 System Validates commodity codes against Material Master and calculates line-level deltas against previous baseline. → Delta comparison matrix displays added, removed, and modified item quantities. Engineering MTO Import & Delta Comparison
  3. 3 Engineering Lead / Material Coordinator Filters delta items by discipline and selects verified uncommitted lines for procurement. → Selected items are staged for requisition bundling. Engineering MTO Import & Delta Comparison
  4. 4 Engineering Lead / Material Coordinator Clicks Create Requisition, defines required-on-site dates, and adds technical requirements. → Material Requisition draft is generated with line-level MTO linkages. Engineering MTO Import & Delta Comparison
  5. 5 Engineering Lead / Material Coordinator Submits requisition for multi-tier engineering approval. → Requisition status transitions to pending approval and routes to Lead Buyer queue. Engineering MTO Import & Delta Comparison
Alternate path: In-line Commodity Code Correction at step 2
  1. Engineering Lead / Material Coordinator Selects unrecognized commodity code in the validation error grid and maps it to a standard catalog item. → Validation error clears and delta recalculates.
Error path: Fatal Schema or Missing Tag Halts Import at step 2
  1. System Detects missing mandatory engineering tags across multiple lines and halts import processing. → Detailed line-by-line error transmittal is displayed with download log option.
  2. Engineering Lead / Material Coordinator Aborts import session to request source file correction from the 3D modeling team. → Draft import session discarded without altering project baseline.
After the main path:
  • MTO revision delta is committed to the project baseline.
  • New Requisition draft is created and queued for procurement packaging.
  • Shortage forecasting engine recalculates balance.
FR-001 FR-002 FR-008 FR-010 Engineering MTO Import & Delta Comparison
2 Inquiry Packaging, Commercial Bid Evaluation, and PO Issuance Procurement Specialist / Buyer critical daily

Elena, a senior procurement buyer responsible for heavy machinery and piping procurement packages.

Goal: Package approved requisitions into RFQs, evaluate vendor bids, and issue purchase orders with monetary approval routing.

Trigger: Notification of approved material requisitions awaiting procurement.

Preconditions:
  • Material Requisition has achieved approved status.
  • Suppliers are qualified on the Approved Vendor List (AVL).
  1. 1 Procurement Specialist / Buyer Opens pending action queue and selects approved requisition lines for packaging. → Requisition items are loaded into the RFQ creation workbench. Role-Aware Operations Dashboard
  2. 2 Procurement Specialist / Buyer Selects qualified AVL suppliers, sets quotation due date, and publishes RFQ package. → RFQ inquiries are dispatched to supplier collaboration workspaces. Procurement & Commercial Bid Evaluation
  3. 3 Procurement Specialist / Buyer Opens Commercial Bid Evaluation once vendor quotes are submitted. → System displays multi-supplier bid comparison with normalized project currencies. Procurement & Commercial Bid Evaluation
  4. 4 Procurement Specialist / Buyer Records technical deviations, enters award rationale, and submits award recommendation. → Recommendation routes through monetary threshold approval workflow. Procurement & Commercial Bid Evaluation
  5. 5 System Validates executive authorization signatures and creates formal Purchase Order. → PO is issued with line-level traceability to original MTO items and transmittal sent to supplier. Procurement & Commercial Bid Evaluation
Alternate path: Sub-$50,000 Expedited Single Buyer Approval at step 4
  1. Procurement Specialist / Buyer Directly signs off low-value PO within authorized personal monetary threshold. → PO is instantly finalized without multi-tier management escalation.
Error path: Award Recommendation Rejected by Finance Approver at step 4
  1. System Routes PO > $250,000 to Finance Lead who rejects it citing unapproved commercial deviations. → PO reverts to evaluation draft with rejection notes logged.
  2. Procurement Specialist / Buyer Re-opens commercial evaluation to negotiate revised terms or select secondary bidder. → Updated evaluation is prepared for re-submission.
After the main path:
  • Purchase Order record is finalized with immutable PO lines.
  • BidEvaluation and AuditLog records are permanently written.
  • Supplier portal is updated with new PO transmittal.
FR-001 FR-003 FR-004 FR-010 Role-Aware Operations Dashboard Procurement & Commercial Bid Evaluation
3 Supplier Quoting, PO Acknowledgement, and Progress Updates Supplier Representative high daily

Marcus, a vendor account manager for an industrial valve supplier managing contracts and milestone transmittals.

Goal: Submit commercial quotations, acknowledge awarded POs, and upload fabrication milestone updates and document transmittals.

Trigger: Receipt of an RFQ inquiry or Purchase Order issuance transmittal.

Preconditions:
  • Supplier user is authenticated with organization-scoped portal credentials.
  • Supplier is linked to active project RFQs or POs.
  1. 1 Supplier Representative Logs into the isolated vendor portal and opens active RFQ inquiry. → RFQ item specifications and required delivery dates are displayed. Supplier Collaboration Portal
  2. 2 Supplier Representative Enters unit prices, lead times, commercial exceptions, and submits quotation. → Quote record is submitted to buyer evaluation register. Supplier Collaboration Portal
  3. 3 Supplier Representative Opens newly awarded Purchase Order and submits formal digital PO acknowledgement. → PO status updates to acknowledged in project ledger. Supplier Collaboration Portal
  4. 4 Supplier Representative Uploads required vendor technical data sheets and updates fabrication milestone progress. → VendorDocument transmittal is logged for engineering and expediting review. Supplier Collaboration Portal
  5. 5 Supplier Representative Submits formal Inspection Request upon completing shop fabrication. → Inspection request is queued for project Quality Inspector assignment. Supplier Collaboration Portal
Alternate path: Supplier Requests Clarification on RFQ Specification at step 1
  1. Supplier Representative Submits technical clarification note via RFQ inquiry panel. → Clarification request dispatched to Buyer and Material Coordinator.
Error path: Document Revision Rejected by Reviewer at step 4
  1. System Notifies supplier that submitted test procedure was rejected with Review Code 3 (Revise and Resubmit). → Document status changes to rejected with reviewer comments displayed.
  2. Supplier Representative Uploads corrected revision file referencing prior comments. → New document revision is submitted for secondary review.
After the main path:
  • Quotation and acknowledgement records are logged in supplier partition.
  • Vendor documents and milestone progress are linked to PO lineage.
  • Inspection request is active.
FR-003 FR-004 FR-010 Supplier Collaboration Portal
4 Quality Surveillance, Punch Listing, and Release for Shipment Expeditor & Quality Inspector high daily

Kenji, a quality surveillance inspector conducting factory witness testing and release audits.

Goal: Review vendor documents, inspect shop fabrication, record non-conformances, and issue Release for Shipment authorization.

Trigger: Inspection request received or expediting milestone approaching.

Preconditions:
  • Vendor documents have attained approved review status.
  • Inspection request is scheduled with supplier.
  1. 1 Expeditor & Quality Inspector Reviews expediting risk heatmap and opens pending inspection request. → Displays PO item specifications, test procedures, and previous punch items. Role-Aware Operations Dashboard
  2. 2 Expeditor & Quality Inspector Reviews full upstream lineage and document approval transmittals. → Confirms approved engineering test plans are linked to PO lines. Traceability Graph Explorer
  3. 3 Expeditor & Quality Inspector Conducts shop inspection, enters test findings, and logs punch list items. → InspectionRecord is created with associated test certificates. Traceability Graph Explorer
  4. 4 Expeditor & Quality Inspector Authorizes formal Release for Shipment and records certificate number. → release_for_shipment flag is set to true on linked PO lines. Traceability Graph Explorer
  5. 5 System Unlocks logistics shipment packaging workflow for logistics coordinators. → Consignment packing lists can now incorporate inspected PO lines. Traceability Graph Explorer
Alternate path: Quality Lead Formal Inspection Waiver at step 3
  1. Expeditor & Quality Inspector Applies standard commodity inspection waiver with attached justification. → Release for shipment is granted under waiver protocol.
Error path: Inspection Failure Due to Dimensional Non-Conformance at step 3
  1. Expeditor & Quality Inspector Logs critical non-conformance finding and rejects Release for Shipment. → InspectionRecord status set to failed; shipment gate locked.
  2. System Dispatches non-conformance notice to Supplier Portal and buyer queue. → Milestone exception flagged on project operations dashboard.
After the main path:
  • InspectionRecord is committed to immutable audit trail.
  • Release for shipment gate is validated.
  • Logistics shipment creation is unlocked.
FR-001 FR-004 FR-005 FR-010 Role-Aware Operations Dashboard Traceability Graph Explorer
5 Consignment Tracking, Site Goods Receipt, and OS&D Handling Logistics Coordinator & Warehouse Manager critical many times a day

Fatima, a site warehouse superintendent managing international transport intake and laydown yard bin allocations.

Goal: Track shipping consignments, verify incoming package contents, log OS&D exceptions, and commit items to storage bins.

Trigger: Physical arrival of transport consignment at site laydown yard.

Preconditions:
  • Shipment package has cleared customs and arrived at site address.
  • Laydown warehouse zones and storage bins are configured.
  1. 1 Logistics Coordinator & Warehouse Manager Opens expected deliveries register on a mobile ruggedized scanner. → Locates transport consignment and packing manifest. Warehouse Goods Receipt & OS&D Inspection
  2. 2 Logistics Coordinator & Warehouse Manager Scans package QR barcodes using mobile camera scanner. → System matches scanned packages against PO line items and manifest. Warehouse Goods Receipt & OS&D Inspection
  3. 3 Logistics Coordinator & Warehouse Manager Performs visual condition verification and confirms item counts and heat numbers. → Package verification checklist completed. Warehouse Goods Receipt & OS&D Inspection
  4. 4 Logistics Coordinator & Warehouse Manager Selects storage zone and assigns specific laydown bin number. → Physical location coordinates mapped to received inventory. Warehouse Goods Receipt & OS&D Inspection
  5. 5 Logistics Coordinator & Warehouse Manager Finalizes Goods Receipt Note and prints durable item barcode tags. → InventoryItem is created in Available status and MaterialMovement record is posted. Warehouse Goods Receipt & OS&D Inspection
Alternate path: Multi-PO Consolidated Consignment Intake at step 2
  1. Logistics Coordinator & Warehouse Manager Scans mixed-PO container and confirms separate package allocations across different purchase orders. → Individual PO lines are credited simultaneously under single receipt.
Error path: Damaged Crate Logged into Quarantine Hold at step 3
  1. Logistics Coordinator & Warehouse Manager Logs OS&D damaged exception, captures camera photos, and flags items as Quarantined. → Items are blocked from field reservation and assigned to quarantine laydown bay.
  2. System Triggers urgent OS&D notice to Buyer and updates shortage analytics with unreceived count. → Shortage alert surfaces on operations dashboard.
After the main path:
  • Physical inventory balances are incremented in available stock.
  • Immutable MaterialMovement ledger transaction is written.
  • Item heat tags are active for construction reservation.
FR-001 FR-005 FR-006 FR-008 FR-010 Warehouse Goods Receipt & OS&D Inspection Role-Aware Operations Dashboard
6 Work Package Material Reservation, Picking, and Mobile Field Issue Construction & Commissioning Lead critical many times a day

Tariq, a piping construction superintendent managing field installation teams and erection schedules.

Goal: Check material availability, reserve required items for work packages, and execute signed mobile field issues.

Trigger: Upcoming construction work package installation window.

Preconditions:
  • Work Package is defined and in active status.
  • Sufficient material stock exists in laydown warehouse.
  1. 1 Construction & Commissioning Lead Queries material availability for target Work Package WP-102. → Displays required vs available stock with zero critical shortage blockers. Construction Reservation & Mobile Material Issue
  2. 2 Construction & Commissioning Lead Adds required items to cart and submits reservation request. → Inventory items transition to Reserved status, preventing double allocation. Construction Reservation & Mobile Material Issue
  3. 3 Construction & Commissioning Lead Generates digital pick-list with bin location directions for warehouse crew. → Pick-list formatted in optimal warehouse retrieval sequence. Construction Reservation & Mobile Material Issue
  4. 4 Construction & Commissioning Lead Scans physical item heat tags and captures field receiver digital signature on mobile pad. → Sign-off image and scan verifications are captured. Construction Reservation & Mobile Material Issue
  5. 5 Construction & Commissioning Lead Commits the issue transaction. → IssueTransaction recorded, stock decremented, and shortage analytics updated. Construction Reservation & Mobile Material Issue
Alternate path: Offline Mobile Issue with Background Synchronization at step 4
  1. Construction & Commissioning Lead Scans tags and records signature while device is disconnected from site network. → Transaction payload cached securely in browser local storage.
  2. System Detects network reconnect and automatically syncs pending issue transactions to server. → Material movements committed with original offline timestamps.
Error path: Tag Scan Mismatch Halts Field Issue at step 4
  1. Construction & Commissioning Lead Scans heat tag of physically retrieved item that does not match reserved alloy specification. → System blocks transaction with red material mismatch warning.
  2. Construction & Commissioning Lead Returns incorrect item to bin and scans correct tagged item. → Validation clears and issue proceed button unlocks.
After the main path:
  • Physical inventory balance is decremented.
  • Immutable MaterialMovement of type issue is created.
  • Traceability graph reflects field installation milestone.
FR-001 FR-007 FR-008 FR-010 Construction Reservation & Mobile Material Issue
7 Project Closeout Reconciliation and Surplus Asset Disposition Project Controls Lead high monthly

Devin, a project controls manager responsible for capital expenditure closeout and surplus equipment recovery.

Goal: Reconcile total engineered materials against installed and remaining stock, and authorize surplus asset disposition.

Trigger: Subsystem commissioning milestone or overall project closeout phase.

Preconditions:
  • Work package installation activities are finalized.
  • All open purchase orders and shipments are closed.
  1. 1 Project Controls Lead Launches the project closeout reconciliation calculation engine. → System computes full matrix of Engineered vs Ordered vs Received vs Issued vs Scrap vs Remaining. Project Closeout & Surplus Reconciliation
  2. 2 Project Controls Lead Reviews discrepancy variances, scrap records, and unaccounted material deltas. → Identifies surplus bulk piping and unused tagged equipment. Project Closeout & Surplus Reconciliation
  3. 3 Project Controls Lead Assigns surplus disposition actions (transfer to sister project, return to vendor, or scrap sale). → Disposition action entries and inter-project transfer requisitions created. Project Closeout & Surplus Reconciliation
  4. 4 Project Controls Lead Submits reconciliation package for multi-stakeholder executive sign-off. → Closeout approval workflow routes to Project Director and Finance Controller. Project Closeout & Surplus Reconciliation
  5. 5 Project Controls Lead Exports signed, comprehensive closeout reconciliation audit dossier. → Tamper-evident closeout package generated in PDF and Excel formats. Project Closeout & Surplus Reconciliation
Alternate path: Direct Surplus Salvage Auction Routing at step 3
  1. Project Controls Lead Sets disposition action to local scrap auction with estimated recovery value. → Surplus line items marked for asset salvage liquidation.
Error path: Unaccounted Inventory Discrepancy Exceeds Tolerance at step 2
  1. System Flags unresolved discrepancy between issued and installed quantities exceeding 2% tolerance. → Closeout sign-off button locked with mandatory audit investigation required.
  2. Project Controls Lead Requests warehouse physical cycle count adjustment before re-running reconciliation. → Adjusting MaterialMovement record posted and reconciliation unlocked.
After the main path:
  • ReconciliationRecord is permanently finalized.
  • Surplus assets are transferred or liquidated.
  • Closeout audit dossier archived for project statutory retention.
FR-001 FR-008 FR-009 FR-010 Project Closeout & Surplus Reconciliation
8 Traceability Graph Exploration and Governance Audit Inspection Governance & Compliance Auditor normal rare

Sophia, an external quality and financial compliance auditor verifying chain-of-custody and anti-corruption controls.

Goal: Verify unbroken material lineage, inspect authorization thresholds, and export chronological tamper-evident audit logs.

Trigger: Periodic statutory audit or project compliance investigation.

Preconditions:
  • Auditor account has read-only compliance permissions across tenant entities.
  • Audit logs are actively maintained in append-only storage.
  1. 1 Governance & Compliance Auditor Inputs a specific pipe heat number into the global scan bar. → Interactive bidirectional lineage node diagram renders in under 3 seconds. Traceability Graph Explorer
  2. 2 Governance & Compliance Auditor Clicks individual nodes (MTO, RFQ, PO, Inspection, Receipt, Issue) to review actor signatures and timestamps. → Node Detail Inspector Drawer displays granular metadata and transmittal history. Traceability Graph Explorer
  3. 3 Governance & Compliance Auditor Navigates to operations dashboard to inspect monetary approval threshold governance. → Displays compliance KPI cards and approval escalation history. Role-Aware Operations Dashboard
  4. 4 Governance & Compliance Auditor Queries append-only audit trail filtered by entity type, user ID, and date range. → System returns chronological, unalterable AuditLog event stream.
  5. 5 Governance & Compliance Auditor Exports verifiable compliance audit package with full digital signatures. → Exported audit transmittal file downloaded.
Alternate path: Forward Lineage Tracing from Engineering MTO Revision at step 1
  1. Governance & Compliance Auditor Searches by MTO Revision ID to trace design items downstream into field installation nodes. → Graph maps all downstream purchase orders and installed work package tags.
Error path: Unlinked Orphan Entity Flagged during Audit at step 2
  1. Governance & Compliance Auditor Identifies an issue transaction missing linked release for shipment certificate. → Auditor flags entity and generates compliance exception finding report.
After the main path:
  • Audit query session is recorded in security logs.
  • Compliance verification report is exported.
FR-001 FR-003 FR-010 Traceability Graph Explorer Role-Aware Operations Dashboard
Coverage
Roles covered: Engineering Lead / Material Coordinator, Procurement Specialist / Buyer, Supplier Representative, Expeditor & Quality Inspector, Logistics Coordinator & Warehouse Manager, Construction & Commissioning Lead, Project Controls Lead, Governance & Compliance Auditor
FRs covered: FR-001, FR-002, FR-003, FR-004, FR-005, FR-006, FR-007, FR-008, FR-009, FR-010
  • Inter-project material surplus transfer execution journey could be further elaborated into a dedicated multi-tenant workflow.
  • Detailed multi-currency exchange rate revaluation batch process journey is not modeled as a standalone interactive user journey.
How to read
  • All roles, screen names, and functional requirement IDs strictly reflect verbatim identifiers from the locked specification.
  • Journeys 5 and 6 feature mobile field interactions and offline degradation mechanisms matching non-functional requirements.
  • Steps with screen = null represent backend export actions or dedicated API audit log queries lacking a distinct dedicated frontend screen.
Entities diagram
Sandbox
DB schema
Sandbox
Data models
Sandbox
Entities & DB (text)

Entity-relationship model for EPC Business Materials Management. Covers the complete bidirectional materials lifecycle from engineering MTO revisions, procurement RFQs and bid evaluations, supplier purchase orders, vendor document transmittals and shop inspections, multi-leg logistics consignments, laydown yard warehousing and OS&D quarantine, field work package reservations and mobile sign-off issues, through to real-time shortage forecasting, surplus reconciliation, and immutable audit governance.

Entities (47)
Tenant

Multi-tenant isolation boundary representing the client operating company or major joint venture.

  • name string

    Corporate entity or joint venture name

  • slug string
    unique

    Unique URL-friendly tenant key

User

Authentication identity and system actor across internal EPC disciplines and external supplier portals.

  • email string
    unique

    Unique user email address

  • full_name string

    Display name of the user

  • status string

    Account lifecycle status

UserProfile

User profile preferences, personal metadata, and locale settings.

  • first_name string
    nullable

    First name of the user

  • last_name string
    nullable

    Last or family name

  • avatar_url string
    nullable

    Profile picture storage URL

  • bio text
    nullable

    User biography or professional summary

  • timezone string
    nullable

    Preferred timezone identifier

Role

Role definition for RBAC governing operational access across disciplines.

  • name string

    Role identifier name e.g. Buyer, Expeditor, QualityInspector

  • description string
    nullable

    Summary of role duties and authority

Permission

Granular action verb permitted on a specific domain resource.

  • action string

    Allowed action verb

  • resource string

    Domain resource e.g. MTO, PurchaseOrder, InventoryItem

UserRole

Junction assigning users to roles with optional project-level scoping.

Project

Capital construction project entity under which engineering, procurement, and site activities occur.

  • code string

    Project code identifier e.g. PRJ-LNG-2026

  • name string

    Descriptive project name

  • base_currency string

    Base currency ISO code e.g. USD, EUR

  • status string

    Project lifecycle phase

  • start_date date
    nullable

    Official project kick-off date

  • end_date date
    nullable

    Target project commissioning date

Area

Physical, geographical, or process unit subdivision of a project (e.g. Train 1, Offsites).

  • code string

    Area code e.g. AREA-100

  • name string

    Descriptive area title

Discipline

Engineering discipline classification (Piping, Electrical, Civil, Instrumentation, Mechanical).

  • code string

    Discipline code e.g. PIPING, ELEC

  • name string

    Discipline full name

WorkPackage

Construction or installation work package (CWP/IWP) tying together engineering materials and field execution.

  • code string

    Work package code e.g. WP-PIP-101

  • name string

    Work package scope description

  • status string

    Execution status

Commodity

High-level material commodity family e.g. Ball Valves, Carbon Steel Pipe, Cable Trays.

  • code string

    Commodity category code e.g. VALVE-BALL

  • name string

    Commodity title

MaterialClass

Commodity sub-classification indicating rating, pressure class, or material grade.

  • class_name string

    Class name e.g. Class 1500 Flanged

Manufacturer

Approved equipment or commodity manufacturer / OEM.

  • name string

    Manufacturer legal trade name

  • country string
    nullable

    Country of origin ISO code

MaterialSpecification

Technical engineering specification standard governing material design and testing.

  • code string

    Specification standard code e.g. ASME-B16.34

  • description text
    nullable

    Detailed engineering specification text

Material

Catalog item in the Material Master catalog with standardized UOM and attributes.

  • code string

    Material catalog code, indexed

  • description string

    Full technical description

  • uom string

    Unit of measure e.g. EA, M, KG

  • material_type string

    Distinguishes tagged serialized assets from bulk items

MaterialTag

Unique engineered tag number identifier for serialized equipment and instruments.

  • tag_number string

    Engineered tag number e.g. 10-HV-0012

  • serial_number string
    nullable

    Manufacturer serial number

MTORevision

Material Take-Off revision snapshot imported from 3D CAD/model design tools.

  • revision_number string

    Revision identifier e.g. Rev A, Rev 0, Rev 1

  • source_system string
    nullable

    Source engineering software e.g. Aveva E3D, SmartPlant

  • status string

    Revision validation state

MTOItem

Individual engineered line item in an MTO revision specifying required design quantities.

  • quantity integer

    Engineered required base quantity

  • allowance_percentage integer

    Scrap or contingency allowance percentage

  • required_on_site_date date
    nullable

    Construction required on site need date

Requisition

Engineering material purchase requisition bundling MTO delta requirements for procurement.

  • requisition_number string

    Unique requisition number e.g. MR-PIP-001

  • status string

    Requisition approval state

  • required_date date
    nullable

    Target delivery milestone date

  • technical_requirements text
    nullable

    Summary of engineering scope and standards

RequisitionLine

Line-level requisition item maintaining direct lineage back to the originating MTO item.

  • quantity integer

    Requested procurement quantity

Supplier

Vendor or manufacturer on the Approved Vendor List (AVL) bidding on and supplying project materials.

  • supplier_code string

    Unique vendor identifier e.g. SUP-9001

  • name string

    Legal company name

  • qualification_status string

    Approved vendor list status

SupplierEvaluation

Vendor qualification and periodic QA performance evaluation scoring.

  • score integer

    Supplier capability score from 0 to 100

  • evaluation_date date

    Date of vendor evaluation

  • notes text
    nullable

    Evaluation comments and findings

RFQ

Request for Quotation procurement package issued to qualified suppliers.

  • rfq_number string

    RFQ package reference e.g. RFQ-PIP-004

  • title string

    Commercial inquiry package title

  • status string

    RFQ sourcing lifecycle stage

  • due_date datetime

    Supplier bid submission deadline

RFQBidder

Invited supplier participant in an RFQ inquiry package.

  • invited_at datetime

    Timestamp when invitation was dispatched

  • status string

    Supplier participation response state

Quote

Commercial and technical quotation submitted by a supplier in response to an RFQ.

  • quote_number string

    Supplier commercial offer reference

  • currency string

    Quotation ISO currency code e.g. USD, EUR

  • total_price integer

    Total quotation price in quoted currency

  • status string

    Quote evaluation status

QuoteLine

Line-item bid with pricing, lead time, and technical deviations.

  • unit_price integer

    Offered unit price

  • offered_lead_time_days integer

    Promised manufacturing lead time in days

  • technical_deviation text
    nullable

    Recorded engineering deviations or comments

BidEvaluation

Technical and commercial bid evaluation summary with award recommendation and threshold sign-offs.

  • recommendation_rationale text

    Technical and commercial award justification

  • status string

    Award approval decision state

PurchaseOrder

Contractual commitment issued to a supplier for material fabrication and delivery.

  • po_number string

    Purchase order number e.g. PO-88001

  • currency string

    PO commercial currency ISO code

  • total_amount integer

    Total contractual value

  • incoterms string
    nullable

    Incoterms e.g. FOB, CIF, DDP

  • payment_terms string
    nullable

    Commercial payment terms e.g. Net 45

  • status string

    PO lifecycle status

POLine

Individual line on a purchase order, maintaining upstream lineage to requisition and MTO item.

  • quantity integer

    Contracted purchase quantity

  • unit_price integer

    Agreed line unit price

  • promised_delivery_date date
    nullable

    Supplier promised contractual ex-works date

VendorDocument

Technical drawing, calculation, or quality certificate submitted by supplier against a PO.

  • document_number string

    Vendor document register number

  • document_type string

    Document classification

  • revision_number string

    Document revision code e.g. Rev 1

  • status string

    Engineering review status

  • submission_date datetime

    Transmittal submission timestamp

  • file_url string
    nullable

    Blob storage URL or external DMS link

DocumentReview

Engineering markup and review decision on vendor transmittals using EPC approval codes.

  • approval_code string

    Standard EPC review disposition code

  • comments text
    nullable

    Engineering review markup comments

  • reviewed_at datetime

    Review completion timestamp

InspectionRequest

Vendor shop inspection notification or factory test gate notification.

  • inspection_type string

    Inspection type

  • proposed_date date

    Requested shop surveillance date

  • status string

    Inspection notification status

InspectionRecord

Quality inspection surveillance result, punch list items, and formal release for shipment.

  • result string

    Surveillance result verdict

  • punch_list_items text
    nullable

    Punch list non-conformities and remediation items

  • release_for_shipment boolean

    Whether formal Release for Shipment is granted

  • certificate_number string
    nullable

    Quality certificate or RFS release number

Shipment

International multi-leg logistics consignment transporting vendor packages to project site.

  • shipment_number string

    Consignment identifier e.g. SHP-0044

  • freight_forwarder string
    nullable

    Logistics service provider name

  • transport_mode string

    Primary transit mode

  • etd date
    nullable

    Estimated time of departure

  • eta date
    nullable

    Estimated time of arrival at destination

  • actual_arrival_date date
    nullable

    Actual arrival date at site laydown

  • status string

    Logistics transit state

ShipmentPackage

Physical crate, container, or pallet mapped to specific PO lines within a consignment.

  • package_number string

    Crate or pallet barcode tag

  • quantity integer

    Packed quantity in this container

  • weight_kg integer
    nullable

    Gross weight in kilograms

Warehouse

Project storage facility, laydown yard, or off-site staging depot.

  • code string

    Warehouse/Yard code e.g. WHS-MAIN, YARD-02

  • name string

    Facility name e.g. Main Laydown Yard

  • location_address string
    nullable

    Physical site coordinates or address

StorageLocation

Specific laydown zone, rack, bay, or bin location within a warehouse.

  • zone string

    Zone code e.g. Zone A, Rack 04

  • bin_number string

    Bin identifier e.g. BIN-A4-12

InventoryItem

Physical on-hand inventory stock item located at a bin, tracking heat number and status.

  • quantity integer

    Current physical stock quantity

  • serial_number string
    nullable

    Item serial number if tagged

  • heat_number string
    nullable

    Mill test certificate heat or melt batch number

  • status string

    Inventory stock state

  • received_date datetime

    Goods receipt timestamp

MaterialMovement

Append-only immutable stock ledger transaction recording receipts, transfers, and issues.

  • movement_type string

    Material movement category

  • quantity integer

    Transacted quantity

  • reference_document_type string
    nullable

    Polymorphic reference entity type e.g. Shipment, Reservation, OSD

  • reference_document_id integer
    nullable

    Polymorphic reference entity integer ID

  • timestamp datetime

    Immutable ledger timestamp

Reservation

Allocation of warehouse stock against a specific Work Package before field installation.

  • quantity integer

    Reserved quantity allocated to package

  • status string

    Reservation lifecycle status

IssueTransaction

Field material handover record with mobile digital sign-off signature.

  • received_by_name string

    Field construction recipient name

  • signature_image_url string
    nullable

    Captured digital signature image blob URL

  • quantity integer

    Physical issued quantity

  • issued_at datetime

    Transaction completion timestamp

ShortageRecord

Live computed shortage deficit comparing MTO demand against orders and available stock.

  • required_quantity integer

    Engineering demand quantity

  • available_quantity integer

    Available unreserved physical stock

  • shortage_quantity integer

    Calculated shortage quantity deficit

  • required_date date
    nullable

    Target construction need date

  • status string

    Shortage resolution status

ReconciliationRecord

Closeout multi-variable reconciliation matrix and surplus disposition record.

  • engineered_quantity integer

    Total approved MTO quantity

  • purchased_quantity integer

    Total PO ordered quantity

  • shipped_quantity integer

    Total supplier shipped quantity

  • received_quantity integer

    Total yard received quantity

  • issued_quantity integer

    Total field issued quantity

  • damaged_quantity integer

    Total OS&D scrap/damaged quantity

  • surplus_quantity integer

    Remaining physical surplus inventory

  • disposition_action string

    Closeout disposition action

CurrencyExchangeRate

Baseline fixed exchange rate tables for project multi-currency normalization.

  • from_currency string

    Source ISO currency code e.g. EUR

  • to_currency string

    Target base ISO currency code e.g. USD

  • rate_multiplier integer

    Fixed-point exchange multiplier (e.g. 10850 for 1.0850)

  • effective_date date

    Rate effective date

AuditLog

Immutable append-only audit trail capturing sensitive transitions, approvals, and deletions.

  • entity_type string

    Target modified entity class name

  • entity_id integer

    Integer or UUID identifier of modified record

  • action string

    Audit action verb e.g. STATUS_CHANGE, APPROVAL

  • previous_values json
    nullable

    Serialized previous field values

  • new_values json
    nullable

    Serialized new field values

  • ip_address string
    nullable

    Client IP address

Webhook

Auto-added from feature tags.

  • url string
    nullable
  • event_types_json json
    nullable
  • secret string
    nullable
  • last_sent_at datetime
    nullable
  • enabled boolean
    nullable
FeatureFlag

Auto-added from feature tags.

  • key string
    unique
  • enabled boolean
  • rolled_out_to_json json
    nullable
  • description text
    nullable
Relationships (91)
From Type To Description
user
one-to-one
user_profile One User has one UserProfile profile record.
tenant
one-to-many
user A Tenant has many Users.
supplier
one-to-many
user A Supplier organization has many external Supplier Users.
tenant
one-to-many
role A Tenant defines many Roles.
role
one-to-many
permission A Role has many Permissions.
user
one-to-many
user_role A User has many assigned UserRoles.
role
one-to-many
user_role A Role is assigned to many UserRoles.
project
one-to-many
user_role A Project scopes specific UserRoles.
tenant
one-to-many
project A Tenant runs many capital Projects.
project
one-to-many
area A Project is divided into many Areas.
tenant
one-to-many
discipline A Tenant maintains standard Disciplines.
project
one-to-many
work_package A Project contains many WorkPackages.
area
one-to-many
work_package An Area groups many WorkPackages.
discipline
one-to-many
work_package A Discipline organizes many WorkPackages.
tenant
one-to-many
commodity A Tenant maintains standard Commodities.
commodity
one-to-many
material_class A Commodity contains many MaterialClasses.
tenant
one-to-many
manufacturer A Tenant registers approved Manufacturers.
tenant
one-to-many
material_specification A Tenant defines MaterialSpecifications.
tenant
one-to-many
material A Tenant manages master catalog Materials.
project
one-to-many
material A Project can define project-specific Materials.
material_class
one-to-many
material A MaterialClass classifies many Materials.
material_specification
one-to-many
material A MaterialSpecification governs many Materials.
manufacturer
one-to-many
material A Manufacturer produces many Materials.
material
one-to-many
material_tag A Material definition has many physical MaterialTags.
project
one-to-many
material_tag A Project tracks many MaterialTags.
project
one-to-many
mto_revision A Project tracks many MTORevisions.
mto_revision
one-to-many
mto_item An MTORevision contains many MTOItems.
material
one-to-many
mto_item A Material is referenced by many MTOItems.
work_package
one-to-many
mto_item A WorkPackage requires many MTOItems.
project
one-to-many
requisition A Project generates many procurement Requisitions.
user
one-to-many
requisition A User authors many Requisitions.
requisition
one-to-many
requisition_line A Requisition contains many RequisitionLines.
mto_item
one-to-many
requisition_line An MTOItem is procured through many RequisitionLines.
material
one-to-many
requisition_line A Material is requisitioned via RequisitionLines.
tenant
one-to-many
supplier A Tenant maintains approved Suppliers on its AVL.
supplier
one-to-many
supplier_evaluation A Supplier undergoes many SupplierEvaluations.
project
one-to-many
supplier_evaluation A Project records SupplierEvaluations.
user
one-to-many
supplier_evaluation A User conducts many SupplierEvaluations.
project
one-to-many
rfq A Project issues many RFQs.
requisition
one-to-many
rfq A Requisition is sourced through RFQs.
rfq
one-to-many
rfq_bidder An RFQ invites many RFQBidders.
supplier
one-to-many
rfq_bidder A Supplier is invited as an RFQBidder across packages.
rfq
one-to-many
quote An RFQ receives Quotes from bidders.
supplier
one-to-many
quote A Supplier submits many commercial Quotes.
quote
one-to-many
quote_line A Quote contains many QuoteLines.
requisition_line
one-to-many
quote_line A RequisitionLine is priced by QuoteLines.
rfq
one-to-many
bid_evaluation An RFQ has BidEvaluations.
quote
one-to-many
bid_evaluation A Quote is selected in a BidEvaluation.
user
one-to-many
bid_evaluation A Buyer evaluates bids in BidEvaluations.
user
one-to-many
bid_evaluation An Approver authorizes BidEvaluations.
project
one-to-many
purchase_order A Project issues many PurchaseOrders.
supplier
one-to-many
purchase_order A Supplier fulfills many PurchaseOrders.
quote
one-to-many
purchase_order A Quote results in a PurchaseOrder award.
purchase_order
one-to-many
po_line A PurchaseOrder contains many POLines.
requisition_line
one-to-many
po_line A RequisitionLine is committed in POLines.
material
one-to-many
po_line A Material is purchased via POLines.
purchase_order
one-to-many
vendor_document A PurchaseOrder requires many VendorDocuments.
supplier
one-to-many
vendor_document A Supplier submits many VendorDocuments.
vendor_document
one-to-many
document_review A VendorDocument undergoes DocumentReviews.
user
one-to-many
document_review An Engineer completes DocumentReviews.
purchase_order
one-to-many
inspection_request A PurchaseOrder triggers InspectionRequests.
supplier
one-to-many
inspection_request A Supplier requests InspectionRequests.
inspection_request
one-to-many
inspection_record An InspectionRequest generates InspectionRecords.
user
one-to-many
inspection_record A Quality Inspector records InspectionRecords.
project
one-to-many
shipment A Project receives logistics Shipments.
supplier
one-to-many
shipment A Supplier dispatches Shipments.
shipment
one-to-many
shipment_package A Shipment contains many ShipmentPackages.
po_line
one-to-many
shipment_package A POLine is packed into ShipmentPackages.
project
one-to-many
warehouse A Project operates Warehouses and laydown yards.
warehouse
one-to-many
storage_location A Warehouse contains many StorageLocations (bins).
material
one-to-many
inventory_item A Material has physical InventoryItems.
warehouse
one-to-many
inventory_item A Warehouse holds InventoryItems.
storage_location
one-to-many
inventory_item A StorageLocation houses InventoryItems.
po_line
one-to-many
inventory_item A POLine generates received InventoryItems.
inventory_item
one-to-many
material_movement An InventoryItem records immutable MaterialMovements.
user
one-to-many
material_movement A User performs MaterialMovements.
storage_location
one-to-many
material_movement A StorageLocation is the origin of MaterialMovements.
storage_location
one-to-many
material_movement A StorageLocation is the destination of MaterialMovements.
work_package
one-to-many
reservation A WorkPackage holds material Reservations.
inventory_item
one-to-many
reservation An InventoryItem is allocated in Reservations.
user
one-to-many
reservation A Construction Lead initiates Reservations.
reservation
one-to-many
issue_transaction A Reservation is fulfilled by IssueTransactions.
user
one-to-many
issue_transaction A Warehouse Operator executes IssueTransactions.
project
one-to-many
shortage_record A Project monitors ShortageRecords.
work_package
one-to-many
shortage_record A WorkPackage tracks ShortageRecords.
material
one-to-many
shortage_record A Material has calculated ShortageRecords.
project
one-to-many
reconciliation_record A Project maintains closeout ReconciliationRecords.
material
one-to-many
reconciliation_record A Material is reconciled in ReconciliationRecords.
tenant
one-to-many
currency_exchange_rate A Tenant defines CurrencyExchangeRates.
tenant
one-to-many
audit_log A Tenant maintains immutable AuditLogs.
user
one-to-many
audit_log A User triggers logged events in AuditLogs.
Database tables (47)
tenants
  • id bigInteger
    unique
  • name string
  • slug string
    unique
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
users
  • id bigInteger
    unique
  • email string
    unique
  • full_name string
  • status string
  • tenant_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
user_profiles
  • id bigInteger
    unique
  • first_name string
    nullable
  • last_name string
    nullable
  • avatar_url string
    nullable
  • bio text
    nullable
  • timezone string
    nullable
  • tenant_id bigInteger
    unique
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
roles
  • id bigInteger
    unique
  • name string
  • description string
    nullable
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
permissions
  • id bigInteger
    unique
  • action string
  • resource string
  • role_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
user_roles
  • id bigInteger
    unique
  • user_id bigInteger
    nullable
  • role_id bigInteger
    nullable
  • project_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
projects
  • id bigInteger
    unique
  • code string
  • name string
  • base_currency string
  • status string
  • start_date date
    nullable
  • end_date date
    nullable
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
areas
  • id bigInteger
    unique
  • code string
  • name string
  • project_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
disciplines
  • id bigInteger
    unique
  • code string
  • name string
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
work_packages
  • id bigInteger
    unique
  • code string
  • name string
  • status string
  • project_id bigInteger
    nullable
  • area_id bigInteger
    nullable
  • discipline_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
commodities
  • id bigInteger
    unique
  • code string
  • name string
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
material_classes
  • id bigInteger
    unique
  • class_name string
  • commodity_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
manufacturers
  • id bigInteger
    unique
  • name string
  • country string
    nullable
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
material_specifications
  • id bigInteger
    unique
  • code string
  • description text
    nullable
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
materials
  • id bigInteger
    unique
  • code string
  • description string
  • uom string
  • material_type string
  • tenant_id bigInteger
    nullable
  • project_id bigInteger
    nullable
  • material_class_id bigInteger
    nullable
  • specification_id bigInteger
    nullable
  • manufacturer_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
material_tags
  • id bigInteger
    unique
  • tag_number string
  • serial_number string
    nullable
  • material_id bigInteger
    nullable
  • project_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
mto_revisions
  • id bigInteger
    unique
  • revision_number string
  • source_system string
    nullable
  • status string
  • project_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
mto_items
  • id bigInteger
    unique
  • quantity integer
  • allowance_percentage integer
  • required_on_site_date date
    nullable
  • mto_revision_id bigInteger
    nullable
  • material_id bigInteger
    nullable
  • work_package_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
requisitions
  • id bigInteger
    unique
  • requisition_number string
  • status string
  • required_date date
    nullable
  • technical_requirements text
    nullable
  • project_id bigInteger
    nullable
  • created_by_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
requisition_lines
  • id bigInteger
    unique
  • quantity integer
  • requisition_id bigInteger
    nullable
  • mto_item_id bigInteger
    nullable
  • material_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
suppliers
  • id bigInteger
    unique
  • supplier_code string
  • name string
  • qualification_status string
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
supplier_evaluations
  • id bigInteger
    unique
  • score integer
  • evaluation_date date
  • notes text
    nullable
  • supplier_id bigInteger
    nullable
  • project_id bigInteger
    nullable
  • evaluator_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
rfqs
  • id bigInteger
    unique
  • rfq_number string
  • title string
  • status string
  • due_date datetime
  • project_id bigInteger
    nullable
  • requisition_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
rfq_bidders
  • id bigInteger
    unique
  • invited_at datetime
  • status string
  • rfq_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
quotes
  • id bigInteger
    unique
  • quote_number string
  • currency string
  • total_price integer
  • status string
  • rfq_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
quote_lines
  • id bigInteger
    unique
  • unit_price integer
  • offered_lead_time_days integer
  • technical_deviation text
    nullable
  • quote_id bigInteger
    nullable
  • requisition_line_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
bid_evaluations
  • id bigInteger
    unique
  • recommendation_rationale text
  • status string
  • rfq_id bigInteger
    nullable
  • awarded_quote_id bigInteger
    nullable
  • evaluator_user_id bigInteger
    nullable
  • approved_by_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
purchase_orders
  • id bigInteger
    unique
  • po_number string
  • currency string
  • total_amount integer
  • incoterms string
    nullable
  • payment_terms string
    nullable
  • status string
  • project_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • quote_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
po_lines
  • id bigInteger
    unique
  • quantity integer
  • unit_price integer
  • promised_delivery_date date
    nullable
  • purchase_order_id bigInteger
    nullable
  • requisition_line_id bigInteger
    nullable
  • material_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
vendor_documents
  • id bigInteger
    unique
  • document_number string
  • document_type string
  • revision_number string
  • status string
  • submission_date datetime
  • file_url string
    nullable
  • purchase_order_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
document_reviews
  • id bigInteger
    unique
  • approval_code string
  • comments text
    nullable
  • reviewed_at datetime
  • vendor_document_id bigInteger
    nullable
  • reviewer_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
inspection_requests
  • id bigInteger
    unique
  • inspection_type string
  • proposed_date date
  • status string
  • purchase_order_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
inspection_records
  • id bigInteger
    unique
  • result string
  • punch_list_items text
    nullable
  • release_for_shipment boolean
  • certificate_number string
    nullable
  • inspection_request_id bigInteger
    nullable
  • inspector_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
shipments
  • id bigInteger
    unique
  • shipment_number string
  • freight_forwarder string
    nullable
  • transport_mode string
  • etd date
    nullable
  • eta date
    nullable
  • actual_arrival_date date
    nullable
  • status string
  • project_id bigInteger
    nullable
  • supplier_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
shipment_packages
  • id bigInteger
    unique
  • package_number string
  • quantity integer
  • weight_kg integer
    nullable
  • shipment_id bigInteger
    nullable
  • po_line_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
warehouses
  • id bigInteger
    unique
  • code string
  • name string
  • location_address string
    nullable
  • project_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
storage_locations
  • id bigInteger
    unique
  • zone string
  • bin_number string
  • warehouse_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
inventory_items
  • id bigInteger
    unique
  • quantity integer
  • serial_number string
    nullable
  • heat_number string
    nullable
  • status string
  • received_date datetime
  • material_id bigInteger
    nullable
  • warehouse_id bigInteger
    nullable
  • storage_location_id bigInteger
    nullable
  • po_line_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
material_movements
  • id bigInteger
    unique
  • movement_type string
  • quantity integer
  • reference_document_type string
    nullable
  • reference_document_id integer
    nullable
  • timestamp datetime
  • inventory_item_id bigInteger
    nullable
  • actor_user_id bigInteger
    nullable
  • from_location_id bigInteger
    nullable
  • to_location_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
reservations
  • id bigInteger
    unique
  • quantity integer
  • status string
  • work_package_id bigInteger
    nullable
  • inventory_item_id bigInteger
    nullable
  • reserved_by_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
issue_transactions
  • id bigInteger
    unique
  • received_by_name string
  • signature_image_url string
    nullable
  • quantity integer
  • issued_at datetime
  • reservation_id bigInteger
    nullable
  • issued_by_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
shortage_records
  • id bigInteger
    unique
  • required_quantity integer
  • available_quantity integer
  • shortage_quantity integer
  • required_date date
    nullable
  • status string
  • project_id bigInteger
    nullable
  • work_package_id bigInteger
    nullable
  • material_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
reconciliation_records
  • id bigInteger
    unique
  • engineered_quantity integer
  • purchased_quantity integer
  • shipped_quantity integer
  • received_quantity integer
  • issued_quantity integer
  • damaged_quantity integer
  • surplus_quantity integer
  • disposition_action string
  • project_id bigInteger
    nullable
  • material_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
currency_exchange_rates
  • id bigInteger
    unique
  • from_currency string
  • to_currency string
  • rate_multiplier integer
  • effective_date date
  • tenant_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
audit_logs
  • id bigInteger
    unique
  • entity_type string
  • entity_id integer
  • action string
  • previous_values json
    nullable
  • new_values json
    nullable
  • ip_address string
    nullable
  • tenant_id bigInteger
    nullable
  • actor_user_id bigInteger
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
webhooks
  • id bigInteger
    unique
  • url string
    nullable
  • event_types_json json
    nullable
  • secret string
    nullable
  • last_sent_at datetime
    nullable
  • enabled boolean
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable
feature_flags
  • id bigInteger
    unique
  • key string
    unique
  • enabled boolean
  • rolled_out_to_json json
    nullable
  • description text
    nullable
  • created_at timestamp
    nullable
  • updated_at timestamp
    nullable