System Architecture

Forge is built as a modular reasoning engine. Each layer is responsible for a distinct phase of the pipeline — from document ingestion to net financial exposure.

Core Ontology

The foundational data model separates three distinct concepts that together power the reasoning engine:

SystemObservation (Signal)

An event extracted from a document that changes project state. Carries responsibility attribution (Contractor / Owner / Third Party / Force Majeure) and delay estimate. Requires triage.

ProjectConstraint (Rule)

A governing rule extracted from contract documents. Typed via ProjectConstraintType: LIQUIDATED_DAMAGES, MILESTONE_PENALTY, WEATHER_ENTITLEMENT, NOTICE_WINDOW, etc. Defines how signals translate into financial consequence.

SystemActivity (Schedule)

A node in the CPM network with planned dates, float, and WBS context. Signals are linked to activities via semantic + composite scoring. Constraints are scoped to activities or milestones.

Reasoning Services (NestJS)

IngestionModule

Parses unstructured documents (PDF, XML) and runs the LLM extraction pipeline. Separates Signals from Constraints. Pre-computes sensitivity financial exposure at write time to eliminate recalculation at query time.

ConstraintResolverService

Implements hierarchical constraint lookup: Activity-level → Milestone-level → Environment-level. Ensures penalty rates are applied only when the correct typed rule is triggered. Mirrors real construction contract precedence logic.

ResolutionService (CPM Engine)

Executes a true Critical Path Method (CPM) simulation the moment a signal is resolved. Calculates exact float deltas, determines if the critical path shifted, and outputs the new projected project end date.

ConcurrencyResolverService

Projects delay signals as DelayInterval objects (start/end anchored to the activity window). Runs a sweep-line algorithm to detect overlapping intervals and compute NetDelayAttribution: contractor, owner, concurrent, and unknown days.

FinancialsModule (Analytical Layer)

The ground truth for risk analysis. Hosts the FinancialImpactCalculator and UrgencyCalculator. By keeping analytical logic in this low-level module, we ensure a unidirectional dependency graph across all reasoning services, eliminating circular references and initialization errors.

InsightService

Aggregates all observation-level impact into the ExposureSummary. Now implements Urgency-First Prioritization, ensuring the most time-sensitive risks (Act Now) are surfaced to the executive dashboard regardless of confirmed cost.

MilestoneRiskAccumulatorService

Traverses the CPM dependency graph upstream from each delivery milestone, accumulating risk pressure from every observation on the path. Outputs MilestoneRiskState — status, top drivers, impacted paths — and now ranks drivers by Urgency Tier before contribution score.

Vector Memory Layer (pgvector)

Stores observations, activities, and constraints as high-dimensional embeddings. Enables semantic duplicate detection, activity matching, and constraint similarity search — while keeping all financial calculations strictly deterministic.

Schedule Logic Validation

Construction schedules are treated as directed graphs. Two critical validations run on every upload:

Cycle Detection: DFS Topological Sort detects circular logic loops (A → B → A) that would corrupt critical path calculation.
CPM Calculation:Full Forward/Backward pass computes Total Float, Early/Late Start/Finish dates independent of the source file's metadata.