Read Me First

A plain-language introduction to the Infrastructure Asset Registry, for someone meeting it for the first time. No technical knowledge is assumed. If you read only one document here, read this one.

Everything below describes what the software actually does today. Where a thing is optional, or switched off until somebody turns it on, it says so.

---

1. Who this is for

The people who look after publicly owned physical things and have to answer for them.

In practice that means a city or county public works department, a highway or transportation agency, a water or sewer utility, a school district, a parks authority, or a port or airport authority. The software was built with the smaller and less well-resourced end of that range firmly in mind — the agency with a few thousand assets, a handful of staff, no dedicated mapping specialist, and no budget for a six-figure software rollout.

Six kinds of people use it, and they want quite different things from it:

• The field inspector, who is outdoors in the weather, possibly wearing gloves, often holding a phone one-handed, and frequently with no mobile signal at all. This person's situation shaped more of the design than any other.
• The asset coordinator, office-based, who keeps the records straight, imports data, and fixes what is wrong.
• The public works director, who has to go in front of an elected council and defend a spending programme.
• The finance officer, who has to produce the annual accounting disclosures and support grant applications.
• The IT or systems person, who has to install it, connect it to what the agency already runs, and satisfy a security review.
• The resident, who has no account and no training, who wants to report a blocked drain and later find out what happened to it.

You do not need to be any of these to evaluate it. But knowing whose problem it solves makes the rest of this document read the way it was written.

---

2. What it does

It is the agency's single, authoritative list of everything it owns and is responsible for — every road segment, bridge, pipe, culvert, traffic signal, building and park — with, for each one, where it is, what condition it is in, what has been done to it, and what it is worth.

That list then does four jobs:

1. It tells you what you have. One searchable register instead of a dozen spreadsheets, a filing cabinet and somebody's memory.
2. It records condition properly. Inspectors go out, record what they actually see, and the condition score is worked out from those observations using the recognised industry method for that kind of asset — not from somebody's impression. Another person reviews and approves before it counts.
3. It turns condition into money decisions. Model what happens to the network over the next ten years at different budget levels, including the "do nothing" option, and see what deferring work costs. Then turn the option you choose into an actual list of projects.
4. It produces the reports you are obliged to produce. The annual accounting disclosure and grant-application packs are generated from the records already held, rather than assembled by hand.

Around those four sit the supporting pieces: work orders so that a defect found becomes a job done; scheduled routine maintenance that raises its own work orders; an import tool for getting legacy spreadsheets in; and an optional public area where residents can report problems and see what the agency plans to do.

Two honest caveats

This is a working core, not a finished product. The functionality is built and works. What it deliberately does not have is styling, branding, or your agency's own terminology. It is plain on purpose, and meant to be taken and made yours. If you have the domain knowledge and some skill with AI tools you can do that yourself; if you would rather hand it over, section 14 says where to find people who do this.

Some capabilities need a setting you supply. Four features use an AI model: proposing a condition score from inspection photographs, answering questions typed in plain language, writing a plain-language summary of a funding scenario, and proposing how spreadsheet columns map onto registry fields. If the agency has not supplied model access, those four report themselves as unavailable and everything else works exactly as normal — no degraded results, no failures elsewhere. There is always a manual path; the import mapping, for instance, can be done entirely by hand.

---

3. The domain

If you have not worked in this field, here is the background that makes the rest make sense.

A public agency owns a very large quantity of long-lived physical stuff. A mid-sized city might have several hundred miles of road, thousands of drainage structures, hundreds of signals, dozens of buildings and bridges. Collectively this is worth far more than the agency's annual budget — often hundreds of times more. It all decays. None of it decays at the same rate, and almost none of it fails visibly until shortly before it fails expensively.

The traditional way of managing this is to wait for complaints. Somebody reports a pothole, a crew fills it. This is called reactive or complaint-driven maintenance, and it is both the most common approach and the most expensive one, because work happens at the worst possible moment — after failure, at emergency rates, on whatever squeaks loudest rather than whatever matters most.

The alternative is condition-based management: inspect things on a cycle, score their condition on a consistent scale, watch the scores trend, and spend the money where the evidence says it does the most good. This is not a new idea — it is standard practice in well-funded agencies and has been for decades. The obstacle has never been the concept. It has been that the software to do it was priced and built for large organisations.

A few terms you will meet, all explained further in the glossary:

• Condition rating. A number on a defined scale saying how good or bad something is. Crucially, different kinds of asset use different recognised scales — roads are scored one way, bridges another, pipes another. The software knows this and scores each asset by the method its class is rated under.
• Inspection. The visit where somebody looks at the asset and records what they see. The rating is calculated from those observations.
• Backlog. The total value of work that is already needed and has not been done. Left alone, it grows.
• Cost of deferral. What it costs, over time, to not do work now. This is the number that wins arguments with budget committees, because postponing work is not free — it is a loan at a bad interest rate.
• Capital programme. The multi-year list of major projects an agency intends to fund, usually adopted publicly by the elected body.
• GASB 34. A United States public-sector accounting requirement. In short: an agency must report on its infrastructure in its annual financial statements, and it may choose between two approaches — depreciate the assets like any other fixed asset, or use the "modified approach", which lets an agency skip depreciation provided it can demonstrate it assesses condition regularly and is maintaining the network at or above a condition target it has declared. The modified approach is attractive and is exactly the thing an agency cannot do without condition records. The software produces both kinds of report.

The particular problem this product exists to solve

Almost every established product in this market is built on top of a commercial mapping platform, which the agency must separately license. That licence is frequently the largest single cost, and it is a permanent one. Smaller agencies are simply priced out — not by the asset software, but by the mapping platform underneath it.

This product uses open mapping standards throughout and needs no commercial mapping licence, no map service account, and no external mapping key of any kind. The map background is bundled into the product itself, so the map page does not call out to any outside service. That constraint is the single most important thing about the product, and it is enforced: a step that asks for a commercial mapping account would be treated as a defect.

---

4. Where it fits

The customers and users expected

One installation serves one or more agencies, kept entirely separate from each other. Within an agency, staff are organised into departments and given roles (section 10). Residents need no account at all.

The people who typically decide to buy or adopt something like this are the public works director, the asset coordinator, and the agency's IT director, usually under pressure from one of two directions: an accounting obligation they cannot currently satisfy, or a funding programme that requires them to demonstrate they manage their assets properly.

The systems it expects to work alongside

It does not try to be the agency's only system. It expects to sit beside:

• A geographic data service — typically maintained by the county, the state, or the agency's own mapping team. The registry can be connected to one and thereafter keep matching assets' locations up to date automatically, rather than having somebody re-key them.
• Mapping and analysis tools the agency already uses. Because the registry speaks open spatial standards, common open-source mapping desktop software and web mapping libraries can read from it directly. Data can be exchanged in the standard open formats in both directions, including the older format some municipal exchanges still require.
• Finance and enterprise systems. Everything the registry knows is available through its own programmable interface, which is how a finance system, a reporting dashboard or a custom workflow connects to it. The full interface description is published with the product, so an integrator can design against it before installing anything.
• Other applications that want to show the map. Network-scale maps can be embedded elsewhere.
• Spreadsheets. Realistically, this is what the agency's records are in now, and the import tool is built on that assumption.

There is no requirement to connect any of these. The product is fully usable with none of them.

---

5. First run

What you do first depends on which of two situations you are in.

If you are evaluating it

Start the preview. It is a single self-contained package that includes the application, its database — already loaded with a demonstration agency — and everything else it needs. Nothing to configure, no account to create, no external service to sign up for.

When it comes up, open the asset register. That is the front door and the right first screen: the full list of the demonstration agency's assets. Filter it, click into an asset to see its record and condition history, then follow the walkthrough order that shows the product's argument end to end:

1. The register, and one asset's record.
2. The asset hierarchy — how a road network contains segments.
3. The map.
4. The field view (open it on a phone, or narrow the browser window) and the inspection form.
5. The review queue, where a supervisor accepts or rejects field work.
6. The work-order board.
7. Funding scenarios, and the capital programme that comes out of one.
8. The compliance reports.
9. The import tool.
10. The public area — reporting a problem, and the transparency page.

That is about twenty minutes and it covers the whole product. The demonstration agency is a fictional city whose assets sit on real streets, so the map shows something recognisable rather than scattered dots.

getting-started.md has the exact commands, and demo-data.md explains the demonstration agency in detail.

If you are setting up a real system

Do not load the demonstration data. There is a separate one-off setup step that creates your real agency, its first department, and its first administrator, and creates no fictional records at all. The two tools are named apart, guarded apart and documented apart precisely because running the wrong one is expensive.

The real-system step is in production-initialisation.md. Read its safety section before running anything: the step clears the database before writing the base records, which is unremarkable on a genuinely empty system and irreversible on one that is not.

The first administrator does not get a password. They become real by signing in through the agency's identity system, so sign-in has to be working before anybody can administer anything.

---

6. Setting up

Once the system exists and you can sign in, this is the order that avoids rework.

1. Define your asset classes before you import anything. An asset class is a kind of thing — "road segment", "culvert", "traffic signal", "park". Each class defines the fields that apply to it, so a culvert is described as a culvert rather than squeezed into a form designed for roads. Some of those fields can be mandatory. Get this right first: importing against a taxonomy you have not finished creates failures you then have to clean up.

2. Decide your asset numbering. Every asset needs an identifier unique within your agency. If your existing spreadsheets contain overlapping identifiers from different eras, resolve that in the source data, not afterwards — duplicates are rejected at import, naming the conflict.

3. Set up departments and people. Create the departments that own assets, then add staff and give each one a role. Section 10 explains what each role can do. Get the separation right between who records an inspection and who approves it, because by default they cannot be the same person.

4. Import your existing records. Upload a spreadsheet; the system proposes how each column maps onto registry fields; you correct anything you disagree with; nothing is written until you confirm. Valid rows become assets, invalid rows do not, and every rejection is reported with its row and its reason.

Import a small representative sample first, read the failure report, fix the source, and repeat. This is far cheaper than discovering a systematic mapping mistake after ten thousand rows. Every imported asset stays traceable to the batch it came from.

5. Connect your geographic data source, if you have one. Where your locations live in a county or state service, connect it once rather than importing geometry by hand. From then on it keeps matching assets current, and running it twice does not create duplicates.

Assets with no location at all are perfectly legitimate — a newly catalogued building, a culvert nobody has surveyed. They work everywhere in the product except map views, which leave them out and say so rather than inventing a position for them.

6. Set your condition targets. If you intend to use the modified accounting approach, declare the condition level you are committing to maintain per asset class. The compliance report compares actual against that target and states whether the standard was met.

7. Decide about the public area. It is off for a new agency and stays off until somebody deliberately turns it on. When you do turn it on you choose, class by class, exactly what becomes visible, and you are shown precisely what will be exposed before the change takes effect. Asset locations are never published.

8. Optionally, supply model access for the four assisted features described in section 2. Skip this and everything else still works.

Technical setup — installing, deploying, connecting systems — is covered in getting-started.md, the installation and integration guides under collateral/, and security-posture.md for a security review.

---

7. Day to day

The inspector, in the field

Opens the field view on a phone before leaving, which stores the assets, the condition methods and the forms on the device. The top of the screen says plainly whether the device is ready to work with no signal.

At the asset, records an inspection: what was actually observed, defect by defect, with photographs. The score is computed from those observations. A field left blank stays blank — it is not treated as a recorded zero.

With no signal, nothing stops and nothing is lost. Work queues on the device, visibly and countably. When a connection returns the queue empties on its own, and submitting the same inspection twice cannot create it twice. Two inspectors both working offline on the same asset will both have their work survive; neither is silently discarded.

The supervisor

Works the review queue. Field work does not go straight into the record — it arrives here, and a supervisor accepts it or sends it back with a reason. The person who approves cannot be the person who recorded it, and that is enforced by the permissions rather than left to procedure. An agency may permit self-approval if it chooses, and each approval records which rule applied.

Once approved, the asset's current condition, rating band and inspection date update to match.

Where an inspection found something serious, the supervisor raises a work order straight from it, and the work order records both the asset and the inspection that prompted it.

The crew

Work the work-order board. Orders move through their states — open, assigned, in progress, on hold, closed — and invalid jumps are refused rather than accepted quietly. On completion, labour and material costs are recorded, and the asset's lifetime maintenance cost goes up by exactly that. Priority is shown by shape and wording as well as colour, so the board can be printed for a crew briefing and still mean what it says.

Routine recurring maintenance is defined once as a template and raises its own work orders when due, without anybody remembering to.

The coordinator

Keeps the register straight: registering new assets, retiring things that have gone, maintaining the hierarchy, running imports, and correcting what the field finds wrong. If two office users edit the same record at once, the second save is refused as out of date, the differences are shown, and the rejected user's input is kept for resubmission rather than thrown away.

The director

Uses the funding scenarios. Run several annual budget levels over a multi-year horizon and see, for each, how average condition and backlog evolve, and what the deferral costs. Comparing those scenarios is the argument you take into a council meeting. The scenario you settle on becomes a capital programme of real projects in real years for real amounts, each one traceable back to the assets that justified it.

The finance officer

Generates the annual disclosure — either accounting approach — and grant application packs, from records already held. A generated report keeps the figures it was built from, so it reads back later exactly as produced, even after the underlying records have moved on.

Anybody, occasionally

Types a question in plain language rather than building a filter — "which culverts are in poor condition and unplanned". The answer comes from the register itself, within the asking person's own permissions, and traces straight back to the records. It is a shortcut to a query, not a source of new facts, and it says so when it cannot answer from the data rather than guessing. This is one of the features that needs model access.

Residents

Report a problem through the public pages with no account: a description, a photograph, a location. The report attaches itself to the nearest recorded asset and enters the agency's queue, and the resident gets a reference number to check the status later. Separately, where the agency has turned it on, anyone can see overall asset conditions and planned capital works.

---

8. Ongoing care

Inspect on a cycle. The product's value decays with its condition data. Set an inspection frequency per asset class and keep to it. If you intend to use the modified accounting approach, regular condition assessment is not optional — it is the thing that entitles you to use it.

Watch your coverage. Not every asset will be rated, and the product tells you so rather than quietly averaging over the gaps. Treat a growing unassessed share as a problem to fix.

Re-run the scenarios annually, before budget season, with the year's new condition data in them. A scenario built on three-year-old ratings argues for the wrong things.

Produce the compliance report each reporting year. It is generated rather than assembled, but somebody still has to run it and read it.

Keep the taxonomy tidy. Over time, classes accumulate fields nobody fills in. Prune them.

Retire rather than delete. Records are never truly erased — assets, inspections and work orders are retired and retained, because the history is the point and an audit trail with holes in it is worth little. A narrow, audited path exists solely for privacy obligations.

Back up, and test the restore. The product commits to losing no more than 24 hours of data and being back within 8 business hours, with restores verified automatically rather than assumed. That commitment is only real if somebody periodically checks it. The runbook is backup-restore.md — written for whoever is on call when the environment is gone.

Review who has access. Roles are resolved fresh each time somebody acts, so removing a role takes effect immediately rather than at their next sign-in. Use that.

When a condition standard changes. If your agency adopts a revised rating method, historical inspections keep the method used at the time, and trends will not silently compare scores that are not comparable.

---

9. Glossary

Term	What it means
Asset	One physical thing the agency owns and is responsible for.
Asset class	A kind of asset — road segment, culvert, signal, park — defining which fields apply to it and which are mandatory.
Asset hierarchy	The parent-child structure: a road network contains segments, a segment contains components. Lets you roll condition or cost up, or drill down to the one part dragging an average.
Asset number	The identifier unique within your agency.
Backlog	The value of needed work not yet done.
Capital programme	The multi-year list of major projects the agency intends to fund. Often called a CIP — capital improvement programme.
Condition rating / score	A number on a defined scale describing an asset's state, computed from what an inspector recorded.
Rating band	The plain-language grade a score falls into — good, fair, poor and so on.
Cost of deferral	What postponing work costs over time.
Defect / distress	A specific observed fault — a crack, a spall, a blockage — of a defined type and severity, recorded individually.
Depreciation approach	The accounting treatment where infrastructure is depreciated like any other fixed asset.
GASB 34	The US public-sector accounting requirement covering how agencies report infrastructure.
Inspection	A recorded visit to an asset. The source of condition scores.
Modified approach	The GASB 34 alternative that lets an agency skip depreciation provided it demonstrates regular condition assessment and maintenance at a declared target level.
Maintenance template	A definition of recurring routine work that raises its own work orders when due.
Open spatial standards	Publicly published, licence-free ways of describing and exchanging location data — what this product uses instead of a commercial mapping platform.
Organisation	One agency. A single installation can hold several, entirely separate.
Preventive maintenance	Work done on a schedule to stop failure, as opposed to work done after it.
Public portal	The area residents can use without an account. Off until enabled.
Reactive maintenance	Fixing things after they break or are complained about.
Retire	Take an asset out of service while keeping its record and history. Not deletion.
Review queue	Where submitted field inspections wait for a supervisor to accept or reject them.
Scenario	A modelled funding level run over several years, producing projected condition, projected backlog and a cost of deferral.
Work order	A job: what needs doing, to which asset, by whom, at what cost.

---

10. Who can do what

Seven roles. A person can hold more than one, and what they can do is the total of what their roles allow. Permissions are named after actions rather than job titles, which is why the boundaries below are precise.

Role	Broadly
Administrator	Everything, including agency settings, user administration, the audit trail, and the narrow privacy-purge path.
Manager	Runs the agency's records: assets, taxonomy, departments, work orders, planning, imports, citizen requests, report generation, and the audit trail. Can send an inspection back for rework, but cannot approve one. Can see financial data but not change it.
Supervisor	The review role. Records and reviews inspections and — uniquely, apart from the administrator — approves them. Raises and assigns work orders, manages citizen requests, reads the audit trail.
Inspector	Records inspections and edits assets. Raises work orders. Cannot approve.
Field crew	The narrowest working role: read assets, record inspections, work work orders. No planning, no reporting, no agency settings.
Finance	Reads everything ordinary, plus financial data which it can also change, and generates reports. No asset editing, no inspections, no work orders.
Viewer	Read-only across assets, taxonomy, inspections, work orders, planning, reports and agency details. Changes nothing.
(the public)	Not a role and never stored. Unauthenticated residents can submit a request, look one up by reference, and view the transparency page where the agency has enabled it.

Two of these boundaries carry real weight and are worth stating plainly:

• Approval is separated from recording. Neither an inspector nor the field crew can approve, and by default nobody can approve their own work. This is what makes a condition score defensible rather than self-reported.
• Managers deliberately cannot approve inspections. A manager runs the records; a supervisor signs off the field work. Splitting those was a choice, not an oversight.

---

11. What ships with the preview, and how to start clean

The preview contains a fictional agency — the City of Springfield — whose assets sit on the real streets of one San Francisco district, so the map shows a real place rather than dots on a grid. It holds roughly:

• One agency, one department, and six people carrying different roles, so you can see the permissions genuinely differ rather than take them on trust.
• Four asset classes covering every shape of geography: linear (road segments), point (signals, culverts) and area (parks), with custom fields of several types.
• Seven curated assets arranged in a hierarchy, plus a few hundred background assets filling in the district's other streets, culverts, signalled corners and parks. One curated asset — a culvert — has no location at all, on purpose: every real agency has unlocated assets, and a demonstration where everything is mapped hides the case the product has to get right.
• Condition ratings on some assets, not all — again deliberately, because the coverage warning, the "not assessed" wording on the public page and the partial-coverage path in the scenario engine only appear when part of the network is unrated.
• A review queue holding inspections in every pre-approval state, including one rejected with a reason and one carrying preserved offline work.
• Work orders across every column of the board, including some raised from an inspection and some generated by a quarterly park-safety template, with real labour and material charges so an asset's lifetime maintenance figure is a genuine sum.
• Four funding scenarios and two capital projects.
• Two generated reports — the annual modified-approach disclosure and a grant application pack.
• The public area enabled, the way an administrator would enable it.

All of it was created through the product's own paths — assets registered the way the application registers them, inspections approved through the real approval route by a different person from the one who recorded them — rather than written straight into the database. So what you are looking at is what the product produces.

Starting fresh. The demonstration data is for evaluating, not for building on. For a real system, use the separate first-use setup described in section 5, which creates no fictional records. Loading a second demonstration agency alongside the first is also possible and is the quickest way to see the separation between agencies on screen; demo-data.md covers it.

Re-running the demonstration load is safe — it recognises what it already created and adds nothing a second time.

---

12. The other documents here

Everything in this folder, and who each is for:

Document	For	About
getting-started.md	Anyone installing it	From nothing to a running system with data in it. Start here after this document.
demo-data.md	Anyone demonstrating or evaluating	The demonstration agency: what it contains, how to load it, and how it differs per environment.
production-initialisation.md	The operator of a real system	The one-off act of creating your real agency, first department and first administrator. Read its safety section first.
useful-commands.md	Operators and developers	The commands worth keeping to hand.
api-reference.md	Integrators	How to work with the programmable interface.
openapi.yaml	Integrators and tooling	The machine-readable description of that interface, generated from the running system.
testing.md	Developers and reviewers	What the test suites are and which question each answers.
deployment-validation.md	Operators and reviewers	Recorded evidence from an actual deployment.
security-posture.md	A security reviewer	The security position: what is enforced, how, and what is out of scope.
nist-800-53-mapping.md	An agency's assessor	How the product maps onto the US federal control catalogue, for procurement and authorisation reviews.
accessibility.md	Procurement and accessibility reviewers	The formal accessibility conformance statement.
backup-restore.md	Whoever is on call	The runbook for when the environment is gone.
dependency-licences.md	Legal and procurement	Every dependency and its licence — the evidence behind the no-commercial-mapping-licence claim.
login-bypass.md	Developers and reviewers	A local-machine-only sign-in shortcut, why it exists, and the limits that keep it local.
quickstart-results.md	Reviewers	The published quickstart, executed, with results.
store-thumbnail.png	—	The product image.

There is more beyond this folder: sales and marketing material, white papers on the specific arguments (vendor-neutral mapping, the modified approach, offline field work, cost of deferral, migration), detailed technical documents, and both a plain-English and a detailed user guide.

---

13. Common questions and gotchas

Do I need a commercial mapping licence or a map service account? No. Not for anything, at any point. The map background is bundled into the product and the map page calls out to no outside service. If you ever hit a step asking for one, that is a defect worth reporting — it is the single constraint the whole product exists to satisfy.

Does the field app really work with no signal? Yes, and that is the case it was designed around rather than an afterthought. Assets, condition methods and forms are stored on the device before you lose reception; work queues visibly while you are offline; the queue empties itself when a connection returns; and the same inspection submitted twice cannot create two.

Can an inspector approve their own inspection? Not by default. An agency can permit self-approval if it wants to, and each approval records which rule applied — so the distinction survives into the compliance reporting rather than being lost.

Can I delete an asset? No. You retire it, and the record and its history are kept. A narrow audited path exists only for privacy obligations. This surprises people, and it is intentional — the history is most of the value.

Is the public area on? No. It is off for a new agency and stays off until somebody deliberately enables it, choosing class by class what becomes visible and seeing exactly what will be exposed before it takes effect. Asset locations are never published.

What happens with no AI model access configured? The four assisted features report themselves unavailable. Everything else is unaffected — no degraded scores, no partial results, no failures elsewhere. There is a manual path for what matters, and the import mapping can be done entirely by hand.

What if two office users edit the same record at once? The second save is refused as out of date, the differences are shown, and the rejected user's input is kept so they can resubmit. Nothing is silently overwritten.

What about an asset with no location? Perfectly valid. It works everywhere except map views, which exclude it and say so rather than guessing a position.

We changed our rating method — does that break our history? No. Historical inspections keep the method used at the time, and trends will not silently compare scores computed different ways.

The demonstration data has gaps — assets with no rating, a culvert with no location. Is that a bug? No, it is deliberate. Several behaviours the product must get right only appear when the data is incomplete, and a demonstration where everything is perfect hides them.

Why does it look so plain? Because it is the working core with no styling or branding on top, and that is on purpose — it is meant to be taken and made yours. See section 2.

Can I run several agencies on one installation? Yes, and they are kept entirely separate. Loading a second demonstration agency is the quickest way to see that boundary on screen.

---

14. Where to get help

The community at wbsp.ai is the place to go — to ask a question, to suggest something, or to find people who can turn this core into a finished, branded application for your agency.

It is also worth looking around while you are there. The community has built many takes on this product and on others, and one of them may already be most of the way to what you need.

---

Infrastructure Asset Registry · part of the worlds-biggest-software-project initiative.