Construction Service
Planning and document control for development projects — seven stages with gates, tasks that measure progress, and controlled documents with a revision history.
The construction service records a Development project: One building or site being developed, from the first idea to handing it over. It has one of four kinds: master plan, ground up, conversion, or capital improvement. Not a workspace project: a workspace project is where people talk about work, a development project is the work itself. as it moves through seven Stage: One of the seven steps every development project passes through in order: initiation, execution plan, final product approval, tender, award, construction, closeout. The first five make up the pre-construction phase and the last two the construction phase. A project is in exactly one stage at a time and cannot skip one.s, and the work and paperwork around it. That covers the plan (Package: A named body of work inside a project, such as signage, facade, or amenities. It is measured either by the progress of its tasks or by a percentage somebody reports. A project's progress is the weighted average of its packages and is never stored.s, tasks, milestones, weekly updates), the Controlled document: A document whose changes are tracked formally, such as a drawing, a specification, or the project schedule. It keeps one permanent code for its whole life; a change adds a revision rather than a new document.s the project is built from and their Revision: One version of a controlled document. Internal revisions (A, B, C, or R0-A after the first release) are working copies that are prepared, reviewed and approved. A published revision (R0, R1, and so on) is the official one people work from. Only one revision is published at a time, and publishing a new one supersedes the old.s, and the decisions, approvals and risks. It also covers the budget, the Variation: A change to the cost or schedule agreed at award, for example extra work a new drawing revision needs. It is approved through an approval, and incorporating it writes a new baseline.s that change it after award, and the outside firms doing the work. Those firms take part through a portal of their own.
- Domain
- Services
- Kind
- Go HTTP service
- Lifecycle
- Planned
- flowctl project
- None
- Stacks
- Runs on its own
Three rules shape everything here.
The first is that a project moves through stages, not through separate tools. A decision taken during initiation is still readable during construction, against the same project, in the same database. Nothing is exported and re-imported at a stage boundary.
The second is that progress has to be measurable. "Design is 70% complete" is not a figure anybody can act on, so the service will not store one. A project's percentage is computed from its packages and tasks, and each task's progress is set by the person doing it. The number on screen always has the thing it was computed from one click away.
The third is that there is exactly one current version of every document. A document keeps one code for its whole life. Changing it adds a revision, only one revision is published at a time, and a published revision is never edited. Anyone reading a superseded revision is told which one replaced it.
Run it locally
Start the service, create a project, and try to advance a stage without a gate.
Architecture
The eight domains, how stage gates are enforced, document control, and what is published.
Measuring progress
How a project percentage, health and freshness are computed, and why none of it is stored.
API
Routes, the command envelope, and the refusals worth knowing about.
Console
The construction console on port 3508.
Vendor portal
The app outside firms use on port 3509, and how each firm is kept to its own work.
The seven stages
| Stage | Phase | Gate to leave it |
|---|---|---|
initiation | Pre-construction | INITIATION_APPROVED |
execution_plan | Pre-construction | None |
product_approval | Pre-construction | PRODUCT_APPROVED |
tender | Pre-construction | TENDER_RECOMMENDED |
award | Pre-construction | READY_FOR_CONSTRUCTION |
construction | Construction | None |
closeout | Construction | The last stage. The project is completed from here, not advanced |
The order is fixed and the service refuses to skip. A Stage gate: An approval that has to be granted before a project can leave initiation, final product approval, tender, or award. Without an approved gate the advance is refused, which stops a project drifting into the next stage before the previous one is signed off. is an
approval of kind stage_gate whose subject is the stage being left; the service checks
that one has been approved before it moves the project. Passing the award gate also
records who won the construction contract and for how much, and writes the project's
first Baseline: A saved record of what was agreed at a point in time: the budget, the construction start and finish, and the published document revisions. The first is written when the project passes the award gate; each incorporated variation adds another. Earlier baselines are kept..
Every project has one of four kinds, fixed when it is created: master plan (a plan for a whole site, usually built out later as several projects), ground up (a new building), conversion (an existing building changed to a new use), and capital improvement (major work on an existing building that keeps its use). All four get the same seven stages.
Nothing has deployed. The service runs locally, has no registered Azure pipeline, and
its lifecycle status in the registry is planned. The design is settled;
the deployment is not.
Design docs
The full design, including the five-stage service map this service is the first piece of, is in docs/construction/construction.md. The calls that had real alternatives are recorded as decisions:
- docs/decisions/0086-construction-owns-the-development-project.md — why a development project is not a workspace project
- docs/decisions/0087-project-scope-for-grants.md — why the service uses Cloudflare Access and an editors list for now, and how it moves to grants
- docs/decisions/0088-measurable-progress.md — why no percentage is stored
- docs/decisions/0090-vendor-portal.md — why the vendor portal is a second app on this service, and how a firm is kept to its own work
- docs/decisions/0092-planning-and-document-control.md — the stages, gates, tasks, document control, variations and budget, and what was removed