Architecture · FS-05
Contractor Financial Operations
ARCHITECTURE · $12K–$25K PROJECT BANDBid-to-cash for a GC-scale operator: bid pipeline, change-order approval chain, state-specific lien waivers, subcontractor pay applications, and weather delay documentation in one workspace, with the compliance deadlines enforced by the workflow rather than by memory.
Every figure in this console is sample data, shown to demonstrate the interface. It is not real client data and not a performance claim.
The problem this is shaped around
A general contractor running eight-figure volume tracks bids, change orders, lien waivers, subcontractor pay applications and weather delay claims across QuickBooks, three spreadsheets and an inbox. Every one of those five has a deadline attached, and the deadline is the part the spreadsheet does not know about.
How work moves through it
Stage 1
Bid enters the pipeline
Follow-up scheduled per bid at creation; win/loss reason is a required field on close, so the pipeline can be analysed rather than just emptied.
Stage 2
Contract and schedule of values
The awarded bid becomes the contract record. Every later change order and pay application references it, so nothing floats free of the original scope.
Stage 3
Change order raised
Internal draft → GC review → approved. Only an approved change order generates a contract addendum, and the addendum is generated from the record rather than re-typed.
Stage 4
Waiver generated per statute
Conditional and unconditional waivers built from the statutory form for the job's state at each payment tranche. State is a property of the job, not a setting.
Human step
Pay application released
The workflow refuses to clear a sub's pay application without a matching signed waiver on file. This is a hard block, not a warning.
Gold marks a step a person takes. There is always at least one, on purpose: the system prepares and displays, a human confirms and executes. That is the rule for money movement and for anything a model extracted from a document, and it is not negotiable on a build.
Decisions taken at the schema, not retrofitted
Jobs carry several subcontractors from the start
A join table, not a foreign key. Retrofitting many-to-many onto a live system after the first job with two subs is a migration touching every query that ever referenced the relationship.
Waiver forms are per-state records, not templates
Texas, California, New York and Florida each prescribe statutory language. A single template with a state variable produces a document that is not the statutory form, which is the same as not having one.
Every file is bound to the record it belongs to
A photo, receipt or signed document is stored with a pointer to the specific job, invoice or claim it belongs to, plus who uploaded it and when. The test is whether searching a transaction a year later surfaces its own proof automatically. A folder of unlinked images fails that test, and it is the state most businesses are in.
One database per client, not shared tables
Each build runs in its own container against its own database with its own credentials. Isolation by table prefix inside a shared database is the mistake this replaces: it works until one missing filter in one query shows a business its competitor's numbers, and by then the whole schema depends on it.
Where it breaks, and what it does about it
Anything can be made to work on a good day. This is the list that decides whether a system survives a bad one — and the honest cost of each answer, because none of them are free.
| When this happens | The system does this | What that costs to build |
|---|---|---|
| A sub sends a waiver for the wrong tranche | The waiver is matched against the specific pay application and payment amount, not just the job. A mismatch is surfaced at upload with both figures shown side by side, before anyone signs anything. | Waiver records must be modelled per tranche, which roughly doubles the waiver table's complexity. |
| The weather API is unreachable on the day of a delay | Delay records are created immediately with the observation left pending, and a retry queue backfills the NOAA reading when the service returns. The claim draft is held until the reading lands rather than being filed with a blank. | A durable job queue and a visible pending state on the claim — a day of work that most builds skip. |
| A change order is approved verbally on site | There is no path to an addendum that does not pass through the approval chain, so a verbal approval simply has no record. What the system does instead is surface the gap: work logged against a scope with no approved change order appears on the owner's exception list. | It makes the system briefly less convenient than a text message, which is the point. |
| Two people edit the same schedule of values | Optimistic locking on the contract record. The second writer is shown what changed and by whom rather than silently overwriting, because on a schedule of values the overwrite is money. | Version columns and a conflict screen; a genuine amount of UI work for an event that is rare and expensive. |
What this deliberately does not do
- It does not move money. It prepares the pay application, shows what is owed and to whom, and a person executes the payment from their own bank. There is no button here that sends funds, by deliberate policy, no matter how convenient that would be.
- It does not store a subcontractor's bank or routing numbers. A payee is identified by a nickname or a last-four, never by an account number sitting in a contractor's database.
- It does not give legal advice. Waivers are generated from the statutory form for the job's state; whether that form is the right instrument for a given dispute is a question for the contractor's attorney.
- It does not replace the accounting ledger. It reconciles against it.
Book an architecture scoping session
An hour on your actual operation — where the work currently queues, what gets re-keyed, which step everyone has quietly built a spreadsheet around. You leave with a diagram like the one above drawn for your stack, whether or not you build it here. Scope is written before any payment, always.
The linked walkthrough is an interactive demo, not a deployment: it runs entirely in your browser with sample data and resets when you refresh it. This page describes the architecture built when a business commissions the system — not a claim that this particular one is running anywhere. Systems are built on infrastructure we operate, and your data stays yours and is exportable on request at any time, including if you leave.
FS-05 · contractor-financial