Precon System

Summary

Precon is the bid-opportunity workflow: source intake, portal acquisition, document publication, solicitation understanding, sizing, RFI drafting, estimator workspace, bid decision, and submitted-bid capacity tracking. It is document-heavy, stateful, and repair-oriented, so the thread starts from the operator workspace rather than from individual processing packages.

The module's job is to help preconstruction operators find and understand opportunities while keeping evidence, chronology, document precedence, repairability, and estimator decisions visible.

Module At A Glance

Reader Question

How does the platform move an opportunity from external source evidence into an estimator-ready workspace, and how does it recover when documents, portals, sizing signals, or communications are incomplete?

Surface Or Workflow

The entry surfaces are the precon console, opportunity detail, review workspace, estimator workspace, portal review, document explorer, RFI workspace, diagnostics, and submitted-bids views. Operators need to understand what the opportunity is, which documents are authoritative, what trade/sizing signals exist, who needs to act, and which repair paths are available.

Engineers enter through route families, processing jobs, portal acquisition packages, sizing services, RFI drafting, planning/capacity services, tests, and runbooks.

Architecture Rationale

Precon is not one document pipeline because the workflow makes several evidence commitments: opportunity identity, portal access, document precedence, sizing evidence, RFI candidates, estimator decision, and capacity feedback. Each commitment needs its own repair path.

Lifecycle

The lifecycle starts with opportunity intake. Mailbox, portal, and source signals become candidate opportunities and solicitations. Portal and document acquisition then decide where authoritative files live, what changed, and which documents should be published or indexed.

Processing services build runtime tasks and evidence. Sizing services extract trade signals, apply heuristics and guardrails, and produce evidence that an estimator can inspect. RFI drafting uses document context and recipient selection to propose communication without making the model or draft the final authority.

The estimator workspace pulls these strands together: opportunity overview, documents, chronology, solicitations, RFI candidates, sizing evidence, planning state, bid decisions, and capacity. Repair jobs and runbooks exist because external portals, documents, and source messages regularly produce ambiguous or incomplete state.

Child Threads

Implementation Boundaries

app/web/app/precon and app/api/precon expose the module surfaces. services/precon owns correspondence, portals, processing, sizing, planning, RFI, review, diagnostics, and documents. jobs/precon owns thin automation entrypoints for repeatable ingestion, replay, repair, publication, and reporting work. tests/precon and runbooks under docs/runbooks should be linked directly as child threads mature.

Tradeoffs

Precon has many packages because the workflow has many distinct operational questions. Collapsing them into one "opportunity service" would hide the differences between source intake, portal state, document precedence, sizing evidence, RFI drafting, and estimator action. The recursive thread model lets the first-level page stay readable while child threads own the deeper implementation families.

Visual

The current visual is a graph neighborhood. The intended first-level visual is a precon opportunity lifecycle map: intake, portal/document acquisition, processing, sizing/RFI, estimator workspace, bid outcome, capacity feedback, and repair loops.

Operator Narrative

Precon is the domain where document volume, external portals, deadlines, estimate context, and human judgment collide. The operator is not just asking "did we receive a file?" They are asking what opportunity this is, which source is authoritative, which documents matter, whether sizing evidence is good enough, which questions need to become RFIs, and whether the company should bid. The platform has to preserve enough context for those decisions to be made repeatedly and reviewed later.

The estimator workspace is therefore the right conceptual center. It composes source intake, opportunity identity, correspondence, portal acquisition, document publication, sizing signals, RFI candidates, notes, assignments, submitted-bid history, and capacity. Each of those pieces has its own internal workflow, but the operator needs a coherent view of the opportunity.

This is why precon cannot be modeled as a single document pipeline. A document download can succeed while opportunity identity is still ambiguous. Sizing can produce evidence while document precedence is still under review. An RFI draft can be useful while still requiring human editing. A portal may be accessible but not authoritative. The module needs state for each commitment rather than one global "processed" flag.

Evidence Commitments

Precon makes several commitments as an opportunity matures. First, it commits to source identity: which solicitation, message, portal link, or correspondence belongs to which opportunity. Second, it commits to document access and publication: which files are available, which ones are relevant, and which version should be treated as current evidence. Third, it commits to sizing and trade evidence: what the documents imply about scope, quantities, risk, and confidence. Fourth, it commits to communication: what questions need to be asked and who should receive them. Finally, it commits to bid and capacity state.

Each commitment needs a repair path. Source identity can be merged or reassigned. Portal access can be retried or manually repaired. Document publication can be corrected when precedence or classification is wrong. Sizing evidence can be refreshed, compared, or flagged. RFI drafts can be edited. Capacity and bid state can be updated as the team's plan changes. The architecture has many packages because these commitments are genuinely different.

AI And Human Judgment

Precon uses model-assisted and OCR-adjacent workflows, but the architecture should never treat generated output as the final authority. Models can help classify documents, extract sizing signals, summarize evidence, or propose RFI language. Services and operators decide what is accepted. The workspace should show evidence, citations, confidence, and editable drafts rather than hiding the model behind a final answer.

This posture is especially important for sizing. A sizing conclusion without evidence is not useful to an estimator. The platform should preserve which documents were considered, which signals were extracted, which precedence rule or heuristic applied, and where guardrails or quality checks raised concern. That lets AI speed up evidence gathering without replacing estimator judgment.

RFI drafting follows the same rule. Generated draft language can accelerate communication, but recipient selection, final wording, and send decisions remain human-owned. The model can propose; the platform should preserve source questions, draft state, edits, and final communication context.

Operations And Repair

Precon's operational risk is that external systems are unreliable and source state changes often. Mailboxes move, portal links expire, documents are replaced, project names vary, and deadlines shift. The module therefore needs daily operations, repair jobs, replay paths, diagnostics, and runbooks as part of the design, not as an afterthought.

The runbooks and jobs are valuable because they encode repeated recovery paths. If mailbox intake fails, support should know how to replay or inspect state. If portal acquisition is incomplete, operators should see acquisition status and repair options. If sizing evidence is stale, the platform should support refresh or rebuild. If submitted-bid capacity needs correction, it should flow through planning services rather than a spreadsheet.

Precon is a good example of recursive documentation. The first-level system post explains the opportunity lifecycle. Child threads own intake, portal acquisition, publication methodology, sizing, RFI drafting, estimator workspace, submitted bids, and operations. Reference posts and tests then explain the implementation families behind those workflows.

Source Evidence

  • docs/domains/preconstruction.md
  • app/web/app/precon
  • app/api/precon
  • services/precon
  • jobs/precon
  • tests/precon
  • docs/runbooks/precon-daily-operations.md
  • docs/runbooks/precon-mailbox-failures.md
  • docs/runbooks/precon-repair-jobs.md