User Manual & Demo Guide

Application: Road Maintenance (DSLCore) Audience: Demonstration — presenters and viewers URL: http://localhost:5023 Version: 1.0 (2026-07-16)

1. What You Are Looking At

Road Maintenance is a working prototype generated with DSLCore from the data model of a routine road maintenance guideline — the kind of document that normally lives as a several-hundred-page PDF. The guideline's reference structures (defect codes, intervention rules, maintenance activities) and its operational workflow (inspect → identify defect → assess → prioritise → plan → deliver → verify → close) have been turned into a navigable application.

The build path, and the point of the demo:

Guideline document
  → data model (25 models, written as a ~450-line DSL text file)
  → code generation (database, screens, forms, navigation — all generated)
  → running application with realistic demo data

Nothing in the user interface was hand-built for this application. The lists, forms, drill-downs, lookups and dashboard are the standard DSLCore interface, driven entirely by the schema definition. What is specific to this application is the domain model and the demo dataset, which follows several defects through their complete lifecycle.

The three layers of the model

The design's key idea: intervention levels and response times are not properties of a defect type. They vary by defect sub-type × road category × corporate priority, so they live in a separate Intervention Rule table. A pothole on a major highway triggers a 2-day response; the same pothole on a rural feeder road allows 7 days.

2. Getting Started

Starting the application

From the project root:

python server/run.py road_maintenance

Then open http://localhost:5023 in a browser. (Alternatively, use the control panel at http://localhost:5000 to start and stop apps.)

Signing in

The app uses email + PIN authentication. A demonstration account is pre-configured:

Enter both on the sign-in screen and press Sign In. Developer accounts registered in the shared user store also work across all apps. To sign out, use the logout control in the header.

The dashboard

After signing in you land on the dashboard. It shows:

• Category cards — the six functional areas (Network, Inspections & Observations, Defect Log & Backlog, Work Delivery, Activity Catalogue, Reference Library), each listing its models with record counts.
• Quick actions — shortcuts: View Defects, New Inspection, View Work Orders.
• System stats — active model count, total records, system status.

The ☰ menu button (top left) opens the sidebar from any screen. The sidebar is an accordion grouped the same way as the dashboard categories; the title in the header returns you to the dashboard.

3. Working With Records (the generic DSLCore interface)

Every model in the application uses the same screen pattern, so once you have seen one list you have seen them all. This uniformity is itself a demo point — none of these screens were individually built.

List pages

Open any model from the sidebar (e.g. Inspections & Observations → Defect Observation). A list page has:

• ☰ Actions menu (top-left of the table) — the single control point. Always offers Create New, Filters, Reports, Settings and Adhoc Query; once a row is selected, a Selected Record section appears with View (inline/modal/slider), Edit, Delete and — for deleted rows — Restore (deletes are soft; nothing is ever physically removed, an audit-friendly behaviour worth mentioning in a demo).
• Search & filters — open ☰ Actions → Filters: a Quick Search box that searches across all fields, plus per-field advanced filters; active filters are remembered.
• Sorting — click any column heading to sort; click again to reverse.
• Pagination — << < > >> controls with a typeable page number and a page-size selector (10/25/50/100 per page).

Selecting and drilling down

• Click a row to select it. Two things happen: the Selected Record actions (Edit/Delete/View) become available in the ☰ Actions menu, and related-data tabs load underneath the table — one tab per child table. For example, selecting an Inspection shows a tab of the Defect Observations recorded during it; selecting a Defect Observation shows tabs for its Assessments, Log Entries, Planned Work and Closures.
• Child tables nest: you can select a row inside a child tab and drill a further level down (parent → child → grandchild). Selections clear automatically when you change the parent row, so the levels never show stale data.
• Ctrl+Click a linked value (e.g. the road section name shown on a defect row) to open the related record in a read-only slide panel without leaving the page. This works in parent and child tables alike.

Forms, lookups and dropdowns

Create or Edit opens the record form:

• Fields with a fixed set of values (statuses, priorities, work classes) render as dropdowns populated from the schema's enumerations.
• Foreign-key fields (e.g. choosing the Road Section for an inspection) open a lookup modal with its own search box. Roads display as "18A - Western Highway" and sections as "18A-01 - Western Hwy — Town Reach" — composed display labels defined in the schema, not hand-coded.
• Required fields are marked; validation happens on the form and is enforced by the database.

Documentation portal

/docs serves the project's technical documentation portal (no login required) — useful if a technical audience asks how the system works.

4. The Domain in Five Minutes

Talking points before running the storylines:

Defect classification. Two-character defect codes (PH Pothole, CR Cracking, ED Edge Break, GD Guardrail Damage…) subdivide into four-character sub-codes that carry the measurable definition — PH01 is a pothole under 300 mm diameter, PH02 is 300 mm or larger.

Corporate priorities. Six priorities drive response:

Intervention rules (IL/RT). Each rule binds a defect sub-type to a road category and priority, and defines the initial intervention level (when the defect enters the log), the upper level, the response time, and the weightings. Priority score = corporate weighting × field weighting.

The lifecycle. A defect observation moves through statuses:

Observed → Assessed → Logged → Planned → WorkOrdered → InProgress
        → Completed → Verified → Closed
   (or → Monitoring, when below intervention level)
   (or → Backlog, when not rectified within the work cycle)

Repair choice. A defect doesn't map to one repair. The Valid Defect Activity table records every permitted rectification per defect sub-type, flagged preferred / temporary / permanent / emergency-only. The system knows a large pothole can be heavy-patched (permanent, preferred) or coldmix-filled (temporary make-safe) — and the demo data uses both on the same defect.

5. Demo Storylines

The seed data was written as connected stories, not random rows. Each storyline below gives the navigation path and what to point out. Dates are relative to a seed date of 16 July 2026.

Storyline A — A pothole's complete lifecycle ★ (the centrepiece)

One defect followed from discovery to verified closure.

1. Sidebar → Inspections & Observations → Inspection. Select INS-2026-0032 — the routine monthly drive-over of Western Highway's Town Reach section, ~5 weeks ago.
2. In the Defect Observation child tab, find OBS-2026-0201: a 450 mm pothole, 80 mm deep, in the northbound wheelpath at the Boundary Creek bridge approach. Note hazardous_suspected is flagged and status is already Closed — we're about to see why.
3. Open the Defect Observation list and select OBS-2026-0201 to get its own child tabs:
4. Defect Assessment — assessed the same day against the PH02 × Category 1 × Safety intervention rule: diameter 450 mm exceeds the 300 mm initial intervention level. Corporate weighting 10 × field weighting 8 = priority score 80. Response due in 2 days.
5. Defect Log Entry — entered the defect log, status Fixed (dealt with inside the period).
6. Planned Work — Heavy Patching (activity 103), 4.5 m² at $185/m², estimated $832.50.
7. Defect Closure — closed as Rectified, restoration verified.
8. Sidebar → Work Delivery → Work Order. Select WO-2026-0140. Read the description: a coldmix make-safe was applied the day of inspection (temporary repair) and the heavy patch followed (permanent repair) — the two repair options from the Valid Defect Activity table used in sequence. Its child tabs show:
9. Work Execution — DP Crew 2, 4.5 m² completed, $832.50, with a note that base moisture was found (feeding the next programme review).
10. Completion Inspection — Pass: patch flush, quantity verified, and a follow-up inspection scheduled.
11. Close the loop: Inspection → INS-2026-0044 is that follow-up — a planned walk-over next week to check the patch after three months in service. The lifecycle is circular: work generates future inspection.

Storyline B — Priority 1 Hazard: emergency guardrail repair

What mandatory response looks like, still in flight.

1. Defect Observation → OBS-2026-0205: guardrail struck and deformed over 12 m below the lookout on the Range Ascent, found during INS-2026-0035.
2. Its assessment is Priority 1 — Hazard: barrier ineffective above a high embankment. Score 100, response time 24 hours, and note the assessment reason records that field weighting is not applied for Priority 1 — mandatory action.
3. Work Order WO-2026-0143 was issued same-day as an emergency order. Status InProgress: the execution record shows 6 of 12 metres of rail fitted, the rest on backorder, the site signed and made safe. Real maintenance is messy; the system tracks partial completion honestly.

Storyline C — The backlog: when funding runs out

The guideline's backlog concept as a workflow, not a boolean.

1. Defect Observation → OBS-2026-0202: 40 m² of crocodile cracking through the school-zone frontage, pumping fines in wet weather. Status Backlog.
2. Its Defect Log Entry is CarriedForward — not fixed within the period.
3. Sidebar → Defect Log & Backlog → Defect Backlog: the backlog record states why — routine budget exhausted, and the area qualifies for the next reseal preparation programme (reference RESEAL-2027-DP-04). It holds a review date and target resolution date, because backlog defects must be reassessed — they deteriorate between cycles.
4. Planned Work shows the corresponding entry with status Deferred and work class Programmed — the audit trail of the deferral decision.

Storyline D — Below intervention level: monitoring

1. Defect Observation → OBS-2026-0210: worn centreline through the estuary floodway. below_initial_intervention and monitoring_only are both true; status Monitoring. No assessment, no log entry — the rules say it doesn't warrant action yet, so the system records it and waits. Point out the observation note: bundle with the next reseal.

Storyline E — The reference library (the guideline as data)

Show that the rules driving Storylines A–D are themselves ordinary, editable records.

1. Reference Library → Intervention Rule. 14 rules. Find the two PH02 rows: Category 1 = 2-day response; Category 3 = 7-day response. Same defect, different road, different obligation — the reason this is a table, not a field on the defect type.
2. Activity Catalogue → Valid Defect Activity. Filter or scan for PH02: heavy patching (preferred, permanent) and pothole patching (emergency-only, temporary) — the options exercised in Storyline A.
3. Activity Catalogue → Maintenance Activity. Select 103 Heavy Patching; its child tab shows the Activity Standard: restoration standard, preparation and step-by-step work operations, versioned and dated. In a full deployment, every activity page of the guideline becomes one of these records.
4. Closing line: a new edition of the guideline is a data load, not a software release.

6. A Suggested 10-Minute Demo Script

7. Reference

7.1 Menu map

7.2 Model glossary (one line each)

• District / Network / Road / Road Section / Road Location — the asset hierarchy, from administrative district down to a chainage-referenced spot with GPS coordinates.
• Road Category — traffic-based classification (CAT1 major highway … CAT4 minor access) that intervention rules key on.
• Maintenance Element — guideline chapter groupings (Sealed Surfaces, Drainage, Road Furniture…), each owning an activity-number range.
• Maintenance Activity — a three-digit standard treatment (101 Pothole Patching, 502 Guardrail Repair…).
• Activity Standard — the versioned "how" of an activity: restoration standard, preparation, operations.
• Defect Type / Defect Sub Type — two-character code and its measurable four-character subdivisions.
• Corporate Priority — the six-priority scheme; priorities 1–2 are mandatory-action, 3–6 are weighted/scored.
• Intervention Rule — IL/RT rule per sub-type × road category × priority: intervention levels, response time, weightings.
• Valid Defect Activity — permitted repairs per defect sub-type, with preferred / temporary / permanent / emergency flags.
• Unit Of Measurement — shared units reference (EACH, LM, M2, M3…).
• Inspection — a scheduled, complaint, follow-up or joint drive-over / walk-over of a road section.
• Defect Observation — one defect found in the field, with measurements and a lifecycle status.
• Defect Assessment — the scoring event: rule applied, weightings, calculated score, response due date.
• Defect Log Entry — membership of the period's defect log (defects that reached intervention level).
• Defect Backlog — logged defects not rectified in the cycle, with reason, review and target dates.
• Planned Work — costed intention: activity, quantity, rate, dates, work class.
• Work Order — the instruction to do it, with required/actual dates and emergency flag.
• Work Execution — what the crew actually did: quantities, cost, weather, traffic control.
• Completion Inspection — verification against the restoration standard (Pass / ConditionalPass / Fail).
• Defect Closure — the terminal record tying observation, work order and verification together.

7.3 Seeded demo records inventory

7.4 Administration notes

• Reset the demo data: stop the server, delete apps/road_maintenance/data/road_maintenance.db, start the server (tables auto-create), then run python apps/road_maintenance/scripts/seed_data.py.
• Regenerate after schema changes: edit apps/road_maintenance/schema/road_maintenance.dsl, run python -m codegen.cli all road_maintenance, restart the server.
• Users: app users are managed per-application in the shared auth store (/admin/users/, developer login required). The demo@dslcore.net account is scoped to this app only and can be deactivated there.
• Phase 2 scope (designed, not yet built): JMRA needs assessment, claims and schedule rates, permits/approvals, resource requirements.