READ ME FIRST — Construction Bidding Platform

Welcome. This document is for anyone encountering this project for the very first time — especially people from the construction world, not software developers. It explains what this software is, who it's for, how to see it running, and how to live with it day to day. No jargon, no code. Where a technical term is unavoidable, it's explained in the glossary at the end.

Reading time: about 10–15 minutes.

---

1. Who this is for

This project serves two groups of people in the construction industry:

General contractors (GCs) — specifically the estimators and preconstruction teams who put bids together. These are the people who take a set of drawings for a new building, break the work into pieces (concrete, plumbing, electrical, and so on), send those pieces out to subcontractors for pricing, collect the prices back, and assemble the overall bid — all against a hard deadline. This platform is built for them first.

Subcontractors and suppliers — the companies that receive those invitations and price the work. They are usually busy, often on a job site, often on a phone, and they do not want to create yet another account on yet another software portal. This platform is designed so they never have to.

There is a third audience: the person (maybe you) who has been asked to evaluate this software, run it, or look after it for one of the groups above. This document is written mainly for you.

---

2. What it does

In plain terms: this software replaces the email-and-spreadsheet chaos of construction bidding with one organized system.

Today, a typical general contractor sends out bid invitations by email, tracks who responded in a spreadsheet, fields phone calls about drawing changes, and compares subcontractor prices by hand — often discovering too late that the cheapest bidder left something out.

This platform keeps the whole process in one place:

• The GC uploads the project drawings and specifications once.
• The GC breaks the project into bid packages (one per trade, typically) and invites subcontractors by email — dozens at a time.
• Each subcontractor gets a private web link. They tap it, see the drawings, and answer "we'll bid" or "no thanks" — no account, no password, no sign-up.
• Subcontractors submit their prices through the same link, broken down by scope item, so prices can be compared like-for-like.
• Questions from bidders (RFIs) and changes to the drawings (addenda) are distributed to everyone at once, fairly, and the system tracks who has seen what.
• When the deadline passes, the GC compares all bids side by side, with the software flagging suspicious gaps and outliers, then awards the winner.
• Every meaningful action is recorded in a permanent audit trail — who saw what, when, and which version of a document they saw. If a dispute ever arises, that record exists.

The software also includes AI-assisted features (drafting scope lists from drawings, suggesting which subcontractors to invite, reviewing bid comparisons). All AI output is advisory — a human always approves anything that goes out the door. See the FAQ for an important note about how the AI behaves in the demo preview.

The platform is open source. It is part of the WBSP (worlds-biggest-software-project) initiative.

---

3. The domain — construction bidding in a nutshell

If you're new to construction, here's the setting this software lives in.

Before a building is built, someone has to promise to build it for a price. Winning that promise is called bidding, and it works like this:

A project owner (a city, a developer, a company) hires designers, who produce drawings (the plans) and specifications (the written requirements). Together these can run to hundreds of megabytes of PDFs.

A general contractor wants to win the job. But a GC rarely does all the work itself — it hires subcontractors for each trade: concrete, masonry, steel, plumbing, electrical, roofing, and dozens more. So the GC's estimator breaks the project into trade-sized pieces called bid packages, and invites subcontractors to price each one. That invitation is called an invitation to bid, or ITB.

Each subcontractor reviews the drawings for its trade — historically in a physical room full of plans, which is why the online equivalent is still called a planroom — and decides whether to bid. If yes, they submit a price, usually with inclusions ("our price covers X") and exclusions ("our price does not cover Y").

The deadline matters enormously. Bids submitted late don't count. Some bids are sealed — no one, not even the GC, may look at the prices before the deadline — to keep the competition fair.

During the bidding period, two things always happen:

• Bidders have questions. Each question is a Request for Information (RFI). Fairness demands that every bidder see the same answers.
• The drawings change. Each bundle of changes is an addendum, and the GC must be able to prove every bidder saw it — a bidder who priced the old drawings is a problem waiting to happen.

After the deadline, the GC compares the bids. This is called bid levelling: lining the bids up side by side to find out which is truly cheapest once you account for what each bidder excluded. A bid that looks low but excludes a chunk of the work is a scope gap, and scope gaps are how GCs lose money. Finally, the GC awards each package to a winner, and the award becomes a subcontract.

Two more pieces of vocabulary you'll see throughout the software:

• CSI MasterFormat — the standard industry numbering system for construction work. Every trade and every scope item is tagged with a MasterFormat section number (for example, division 03 is concrete, division 23 is heating and cooling). This is what makes searching and comparing by trade possible.
• DBE / MBE / WBE certifications — Disadvantaged, Minority, and Women-owned Business Enterprise certifications. Public projects often require a percentage of the work to go to certified firms, so the platform tracks certifications and can report whether a project met its goals. Public projects may also carry prevailing wage requirements (government-set minimum pay rates), which the platform records on the project.

The people, in one line each: the estimator prices the job; the preconstruction team manages the bidding process; the project manager runs the job once won; the subcontractor prices and performs one trade.

---

4. Where it fits

Who runs it. The platform is multi-tenant: one running copy can serve many independent companies, each seeing only its own data. It can be self-hosted by a company or run as a hosted service. It is aimed squarely at small and mid-size contractors who are priced out of the commercial alternatives (which commonly cost thousands to tens of thousands of dollars per year).

What it works alongside. The platform connects to a small number of outside things, all of them real and part of the shipped product:

• Email, in both directions. This is the most important connection. Invitations, reminders, RFI answers, addendum notices, and award notices all go out by ordinary email, sent through a standard mail server (SMTP) you provide, or through Amazon's email service when deployed on AWS. The system tracks whether invitation emails bounce and alerts the GC. Replies from subcontractors can be routed back in and filed against the right invitation. For email to actually arrive in a real deployment, the sending domain needs standard email authentication set up (SPF, DKIM, DMARC — your IT person or mail provider will know these; the project's technical notes cover the details).
• A federated sign-in service (HAP). There are no passwords in this system. Users sign in through an external identity service provided by the hosting platform, the same way "Sign in with Google" works on other sites. The software never stores a password.
• An AI model provider. The AI features send document content to an AI service (by default an external provider such as Anthropic or an OpenAI-compatible service; a deployment can instead be pinned to an approved in-region or self-hosted model). If no AI provider is configured, the software still works — the AI features simply fall back to a built-in stand-in (see the FAQ).
• A documented API and webhooks. For technically inclined customers, every major record in the system is reachable through a documented programming interface, and the system can push signed event notifications (bid submitted, award decided, and so on) to other systems. This is the intended path for connecting downstream project-management tools.

One honest boundary: the platform handles the preconstruction phase — everything up to the award and the subcontract. It is not a project management, scheduling, accounting, or payroll system, and it does not do quantity takeoff or estimating calculations for you. It hands off at award.

---

5. First run — seeing it for the first time

The easiest way to see the product is the standalone preview: a single self-contained package that runs the entire platform — database, document storage, background workers, and web interface — on one machine, with a realistic demo company and demo projects already loaded. Nothing else needs to be installed except Docker.

To build and start it, from the project folder:

docker build -f preview/Dockerfile -t cbp-preview .
docker run --rm --name cbp-preview -p 4000:4000 -e PORT=4000 cbp-preview

The build takes roughly 10–20 minutes the first time. Startup takes about 15–30 seconds; watch the logs for ready — open http://localhost:4000, then open http://localhost:4000 in a browser.

Signing in. The first thing you'll see is a login screen. Real sign-in uses the external identity service described in section 4, which requires credentials you won't have in a local preview. For local evaluation only, the preview supports a one-time bypass that signs you in as the demo company's administrator — start the container like this instead:

docker run --rm --name cbp-preview-bypass -p 4000:4000 -e PORT=4000 \
  -e CBP_AUTH_BYPASS_TOKEN=local-preview-only-token \
  -e CBP_BYPASS_ORG_ID=9a4fe6d6-831b-59ea-8a8e-98d39515a500 \
  cbp-preview

That scopes you to the demo general contractor, Summit Ridge Builders, LLC of Columbus, Ohio, and every screen comes up populated: six projects, eleven bid packages in various stages, forty invitations, twenty-nine bids, questions, addenda, levelling sheets, and awards. This bypass only works on local preview runs — it cannot be enabled on a real deployment.

Seeing the subcontractor side. The demo includes an invitation link you can open without any login at all:

http://localhost:4000/planroom/cbp-demo-planroom-rv-bp03-precision-concrete

That's exactly what a subcontractor sees when they tap the link in an invitation email: the documents for their package, the scope items, and the buttons to declare intent or submit a bid.

Data in the preview is throwaway by design. Each plain docker run starts from the same pristine demo world; anything you change disappears when the container stops. Section 8 explains how to keep changes if you want to.

---

6. Setting up a real environment

This section is for moving beyond the demo to a working system with your own company's data. Some steps are technical; they're summarized here in plain terms, with pointers to the detailed runbooks.

What a fresh system needs. A brand-new, empty installation contains no companies, no people, and no projects — only the industry's standard trade classification list (CSI MasterFormat), which is built in. Getting to a usable system means:

1. Initialize the database. A provided initialization script wipes the (empty) system and creates exactly one organization — your company — plus the very first administrator, and records the event in the audit trail. It refuses to run on a system that already contains data unless you explicitly force it, so an accidental re-run can't destroy anything. The full procedure, including its safety confirmations, is in production-initialization.md (see the document map below).
2. The first administrator signs in. Sign-in is through the external identity service — there is no password to set. If the initialization pre-bound the first admin's identity, they land directly in the new organization. Otherwise, the first person to sign in can register the organization themselves and automatically becomes its administrator.
3. Invite the team. The first administrator adds colleagues by email and assigns each a role (see "User roles" below). Each colleague's account activates the first time they sign in.
4. Set up email. Outbound invitations need a working mail server and a properly authenticated sending domain. Until this is done, the software works but invitations don't reach anyone — this is the single most important configuration step for a real deployment.
5. Build your subcontractor list. Add the subcontractors you work with as private contacts (with your own private notes), and search the shared directory of subcontractors who have published profiles. Both sources can be filtered by trade, distance, certifications, and prequalification status.
6. Create your first project and bid package. Upload the drawings and specifications, add scope items (by hand, or review AI-proposed drafts), set the due date, choose whether bids are sealed or visible on arrival, publish, and invite.

There is deliberately no fictional demo data in a real environment. The demo dataset described in this document exists only in the preview and in local development databases, and the initialization tool and the demo loader are kept strictly separate.

---

7. Day to day

What people actually do in the product, by role.

The GC estimator / preconstruction team (daily driver)

• Create and maintain projects — location, dates, status (planning, bidding, awarded, in construction, completed), and for public jobs, the diversity goals and prevailing-wage details.
• Upload and manage documents — drawings and specs, often very large. Files are checked for integrity before they become visible, every version is kept, and only one version is "current" at a time.
• Assemble bid packages — scope items tagged to standard trade codes, the relevant documents, a due date, a budget figure, and the sealed/open setting.
• Invite subcontractors — one by one or in bulk. The system prevents accidental duplicate invitations, tracks every invitation (sent, opened, viewing documents, bid submitted, no-bid, expired), and automatically reminds invitees who haven't responded as the deadline approaches.
• Watch coverage in real time — per package, how many were invited, how many responded, how many have submitted.
• Answer questions — respond to RFIs, optionally distributing the answer to every bidder at once so no one gets an unfair advantage.
• Issue addenda — bundle drawing changes, notify all bidders, and watch the acknowledgement percentage climb; bidders who haven't acknowledged are visible in one view.
• Level the bids — after the deadline, compare all bids side by side per scope item. Missing items are flagged as gaps, statistical outliers are highlighted, and adjustments (say, adding the cost of something a bidder excluded) recompute the totals automatically.
• Award — pick exactly one winner per package. Winner and losers are notified automatically, and the award converts into a subcontract record that updates the project budget. An award can be voided if something goes wrong; that, too, is fully recorded.

The GC administrator

Everything above, plus: manage the organization's settings, invite and manage users and their roles, set how long records are retained (the default is ten years), and — if it ever comes to it — request deletion of the organization's data, which starts a grace period before anything is permanently removed.

The project manager

Works alongside estimators on projects and packages with the same day-to-day write access; in practice the system treats estimators, project managers, and general members as equally able to do the work, with viewers read-only and admins managing the organization.

The viewer

Read-only. Can see everything in the organization, change nothing. Suited to leadership, owners' representatives, or anyone who needs visibility without the ability to touch anything.

The subcontractor (no account)

This is the carefully designed path, because most subcontractors will never log in:

• Receive the invitation email, tap the private link.
• See exactly one package's documents — nothing else in the project.
• Declare bid or no-bid (with an optional reason) in one tap.
• Download documents; every download is recorded.
• Submit a structured bid: amounts per scope item, a total, and inclusions/exclusions. Revise it as often as needed before the deadline — every version is kept.
• Ask questions (RFIs), read the published answers, view addenda, and acknowledge them.
• The link expires shortly after the bid deadline, and can be revoked by the GC at any time. The screens are built for a phone on a bright job site.

The subcontractor (with an account — optional)

Subcontractors who want more can register and maintain two things: a directory profile (published so GCs can find them, or kept private) and a prequalification profile — bonding capacity, safety record, insurance, financial documents — which they can share with specific GCs on a case-by-case basis and revoke at any time. Bidding itself still happens through the invitation link, not the portal.

---

8. Ongoing care

Backups. The database is the system of record and is backed up continuously (point-in-time recovery) with a nightly full copy as a second tier; documents live in versioned object storage. The recovery targets are: lose at most 24 hours of data, be back within 4 hours. A restore procedure has been written down and actually rehearsed — see backup-restore-runbook.md in the document map below. The most important ongoing habit is simply to re-run that restore drill after major updates so the backups are proven, not assumed.

Record keeping and retention. By default, bids, audit records, planroom download logs, and prequalification documents are kept for ten years per organization, and nothing is automatically deleted before that horizon. An administrator can adjust the retention period. Deleting an entire organization starts a grace period (thirty days by default) during which the decision can be reversed; afterwards the data is purged. One honest caveat for operators: the cleanup jobs that enforce retention and deletion exist and are tested, but in the current build they are not yet wired to run on an automatic schedule — they need to be triggered by whoever operates the system.

Reports and dashboards. A built-in analytics view shows the bid pipeline (packages and awarded value by stage), subcontractor response rates, and win rates by trade and region; the figures refresh automatically every few minutes. Public projects can produce a compliance report comparing diversity goals against what was actually awarded. Bid tabulations and proposals export as accessible PDF documents.

Notifications. Users receive in-app and email notifications for the events that matter: invitations, addenda, answered questions, submitted bids, award decisions.

Housekeeping. Most routine care is automatic: reminders to non-responders, deadline sweeps that close out overdue packages and expire old invitation links, and dashboard refreshes all run on their own schedules. The operator's real duties are the backups, the restore drills, the email deliverability setup, and software updates.

---

9. Glossary

• Addendum — an official bundle of changes to the drawings or specs, issued while bidding is open. Bidders must acknowledge it.
• Award — the GC's decision of which bidder wins a bid package. Turns into a subcontract.
• Bid — a subcontractor's formal price offer for a bid package, including its conditions.
• Bid levelling — comparing bids side by side, adjusting for what each one includes or excludes, to find the true best price.
• Bid package — one trade-sized slice of a project sent out for pricing (e.g. "Division 03 — Concrete").
• Bonding capacity — the maximum contract value a surety company will guarantee for a subcontractor; a key prequalification figure.
• CSI MasterFormat — the standard numbering system for construction trades and work items (division 03 = concrete, 23 = HVAC, etc.).
• DBE / MBE / WBE / SBE — Disadvantaged / Minority / Women-owned / Small Business Enterprise certifications, often tied to public-project participation goals.
• Estimator — the person at a construction company who works out what a job will cost and assembles the bid.
• General contractor (GC) — the company that bids for the whole project and hires subcontractors to perform the trades.
• Invitation to bid (ITB) — the request sent to a subcontractor asking for a price on a bid package.
• Planroom — the place (historically physical, now online) where bidders review the drawings and documents for a package.
• Prequalification — a subcontractor's documented financial, safety, and insurance standing, reviewed by a GC before trusting them with work.
• Prevailing wage — government-set minimum pay rates required on many public projects.
• RFI (Request for Information) — a bidder's question about the drawings or specs, and the GC's official answer.
• Scope gap — work that no bidder's price covers; discovered at levelling if you're lucky, in construction if you're not.
• Scope item — one line of work within a bid package (description, trade code, unit, quantity), which bids are priced against.
• Sealed bid — a package whose submitted prices are hidden from everyone until the deadline passes.
• Subcontract — the contract formed from a winning bid.
• Subcontractor (sub) — a company that performs one trade under the GC.

---

10. The other documents in this folder

• production-initialization.md — the technical runbook for preparing a brand-new, empty production or staging system for first use: wiping the database safely, creating the first organization and first administrator, and verifying the result. For whoever operates the system, not for end users.
• backup-restore-runbook.md — the technical runbook for backups and disaster recovery: what is backed up, how to restore, and the record of a timed restore drill proving the recovery targets are met. Read this before any reset of a system that has held real data.
• store-thumbnail.png — an image asset (a store/marketplace thumbnail), not documentation.

---

11. User roles — who can do what

Every user belongs to exactly one organization and has exactly one role. These are the only roles that exist in the product:

Role	What they can do
Admin	Everything, plus manage the organization's settings, invite and manage users, set retention, request organization deletion.
Estimator	Full day-to-day work: projects, documents, packages, invitations, RFIs, addenda, levelling, awards.
Project manager	Same day-to-day write access as estimators.
Member	Same day-to-day write access as estimators.
Viewer	Read-only across the organization.

Separately, individual projects can carry team assignments (lead estimator, estimator, project manager, viewer) to record who is responsible for what on that job.

Subcontractors are not "users" in this sense: invited bidders act through their private invitation link with no account at all, and registered subcontractor organizations have the same role set within their own company. No one can ever see another organization's data — cross-company access is blocked and every attempt is logged.

---

12. Demo data, and starting fresh

What the preview ships with. One fictional general contractor — Summit Ridge Builders, LLC of Columbus, Ohio — with five users (an admin, two estimators, a project manager, and a viewer), plus eighteen fictional subcontractor companies around central Ohio. Around them: six projects in every stage from planning to completed (three public jobs with diversity goals and prevailing wage), thirty-six documents, eleven bid packages in every stage from draft to awarded (some sealed, some open), fifty-four scope items, forty invitations in every response state, twenty-nine bids with full line-item breakdowns (including one revised bid), eight RFIs, four addenda with per-bidder acknowledgement trails, four levelling sheets with gap and outlier flags, two awards with subcontracts, and a full audit trail of roughly 310 recorded events. Every screen in the product comes up populated.

One deliberate gap: the demo's documents exist as records, but the actual PDF files are not in the demo storage — document downloads in the preview won't return real files.

Starting fresh in the preview. Do nothing — that's the default. Every plain start of the preview container begins again from the pristine demo world. If you chose to keep your changes between runs (by mounting a data volume), delete that volume to return to the clean demo.

Starting fresh for real. Use the initialization procedure in production-initialization.md. It creates an empty system with just your organization and first administrator — no demo data — and it double-checks with typed confirmations before wiping anything.

---

13. FAQ and common gotchas

"The preview asks me to log in and I don't have an account." Expected. Real sign-in uses an external identity service you don't have locally. Use the login bypass shown in section 5 — it exists precisely for local evaluation, and it is impossible to enable on a real deployment.

"I sent an invitation and no email arrived." Email needs a real mail server configured. The preview and local setups point at a catch-all mail address that, in the preview, isn't running — so invitations are created and tracked but nothing is delivered. To experience the subcontractor side, open the demo planroom link from section 5 directly. On a real deployment, sort out the sending domain's email authentication (SPF, DKIM, DMARC) before going live, or invitations will land in spam.

"The AI features feel canned." In the preview they are. No AI provider is configured there, so the AI features run on a built-in stand-in that returns fixed, realistic-looking demo output. The surrounding workflow is real — drafts, review, human approval, audit records — but the content is placeholder. Point the system at a real AI provider to get real analysis.

"I can't see the bids that have come in." If the package is sealed (the default), bid contents are hidden from everyone — including GC admins — until the due date passes. That's a fairness feature, not a bug, and even attempts to peek are recorded. Create the package as "visible on arrival" if you want open bids.

"A subcontractor says their link stopped working." Invitation links expire shortly after the bid deadline, and the GC can revoke them at any time. Expired or revoked links show a clear "access denied" page, and the attempt is logged.

"A bid came in after the deadline." It didn't — the system rejects late submissions outright, shows the bidder the recorded deadline, and logs the attempt. Revisions before the deadline are unlimited and every version is kept.

"My changes in the preview disappeared." By design: the preview starts from the same demo world on every run unless you deliberately mount a data volume (section 5 and preview/README.md).

"The dashboard numbers look a few minutes stale." They can be — the analytics figures refresh automatically every few minutes rather than instantly.

"I was invited to bid. Do I need an account?" No. Everything you need — documents, questions, addenda, bid submission — is in the link from your invitation email. An account is optional and only adds a directory profile and prequalification tools.

"Is there a mobile app?" No — but the subcontractor-facing screens are built for phones, and the whole product is a responsive web application.

---

14. Where to get help

This project is part of the WBSP (worlds-biggest-software-project) initiative. For questions, discussion, and community support, visit https://wbsp.ai.