Part 2 — Objects and rules
Part 2 — Objects and rules
Section titled “Part 2 — Objects and rules”4. Objects and vocabulary
Section titled “4. Objects and vocabulary”KI uses specific names for specific objects, and a few of those names changed when we moved off Legacy KI. Learning this table first will make the phase sections read much faster.
| Term in KI | What it is | Legacy KI called it |
|---|---|---|
| Project Record | The container for one client’s project — team, phases, documents, contracts, and financials. Created automatically when a lead is moved to the job walk stage of the CRM (customer relationship management). | Lead |
| Division | The office a project belongs to. Every project lives in exactly one Division, and Division is the level financial reporting rolls up to. | — |
| Contract | A signed agreement inside a Project Record. | Project |
| Proposal | The client-facing PDF, containing marketing, sales, and project-specific content plus construction pricing. At this stage construction pricing is called a budget, not a price. | — |
| Estimate | The priced build-up behind a proposal. Created in Legacy KI, broken out by Cost Code with markups applied. It generates the pricing PDF that goes into the proposal. | Proposal |
| Cost Code | The standard cost category used to budget, commit, and record job costs. Set up in Legacy KI Admin Setup. Custom codes can also be added to a single project and function the same way. | Cost Code |
| Billing Items | The schedule of how a contract will be billed. Billing Items must sum to the contract amount, and one of them is the deposit. | — |
| Budget Adjustment | The allocation of contract dollars to Cost Codes. The Fee is not a budget adjustment, so Cost Code budgets plus Fee must equal the contract amount. | — |
| Fee | The contract amount less the Cost Code budgets — our margin on the contract. | — |
| Pay Application | The periodic invoice, created by entering percent complete against the Billing Items. | — |
| Change Order | A priced change to a signed contract, executed when it is signed. It carries matching Billing Item and Budget Adjustment changes. | — |
| Commitment | Dollars committed to a vendor or subcontractor, shown against budget in Cost Control. | — |
A Project Record here carries one Construction Contract. There is no Design Contract, because there is no design engagement to sell.
Two objects exist on this instance and not on Story’s:
| Term in KI | What it is |
|---|---|
| Change Estimate | A priced change worked up, negotiated, and where a subcontractor is involved priced against their number, before it becomes a Change Order |
| Commitment | How a subcontractor is committed — the obligation with the signed subcontract behind it, rather than a Purchase Order standing alone |
Submittals, RFIs, Transmittals, Invitations to Bid and bid tabulation are also Legacy KI modules here and are absent from Story’s instance. The glossary defines each.
4.1 Three renames worth learning properly
Section titled “4.1 Three renames worth learning properly”These three are the ones that cause trouble, because the old word and the new word describe different things rather than the same thing renamed.
- A Legacy KI “Lead” is a KI Project Record. It is not a pre-sales stage. The Project Record exists from the job walk onward and stays the same record through design, construction, and completion.
- A Legacy KI “Project” is a KI Contract. A single KI Project Record can therefore contain two things Legacy KI would each have called a project.
- A Legacy KI “Proposal” is a KI Estimate. The word proposal was reused for something else — the client-facing PDF.
There is no object in KI called a quote, a bid, or a schedule of values. Those are industry words for things KI names differently: the priced build-up is an Estimate, the document that goes to the client is a Proposal, and the billing breakdown is Billing Items. Older documents use the industry words freely; the glossary maps them.
4.2 Why the Cost Code matters more than anything else
Section titled “4.2 Why the Cost Code matters more than anything else”The Cost Code is the classification that separates framing from plumbing from tile from cabinetry. It is shared across the whole company, set up once in Legacy KI Admin Setup rather than created per project, and that is the point. (Across this company: the other instance has its own library, and the two are unrelated.) Custom codes can be added to an individual project where a job needs a classification the shared library does not cover; they behave exactly like standard codes for budgeting, commitments, and cost recording.
Because every one of these carries the same code —
- a line on an Estimate,
- a Cost Code budget created by a Budget Adjustment,
- a line on a Purchase Order or Commitment,
- an hour of labour entered against a job,
- a vendor invoice coded by accounting —
what was priced and what was spent are directly comparable, line for line, instead of as unrelated totals. It is what makes “are we over on tile?” a question with an answer, and what lets a single line on a cost summary be opened up into the specific invoices behind it.
Because the library is shared, projects can also be compared to each other. Estimating a kitchen is easier when the last four kitchens booked their costs under the same classification.
5. The financial rules
Section titled “5. The financial rules”These are the arithmetic constraints KI enforces. They hold on both instances, and they are the part of the system that has been stable the longest.
5.1 The two balancing equations
Section titled “5.1 The two balancing equations”For every contract, independently:
Σ (Billing Items) = Contract Amount
Σ (Cost Code budgets) + Fee = Contract Amount
The second equation is the definition of Fee. Rearranged: Fee = Contract Amount − Σ (Cost Code budgets). The Fee is never entered as a Budget Adjustment; it is what is left over.
One Billing Item on every contract is the deposit.
5.2 The two kinds of Budget Adjustment
Section titled “5.2 The two kinds of Budget Adjustment”| Type | Rule |
|---|---|
| Internal adjustment | Moves money between Cost Codes. Must always net to zero once the Fee is included. A reallocation can re-cut the budget; it cannot grow it. |
| Change order adjustment | Tied to a selected Change Order. You determine how the budgets and the Fee change, and the total of the adjustment must equal the amount of that Change Order. |
The distinction is deliberate. A budget does not grow because someone decided it should — it grows because scope was priced, agreed, and signed, and the contract value moved with it.
5.3 The two kinds of Billing Item change
Section titled “5.3 The two kinds of Billing Item change”The same pattern, on the billing side:
| Type | Rule |
|---|---|
| Internal | Net change in Billing Items must equal zero. |
| Change order | Net change must equal the Change Order amount. |
A Change Order therefore moves three things together and keeps them reconciled: the contract amount, the Billing Items, and the Budget Adjustments. What the client owes and what the project is planned to cost stay in step.
5.4 Documents and comments
Section titled “5.4 Documents and comments”Every uploaded document attaches to the record it belongs to — a project, a contract, an issue, a proposal. There is no separate document system to go looking in, and no parallel filing structure to keep in sync.
Each document carries a flag for whether the client can see it, set one document at a time rather than by a blanket rule, so what a client sees is what was shared with them deliberately. See section 13.1.
Issues, Project Updates, Communications, and Documents are four separate records, not four views of one. Each is created, listed, and read in its own place, and none of them is a facet of another. How the data model underneath represents them is not documented — check before writing code that assumes a particular shape.