ModuHaus — Australian Modular House Knowledge Base

A PostgreSQL-backed knowledge base covering everything a buyer or builder needs to know about modular housing in Australia: planning regulation, finance, cost, suppliers, contracts and construction. It is built to be consumed by an MCP server and by interactive tools on the ModuHaus website (site feasibility lookup, budget estimator, and so on).

The knowledge base is deliberately built one module at a time. The schema and naming conventions below exist so that later modules drop into the same database without restructuring anything.

Design principles

One database, many modules. Everything lives in modular_house_kb. The name describes the whole knowledge base, not any single feature — there is no granny_flat_db. A single database keeps cross-module queries possible: a feasibility check that combines a planning rule with a cost band and a supplier lead time should be one SQL query, not three round trips.

The table name carries the module. Every table is prefixed with its module, so \dt in psql groups the schema by domain and any reader can tell at a glance what a table belongs to:

regulation_*     planning rules, permit pathways, DA process
finance_*        construction loan structures, lender policies, rates
cost_*           build cost ranges by spec and region
supplier_*       suppliers, product lines, specifications, reputation
contract_*       standard clauses, common dispute points
construction_*   timelines, transport and install, delay causes

Rows are jurisdiction-scoped and source-stamped. Australian modular housing rules differ per state and change often. Every fact-bearing table carries the jurisdiction it applies to plus source and last_verified, so stale content is visible rather than silently wrong. Never store a regulatory number without the instrument it came from.

Related MCP server: au-eli-mcp

Current status

Completed — Regulation module, granny flat subset

regulation_granny_flat_rules holds state-level approval standards for secondary dwellings (granny flats, office pods).

All eight jurisdictions are seeded. The headline numbers:

Every row was checked against the responsible planning authority's own site on its last_verified date. Where a jurisdiction publishes no single statewide figure the column is NULL rather than a number borrowed from a builder's website — see the NULL semantics gap below before reading those blanks.

Two rows deserve explanation:

• QLD sets no statewide standard at all. The Planning Act 2016 leaves both size and assessment pathway to each local government's planning scheme, so every numeric column is NULL and data_status is no_rule_at_this_level. The only statewide rule is the 2022 amendment removing occupancy restrictions. Queensland's real numbers live in regulation_lga_granny_flat_rules.

• default_permit_required measures whether approval is needed at all, not how fast it is. NSW is true because a complying development certificate is still issued; VIC, WA, TAS and NT are false because the requirement is removed outright when the conditions are met.

UNIQUE (state, category, rule_type) is the natural key. Note that default_permit_required is not a measure of speed but of whether approval is needed at all: NSW is true because a complying development certificate is still issued, while VIC is false because the permit requirement is removed outright.

The VIC row was verified against Planning Victoria on 2026-08-11: Amendment VC253, gazetted 14 December 2023, is the correct instrument, and the 300 sqm minimum lot size is confirmed for the residential zones.

Completed — Regulation module, council-level subset

regulation_lga_granny_flat_rules mirrors the state table plus lga_name, planning_scheme and varies_from_state. Queensland depends on it entirely; elsewhere a row should exist only where a council departs from the state position, so the absence of a row means the state rule applies.

Seeded with four Queensland councils, of which two are fully verified:

Brisbane is the instructive one. Council material says prescribed accepted development (Table 5.3.4.1) does not extend to secondary dwellings, yet Brisbane defines a dwelling house as including one with a secondary dwelling, and a dwelling house is generally accepted development under the Part 5 zone tables. Those are two different mechanisms and the reachable sources do not settle which governs, so default_permit_required stays not_researched rather than being resolved by inference. Recording the ambiguity is the point: a guess here would be indistinguishable from a fact once it is in the table.

Still to add: Sunshine Coast, Ipswich, Townsville, Cairns, Toowoomba, Redland, and the remaining Queensland councils.

Note that published builder and comparison sites disagree with the councils' own schemes on these numbers — Moreton Bay is widely quoted as 90 sqm when the scheme says 45/55/100. Seed only from the responsible authority's own document.

Completed — Cost module, granny flat subset

Two tables. cost_granny_flat_build_ranges holds build cost by state, size and specification; cost_site_works_items holds the twelve site works that get added to it.

They are split because the market's characteristic distortion is a base price presented as a total — site costs commonly add 25–50%. On the figures currently loaded, the priced site items sum to $53,500–$138,500 if every one applied. That number is the reason the module exists: it cannot be expressed as a footnote on a build price, so it gets its own table and always travels with the price.

cost_basis is NOT NULL. A price whose basis is unstated is worse than no price, because it reads as a total. Western Australia is the clearest case for that column: the same 60 sqm dwelling is quoted at about $76,000 supplied as a module, $105,000–200,000 built on site, and $130,000–250,000 all-in. Those are not competing estimates — they cover different things.

All eight jurisdictions carry a two-bedroom mid-spec range, which is what lets compare_states report money. The comparison ships with a warning attached, because the bases genuinely differ: QLD and WA are quoted all-in and so look more expensive than states quoted before site costs, which they are not.

Size and specification grid

23 ranges spanning studio to three bedrooms and basic to premium:

Size is a band, and bedrooms carries the natural key. Sources quote "1 bedroom, 45–60 sqm" — the market segments on bedroom count and a size range follows. The original dwelling_size_sqm forced that into a point value, inventing a precision no source claimed; it is now size_min_sqm / size_max_sqm plus bedrooms.

Two facts a budget estimator must not get wrong, both returned on every call:

• Cost does not scale with floor area. Kitchen, bathroom and service connections are near-fixed, so per-sqm cost rises as the dwelling shrinks. A studio is not half a two-bedroom at half the size, and a $/sqm × area estimator will be wrong at the small end.

• A price for an illegal size is worse than no price. A three-bedroom around 90 sqm exceeds the secondary dwelling cap in NSW, VIC and TAS (60 sqm) and in Brisbane (80 sqm). Only the ACT permits 90 sqm outright. The three-bedroom rows are priced because the market prices them, not because they can be approved as granny flats — the tool says so, and points at the regulation module.

A migration bug worth remembering

Changing the natural key from size to bedrooms orphaned every pre-existing row. The first migration backfilled size_min/size_max but not bedrooms, so the old rows fell outside the new key: the seed's upsert stopped matching them and inserted duplicates alongside instead of updating, silently doubling the table.

Two fixes, both in MODULE_MIGRATIONS: the backfill now sets bedrooms too, so a database migrating for the first time never orphans anything; and a repair statement deletes rows that have NULL bedrooms and a keyed equivalent superseding them — a row with genuinely unknown bedrooms and no sibling is left alone. The general lesson: when a natural key changes, the migration has to backfill every column the new key touches, or the upsert silently stops being an upsert.

Two rows are worth reading before trusting the label over the detail:

• SA covers design fees, slab, construction, fit-out and both consents, but excludes utility connections ($6,000–15,000 separately). None of the three cost_basis values fits exactly; the includes / excludes arrays carry what the label cannot.

• NT is structurally, not cyclically, more expensive: cyclone-rated construction for 316 km/h wind, mandatory air conditioning and termite barriers, freight, and trades at 110–135% of Sydney rates. Those drivers are recorded as NT-scoped rows in cost_site_works_items with no dollar amounts — confirmed to exist, unresearched in size.

Which exposed a bug worth keeping in mind for any future total: unpriced rows sum to zero, so a naive total silently understates by exactly the items nobody has costed. site_works_total now counts them, names them, and labels the total a floor.

What the second module taught us about the architecture

The multi-module design held, but not unchanged. Three things transferred intact: the <module>_<subject> naming, the three-way NULL semantics, and natural-key upserts. Two things did not:

• data_status is necessary but not sufficient. It answers "has anyone researched this?" Cost data needs a second, orthogonal axis: a builder's advertised price is fully researched and still the least reliable number available, because the figure is marketing. source_type (builder_advertised / industry_estimate / market_survey) carries that, and costs.py renders it into a sentence a consumer can relay. Regulation never needed it — its source was always the instrument itself.

• UNIQUE needs NULLS NOT DISTINCT. The regulation keys had no nullable columns. Cost keys do: a national figure has no state, a statewide one has no region. Under Postgres's default handling every such row is distinct, so the upsert would insert duplicates forever instead of updating.

Two new integrity rules came with the module: an inverted range (low > high) is rejected, because it produces a plausible-looking answer with the numbers the wrong way round; and equal bounds are accepted, because a fixed price is legitimate.

Planned modules

• Finance — construction loan structures, per-lender policy, progress payment schedules, current rates.

• Supplier — suppliers, product lines, specifications, certifications, reviews.

• Contract — standard clauses, variation and delay provisions, common disputes.

• Construction — lead times, transport and craneage, install sequence, typical causes of delay.

Setup

Requires PostgreSQL 14+ and uv.

uv sync

Copy .env.example to .env and set DB_PASSWORD to your PostgreSQL password. .env is gitignored and must never be committed; db.py is the only place credentials are read, and every script imports from it.

uv run setup_db.py          # create the database, tables, migrations, constraints
uv run insert_rules.py      # seed the state-level granny flat rules
uv run insert_lga_rules.py  # seed the council-level rules
uv run insert_cost_ranges.py # seed the cost module
uv run query_rules.py       # read them back

All four are safe to re-run. setup_db.py creates only what is missing and applies migrations that are no-ops once current; the seed scripts update existing rows in place instead of duplicating them.

Tests

uv run pytest                    # everything
uv run pytest -m "not protocol"  # skip the subprocess tests (faster)

96 tests against the live development database. Anything a test writes is marked and purged by the conn fixture, so a failure cannot leave the knowledge base in a state where a later query returns invented data.

The suite asserts guardrails, not numbers. Costs and rules change as research continues; a test pinned to $180,000 would break on every legitimate update and teach the next person to ignore failures. What must not change is that a not_researched field is never presented as a fact, that a price never arrives without its basis, and that Queensland is never silently dropped from a ranking.

Verified by mutation: collapsing not_researched into not_applicable, making every NULL read as no_rule_at_this_level, and dropping site works from the cost payload are each caught by a failing test. A suite that passes but survives those would be worse than none, because it would look like protection.

MCP server

mcp_server.py exposes the knowledge base over the Model Context Protocol (stdio transport, built on the official mcp SDK):

uv run mcp_server.py

The estimator

estimate_budget is the first tool that composes the two modules rather than reading one. It takes the block's conditions (sloping_site, reactive_clay_soil, services_over_15m, separate_vehicle_access, separate_tenancy, site_not_flat_or_clear) and returns a range with the applicable site works folded in.

Two ways it could be confidently wrong, both guarded:

• Double-counting. Adding site works to a turnkey_incl_site quote inflates it by tens of thousands; omitting them from turnkey_excl_site or base_module understates it by the same. BASIS_NEEDS_SITE_WORKS decides, and the response says which happened and why. On the current data NSW, QLD and WA are quoted all-in and get nothing added; VIC, SA, TAS, ACT and NT do.

• Pricing something that cannot be built. Every estimate carries a size_legality verdict checked against the state's cap — within_the_cap, over_the_cap, or cannot_check_at_state_level for Queensland, where the cap lives with the council. A NSW three-bedroom returns a price and the fact that 100 sqm exceeds the 60 sqm cap.

A combination with no data returns found: false and lists what is on record, rather than scaling a neighbouring size or spec into an invented figure. Unrecognised site conditions are reported back, because silently dropping one produces an estimate that looks complete and is not.

Site works carry a machine-readable trigger_condition alongside the prose applies_when, so the estimator selects them from the data rather than from a mapping hardcoded in Python — a new item becomes selectable by being inserted.

The server's contract is that a null is never a fact. Every null comes back with a why_missing entry naming one of the three reasons above, and any field whose value is genuinely unknown is also listed in must_not_state. A model relaying an answer has to work against the payload to invent a figure, rather than merely failing to notice a blank. Day counts always travel with their _basis, and every rule carries source and last_verified.

rules.py holds the read layer and the why_null logic. Both the CLI and the MCP server go through it, so the two can never disagree about what a blank cell means — this is the one piece of logic worth centralising, because the failure it prevents is a fabricated regulatory answer. costs.py is the cost module's equivalent and reuses rules.why_null rather than reimplementing it.

The cost tool deliberately has no way to return a build price on its own. Site works come back on every call, with their total, because quoting a base price without them is precisely how this market misleads people.

To register it with an MCP client, point the client at uv run mcp_server.py with this directory as the working directory. The server reads credentials from .env like every other script.

Querying

uv run query_rules.py          # every state
uv run query_rules.py NSW      # one state
uv run query_rules.py nsw vic  # several

Conventions for adding a module

1. Name the table <module>_<subject>. Use the module prefixes listed above; add a new prefix only for a genuinely new domain, and document it here. Table and column names are snake_case, table names plural where the row is one of many (..._rules, ..._lenders).

2. Put units in the column name. max_floor_area_sqm, fallback_max_days, deposit_pct. A bare area or days column will eventually be misread.

3. Every fact-bearing table gets source and last_verified. Regulations, rates and prices all go stale. A row without provenance cannot be trusted by the MCP server and should not be inserted.

4. Scope by jurisdiction where it varies. Add state (and lga if the rule operates at council level) rather than storing a national average that is wrong everywhere.

5. Distinguish NULL from zero and from false. NULL means not applicable or not yet researched; encode "no permit needed" as default_permit_required = false, not as a missing row.

6. Add the DDL to MODULE_TABLES in setup_db.py so a fresh clone builds the whole schema in one command. Keep the DDL CREATE TABLE IF NOT EXISTS.

7. One seed script per module subset, named for what it loads (insert_rules.py, later insert_lender_policies.py). Make it idempotent by keying on the table's natural key so re-running never duplicates data.

8. Import connections from db.py. Do not build a connection string or read os.environ anywhere else.

9. Add tests with the module, not after it. At minimum: the constraints reject what they exist for, the seed is idempotent, and every NULL the module can produce resolves to the right one of the three reasons. Assert guardrails rather than figures, so the suite survives research.

10. Give every table a natural-key UNIQUE constraint and register it in MODULE_CONSTRAINTS in setup_db.py. Seed scripts then use ON CONFLICT (...) DO UPDATE, which is atomic and safe to re-run. Enforcing the key in the database rather than in Python matters because the MCP server, bulk imports and manual SQL all write to these tables too, and none of them go through the seed scripts.

Reading a NULL

A blank cell is never self-explanatory, so two columns carry the reason:

data_status is one of verified, partial (some fields still in unresearched_fields) or no_rule_at_this_level. The distinction matters most to the MCP server: telling a Queensland user "no permit required" because a column was NULL would be a fabricated answer, and this is what stops it.

Day counts

fast_track_days and fallback_max_days are meaningless without *_days_basis, which is business or calendar. NSW, VIC, WA and TAS count calendar days; SA, QLD and ACT count business days. 35 business days is roughly 49 calendar days, so mixing them silently breaks any duration arithmetic. A CHECK constraint refuses a day count whose basis is missing.

Where a jurisdiction publishes two periods, the longer one is stored and the shorter is noted in source — better to under-promise on a timeline. NT stores no figure at all because the Development Consent Authority decides at monthly meetings rather than within a set period.

Where a figure is assembled from published components rather than quoted whole, source shows the arithmetic so a reader can audit it. South Australia is the example: its 12 and 55 business days are each a sum of a verification period, an assessment period, and a decision-issuing period, plus an extension. Both figures replaced an earlier single value of 25 that had been attached to the wrong pathway — 25 is the performance assessed base, not the deemed-to-satisfy period. Attaching a real number to the wrong pathway is the same class of error as inventing one, and it is harder to spot.

Known schema gaps

Recorded rather than fixed, so the next person does not mistake them for oversights. Each needs a schema change, not just more rows:

• No zone dimension. Victoria's exemption is written per zone (RGZ, GRZ, NRZ, plus rural zones), and the 300 sqm lot threshold applies to those residential zones specifically. WA, SA, TAS and NT all set minimum lot size and sometimes maximum floor area per zone too, which is why those cells are blank. Moreton Bay is currently modelled with one row per lot-size band, which works but would not survive a council that varies by zone and by band.

• "Researched, but no published figure" has no encoding. NT's missing decision period is recorded as verified with an explanation in source, because it is neither unresearched nor truly inapplicable. If this case recurs it deserves its own data_status value.

• One row cannot express a threshold split. Victoria is really two rules: over 300 sqm the permit exemption applies; at or under 300 sqm a permit is always required and Clause 54 / VicSmart applies (Amendment VC282, in operation 8 September 2025). This should become a second row with its own rule_type once the sub-300 sqm pathway is researched.

• Pending changes are recorded only as prose. Tasmania's SPP amendment 01/2026 would raise 60 sqm to 90 sqm but is not gazetted; that fact currently lives in a sentence inside source. Anything that needs to answer "what is changing soon" needs real columns.

• Council coverage is partial, and absence is ambiguous. The convention is that a missing council row means the state rule applies — but for a council nobody has researched, it equally means "unknown". The MCP server says so in words on every response; the schema cannot yet distinguish the two.

• Only negative conditions are modelled. excluding_conditions captures what disqualifies a site. Victoria also imposes positive conditions — no more than one existing dwelling on the lot, only one small second dwelling, and no reticulated natural gas connection — which have nowhere to live yet.

• One row cannot express a threshold split. Victoria is really two rules: over 300 sqm the permit exemption applies; at or under 300 sqm a permit is always required and Clause 54 / VicSmart applies (Amendment VC282, in operation 8 September 2025). This should become a second row with its own rule_type once the sub-300 sqm pathway is researched.