Operations Manual

CityCLE·RRTS

Road Repair Tracking System — City of Cleveland, Division of Streets. Field intake, condition scoring, crew routing, photo documentation, and program reporting for pothole, panel, brick, and full-block rehabilitation work.

Prepared by The FixOurStreets216 Project · Cleveland, Ohio

Project

CityCLE·RRTS

Sheet

OM-001

Scale

N.T.S.

Date

2026-07-25

DOC NO. FOS216-RRTS-OM-001 · REV A · DOCUMENTS BUILD: CityCLE_Road_Repair_Tracker.html · STATUS: ISSUED FOR USE

1.0System Overview

CityCLE·RRTS is a single-file, browser-based tracking application for the Cleveland Division of Streets. It holds the full road repair workflow — intake through verification — in one screen, with a live map, a searchable registry, crew routing, and before/after photo documentation.

1.1Purpose

The system exists to answer four questions at any moment of a work week:

What is broken, and how badly? Every defect carries a Pavement Condition Index score, a distress classification, and a measured area.
Who is fixing it, with what? Each record is bound to a repair method and, once dispatched, to a named crew.
Where should the truck go next? The routing engine sequences selected repairs from the service yard.
Can we prove it was fixed? Paired condition and repaired photographs are stored against each repair ID.

1.2Scope

The application covers two parallel programs that share one map:

Spot Repair Program

Repairs

Discrete defects — potholes, joint spalls, brick displacement, base failures. Tracked individually with coordinates, PCI, area in square yards, and a repair method.

Residential Road Rehab

RRRP

Full-block rehabilitation measured in lane miles rather than square yards. Tracked as scheduled blocks with a percent-complete progress bar and a capital cost.

Spot repairs live on the map. RRRP blocks are managed as a scheduling list and roll into program analytics, but they carry no coordinates and therefore do not appear as map pins.

1.3Intended users

Role	Primary tabs	Responsibilities in the system
Field inspector	Settings, Map	Creates repair records, captures coordinates and condition photos, assigns initial PCI, area, and distress type.
Dispatcher	Map, Routes, Crews	Triages by priority, builds and optimizes daily routes, assigns crews, moves records to Dispatched.
Crew lead	Map, Routes	Works the numbered route, updates status in the field, captures the repaired photo, sets completion date.
Program manager	RRRP, Analytics	Manages the rehabilitation block schedule, monitors lane miles and budget, reviews ward distribution.
Administrator	Settings	Loads and clears datasets, manages photo storage, configures map behavior, runs exports.

1.4Operating model — read this before anything else

Critical — Session-based data

Repair records, RRRP blocks, crews, and routes exist only in browser memory. They are not written to disk, a server, or local storage. Closing the tab, refreshing the page, or a browser crash destroys all of them.

On every page load the application automatically replaces whatever was there with the built-in demonstration dataset — 40 sample repairs and 8 sample RRRP blocks. Any manual entry not exported before reload is unrecoverable.

Photographs are the sole exception. They persist in the browser's IndexedDB store and survive reloads. See §9.

This makes the export step operationally mandatory rather than optional. Treat CSV or GeoJSON export as the end-of-shift save, described in SOP-12 (§7.12). Until a persistence layer is added (§14), the exported file is the record of work.

1.5System identification

Application title	CityCLE·RRTS — Road Repair Tracking System
Owning unit	City of Cleveland, Division of Streets
Delivery file	CityCLE_Road_Repair_Tracker.html
Record ID format	RRTS-0000 (seed) · RRTS-<epoch-ms> (manual)
Photo datastore	IndexedDB · CityCLE_RRTS_v2 · store "photos"
Prepared by	The FixOurStreets216 Project

2.0Technical Baseline

2.1Runtime requirements

Requirement	Minimum	Notes
Browser	Chrome/Edge 90+, Safari 14+, Firefox 88+	Requires IndexedDB, Canvas, Geolocation, and ES2020 optional chaining.
Network	Required	Mapping library and tiles are fetched remotely. See §2.2.
Screen	1280 × 800 recommended	The three-column map layout is fixed-width; below roughly 1100 px the side panels crowd the map.
Storage	~50 MB free	IndexedDB quota for photographs. Roughly 250–400 compressed images.
Permissions	Location, Camera	Optional. Prompted on first use of My Location or a camera capture button.

2.2External dependencies

The application is a single HTML file, but it is not fully self-contained at runtime. Four external services are called:

Service	Host	Used for	Failure mode
Leaflet 1.9.4	unpkg.com	Map engine and stylesheet	Blocking Map pane stays blank; all map functions fail.
OpenStreetMap	tile.openstreetmap.org	Default street basemap	Degraded Grey tiles; pins and routing still work.
Esri World Imagery	server.arcgisonline.com	Satellite basemap toggle	Degraded Satellite view blank; revert to street.
Google Street View	google.com/maps	Street View deep link in detail panel	Minor Link fails to open.

Deployment consideration

On a hardened municipal network these hosts are frequently blocked. Confirm allowlisting for unpkg.com and tile.openstreetmap.org before rollout, or vendor Leaflet into the file and point tiles at a City-hosted service.

2.3Data persistence model

Data class	Storage	Survives reload?	Survives browser clear?
Repair records	JS array — lots[]	No	No
RRRP blocks	JS array — rrrpBlocks[]	No	No
Crews	JS array — crews[]	No	No
Route sequence	JS array — routeStops[]	No	No
Map toggles / filters	JS objects — MS, AF	No	No
Photographs	IndexedDB	Yes	No

Because photographs persist but their parent records do not, a reload leaves photos in storage whose repair IDs no longer exist in the registry. These orphaned images consume quota and are not visible in the Photos tab, which filters to records currently loaded. Clear them from Settings → Photo Storage → Delete All Photos when they accumulate.

2.4Deployment

The file is static and needs no build step or server-side runtime.

GitHub Pages — commit the HTML to a repository, enable Pages on the branch, and serve. Rename to index.html to serve at the repository root.
Netlify — drag the file into the deploy panel, or connect the repository for continuous deployment.
Local / offline-adjacent — open the file directly from disk. Geolocation and camera capture require a secure context, so file:// restricts those two features in most browsers. Serve over HTTPS for full functionality.

Note — IndexedDB scoping

Photo storage is bound to the exact origin. Moving the application from a Netlify preview URL to a production domain, or from file:// to HTTPS, presents a fresh empty database. Photos do not migrate. Fix the production URL before field crews begin documenting work.

2.5Security posture

State plainly what the system does and does not provide, so it is deployed with appropriate expectations:

No authentication. Anyone who can reach the URL has full read and write access, including Clear All Data.
No audit trail. Status changes, edits, and deletions are not logged or attributed to a user.
No concurrency control. Two people working simultaneously each hold a private session; their work does not merge and cannot be seen by the other.
Photographs never leave the device. They are stored locally and are not transmitted anywhere, which is good for privacy and bad for backup.
Geolocation is used transiently to populate coordinate fields; it is not tracked or stored beyond the record.

This posture is appropriate for a single-operator planning and field-documentation tool. It is not appropriate as a system of record for work orders that carry contractual or legal weight without the additions in §14.

3.0Interface Map

3.1Global header

The header bar persists across every tab and carries the system identifier, the tab strip, and four live counters.

Element	Behavior
● Live	Static indicator that the interface is running. It does not reflect a server connection.
n Open	Count of repairs whose status is exactly `open`. Excludes dispatched and in-progress work.
n RRRP	Total RRRP blocks loaded, regardless of status.
n Repairs	Total repair records in the session, ignoring all active filters.

Note

Header counters report the full dataset. The count beside "Repair Registry" on the Repairs tab reports the filtered subset. A mismatch between the two is expected whenever a filter is active, not a defect.

3.2Tab reference

Tab	Layout	Primary function	Refreshes on entry
🗺 Map	Filter sidebar · map · detail panel	Spatial triage, record selection, inline editing, photo capture	Recalculates map size
🛣 Repairs	Toolbar · full-width table	Tabular registry of all filtered records; export entry point	Registry table
🏘 RRRP	Entry form · block cards	Full-block rehabilitation scheduling and progress	Block list and summary
⚡ Routes	Settings · sequenced stop list	Depot config, algorithm choice, route build, task order export	Route panel
👷 Crews	Entry form · crew cards	Crew roster, specialty, shift, assignment load	Crew cards
📊 Analytics	Full-width dashboard	Program distributions, cost, PCI, ward concentration	All charts
⚙ Settings	Admin panel · new repair form	Data management, map options, photo storage, and record intake	Nothing

Orientation

New records are created on the Settings tab, not the Map or Repairs tab. This surprises most first-time users. The intake form occupies the right two-thirds of Settings; the left column is administration.

3.3Detail panel sub-tabs

The right-hand panel on the Map tab has four sub-tabs, active once a record is selected.

Sub-tab	Contents
Info	Read-only record summary — address, ward, PCI bar, method, distress, area, cost, source, dates, crew, notes, photo pair, and action buttons (Add to Route, Edit, Delete, Street View).
Photos	Every record in the session that has at least one photograph, as an address-headed card with both slots. A workspace for catching up on documentation.
Edit	Editable fields — status, priority, surface, method, PCI, area, assigned crew, completion date, notes. Each change commits immediately on blur; there is no Save button.
Stats	A copy of the full Analytics dashboard, rendered in the narrow panel for reference without leaving the map.

3.4Map symbology

Each pin encodes four attributes simultaneously:

Visual channel	Encodes	Values
Pin fill color	Repair method	SP5E Kasi IR JCB Pro Saw Cut RRRP
Pin outline	Priority class	P1 P2 P3 — a white outline means the record is currently selected.
Blue override fill	Route membership	A pin turns solid blue when the record has been added to the active route, overriding its method color.
Purple corner dot	Photo present	Appears when at least one photograph is stored against the record.
White numeral	Route stop order	Shown only after Optimize Route runs, and only while Stop Numbers is enabled in Settings.

3.5Notifications

Confirmations appear as toasts in the lower right and clear themselves after 3.5 seconds. Color carries meaning: green confirms a completed action, amber signals a rejected or no-op action, red signals a deletion, and blue signals work in progress. Toasts are transient and are not logged — if a crew reports "it said something and disappeared," there is no history to consult.

4.0Data Dictionary

Every field carried by the system, its type, how it is populated, and whether an operator can change it after creation.

4.1Repair record

The core object. One instance per discrete defect.

Field	Type	Source	Editable	Definition
id	string	Auto / manual	No	Unique record key. Seed records use `RRTS-1000` through `RRTS-1039`. Manual entries default to `RRTS-<epoch-ms>` unless an ID is typed into the form. Photographs are keyed to this value.
address	string	Manual	No	Street address. `, OH` is appended automatically when absent. Only the portion before the first comma is shown in lists and route stops.
lat / lng	float	Manual / GPS / map pick	No	WGS-84 decimal degrees, 5 places (~1.1 m). Mandatory — a record cannot be created without them.
neighborhood	string	Seed only	No	Cleveland neighborhood name. Manual entries are hard-coded to `Manual Entry`.
ward	string	Derived from neighborhood	No	Council ward, looked up from the neighborhood table (§5.7). Manual entries receive `—`.
surface	enum	Manual	Yes	Pavement type: `asphalt`, `concrete`, or `brick`. Governs which distress vocabulary applies.
method	enum	Manual	Yes	Repair technique. Drives pin color, crew matching, and unit cost. See §5.1.
distressType	string	Manual free text	No	Defect classification. Free text, but should be drawn from §5.3. Defaults to `Unspecified`.
pci	integer 0–100	Manual	Yes	Pavement Condition Index. Defaults to 45 if left blank. Drives color coding and average-PCI reporting.
areaSY	integer	Manual	Yes	Repair area in square yards. Defaults to 20. Drives cost and labor estimates.
priority	enum	Manual	Yes	`p1`, `p2`, or `p3`. Defaults to P3 on the intake form. See §5.4.
status	enum	Auto `open`	Yes	Workflow state. New records always begin at `open`. See §5.5.
reportSource	string	Auto	No	Origin of the report. Manual entries are stamped `Manual Entry`; seed records draw from 311 Call, Crew Inspection, Resident Complaint, Ward Council, SeeClickFix.
requestDate	date	Auto — today	No	Date the record entered the system, ISO format.
estCompDate	date	Seed only	No	Target completion. Blank on manual entries and not exposed in the edit panel.
completedDate	date	Manual	Yes	Actual completion date, set by the crew at closeout. Independent of status — set both.
assignedCrew	string / null	Manual or route	Yes	Crew name. Set individually in Edit, or in bulk when a crew is chosen before optimizing a route.
inRoute	boolean	System	Indirect	Route membership. Set by Add to Route, cleared by Clear Route or removing the stop.
zone	string	Seed only	No	Geographic grouping used by the Zone Grouping routing algorithm. Manual entries receive `Custom`.
estimatedHours	float	Calculated	No	Labor estimate in hours. See §6.4.
costEst	integer	Calculated	No	Estimated cost in dollars. See §6.3.
notes	text	Manual	Yes	Free-text field conditions, utility conflicts, repeat-repair history.

Field discipline

Address, coordinates, distress type, and report source are write-once — they cannot be corrected through the interface. A typo in an address requires deleting the record and re-entering it. Verify these four before clicking Add Repair.

4.2RRRP block record

Field	Type	Required	Definition
id	string	Auto	`RRRP-<epoch-ms>` for manual entries, `RRRP-S001`… for samples.
street	string	Yes	Street and block range, e.g. E 116th St (Union Ave — St Clair Ave). The only mandatory field; the block is rejected without it.
ward	enum	No	Ward 1 through Ward 15. Defaults to `—`.
lm	float	No	Lane miles. Defaults to 0. Sums into program totals, so a blank here understates the program.
pci	integer	No	Current block PCI. Defaults to 45.
date	date	No	Scheduled start. Displays as `TBD` when blank.
method	enum	Auto	Rehabilitation technique. See §5.8. Defaults to Mill & Overlay.
cost	integer	No	Estimated capital cost. Defaults to 0 and sums into the program budget rollup.
status	enum	Auto	Always begins at `planned`. See §5.9.
pctDone	integer 0–100	Auto	Percent complete. Begins at 0; forced to 100 when status is set to Complete.
notes	text	No	Scope, drainage issues, utility conflicts, funding source.

4.3Crew record

Field	Type	Definition
id	string	Auto-generated key.
name	string	Crew designation. Mandatory. This string is the foreign key written into a repair's `assignedCrew` field — renaming a crew orphans its existing assignments.
spec	enum	Equipment specialty — SP5E, Kasi IR Patriot, JCB Pothole Pro, Saw Cut R&R, RRRP Paving, or Multi-Method. Advisory only; the system does not prevent assigning a crew to a mismatched method.
cap	integer 2–20	Crew headcount. Used as the denominator of the load bar on the crew card.
shift	enum	Day (6AM–2PM), Swing (2PM–10PM), or Night (10PM–6AM). Display only — it does not constrain scheduling.
color	hex	Assigned automatically from a six-color cycle for the crew avatar.

The load bar on each crew card shows assigned repairs against headcount. It is a rough visual of workload distribution, not a capacity model — one RRRP assignment and one pothole count identically.

4.4Photo record

Field	Type	Definition
id	string	The parent repair ID. One photo record per repair, holding both slots.
before	object / null	Condition photograph — `data` (JPEG data URL), `ts` (ISO capture timestamp), `name` (original filename).
after	object / null	Repaired photograph, same structure.

5.0Controlled Vocabularies

These are the fixed value sets the application recognizes. Entering values outside them — particularly in the free-text distress field — breaks filtering and reporting.

5.1Repair methods

Code	Method	Map color	Unit cost	Typical application
sp5e	Bergkamp SP5E	#FF8855	$2.50/SY	Truck-mounted spray injection for preventive surface treatment across large areas. Highest area, lowest unit cost — used on pavement still in fair condition.
kasi	Kasi IR Patriot	#19C3B2	$8.00/SY	Infrared asphalt recycling. Reheats and reworks existing material into a seamless joint-free patch. Best for utility cut restoration and settled prior repairs.
jcb	JCB Pothole Pro	#0099FF	$45.00/SY	Mechanized pothole excavation and repair. The workhorse for 311-driven reactive work.
scr	Saw Cut R&R	#A855F7	$85.00/SY	Saw cut, remove, and replace to full depth. Reserved for confirmed base failure, saturated subgrade, or repeat failures that lighter methods will not hold.
rrrp	RRRP Full Rehab	#FFCC00	$120.00/SY	Full block reconstruction under the Residential Road Rehabilitation Program. Escalation target when spot repair is no longer economic.

Escalation logic

The unit costs above form a natural escalation ladder — roughly 3×, 6×, 2×, 1.4× at each step. A location receiving a third JCB repair within a season is costing more than a single Saw Cut would have. Sample records flag this pattern in notes as "3rd repeat repair — escalate to SCR." Apply the same discipline to live records.

5.2Road surfaces

Code	Surface	Abbr.	Notes
asphalt	Asphalt — Hot Mix	HMA	Default when unspecified. The majority of the network.
concrete	Concrete — Portland Cement	PCC	Panel-based failure modes; repairs are typically panel-scale rather than area-scale.
brick	Red Brick	Brick	Historic streets. Repairs are frequently reset-and-relay rather than replacement, and may carry preservation constraints not modeled by the system.

5.3Distress types by surface

The distress field is free text, so this table is the standard rather than an enforced constraint. Use these exact strings so that search and reporting group correctly.

Asphalt (HMA)	Concrete (PCC)	Red Brick
Pothole	Joint Spalling	Brick Displacement
Alligator Cracking	Corner Break	Mortar Erosion
Longitudinal Cracking	Map Cracking	Brick Fracture
Rutting	Faulting	Heaving / Frost Uplift
Raveling	D-Cracking	Sand Base Washout
Surface Oxidation	Panel Settlement	Surface Depression

5.4Priority classes

Class	Label	Color	Operational definition
p1	Emergency	#FF4F6A	Active hazard to vehicles or pedestrians. Dispatch same day; overrides route optimization sequence.
p2	Urgent	#FFAA00	Deteriorating and likely to become a hazard. Schedule within the current work week.
p3	Routine	#00C97A	Programmed maintenance. Batch into efficient routes; no urgency constraint.

5.5Status lifecycle

Status	Meaning	Set by	Filterable
Open	Logged and triaged; no crew committed.	Automatic on creation	Yes
Dispatched	Assigned to a crew and placed on a route; work not yet started.	Dispatcher, Edit panel	Yes
In Progress	Crew is on site and working.	Crew lead, Edit panel	Yes
Complete	Physical work finished; repaired photo captured; completion date set.	Crew lead, Edit panel	Yes
Verified	Inspected and accepted after completion. The terminal state for normal work.	Inspector, Edit panel	Yes
Warranty	Repair failed within its warranty period and is being reworked at no additional cost.	Inspector, Edit panel	No

Known gap — Warranty is not filterable

The status filter row on the Map tab offers All, Open, Dispatched, In Progress, Complete, and Verified. There is no Warranty button. Warranty records are visible only under the All filter, and they are excluded from the "Completed" quick stat, which counts Complete and Verified only.

Until this is added (§14), track warranty work by typing warranty into the search box, which matches the status tag rendered in the registry, or by exporting to CSV and filtering there.

5.6Report sources

Source	Definition
311 Call	Resident report through the City's 311 service line.
SeeClickFix	Report submitted through the SeeClickFix civic reporting platform.
Crew Inspection	Identified by Division staff during patrol or while working an adjacent repair.
Resident Complaint	Direct contact to the Division outside the 311 channel.
Ward Council	Referred through a Council office.
Manual Entry	Applied automatically to every record created through the intake form, regardless of true origin.

Note

Because manual entries are all stamped Manual Entry, source attribution is lost for live intake. Until the intake form exposes a source selector (§14), record the true origin as the first line of the notes field — for example "311 #4471882" — so the CSV export carries it.

5.7Ward and neighborhood cross-reference

The system derives ward from neighborhood using this table. It also carries a default surface assumption per neighborhood, used when generating sample data.

Neighborhood	Ward	Predominant surface
Lee-Harvard	Ward 1	Asphalt
Slavic Village	Ward 3	Brick
Mount Pleasant	Ward 3	Asphalt
Old Brooklyn	Ward 4	Concrete
Kinsman	Ward 5	Asphalt
Buckeye-Woodhill	Ward 6	Asphalt
University Circle	Ward 6	Brick
Tremont	Ward 7	Brick
Ohio City	Ward 7	Brick
Hough	Ward 8	Asphalt
Glenville	Ward 9	Asphalt
Collinwood	Ward 10	Asphalt
St. Clair-Superior	Ward 10	Brick
Detroit Shoreway	Ward 11	Brick
Cudell	Ward 12	Concrete
Clark-Fulton	Ward 14	Asphalt
Brooklyn Centre	Ward 14	Concrete
West Park	Ward 15	Concrete
Kamm's Corners	Ward 15	Concrete

Coverage gap

The table omits Wards 2 and 13 entirely, and the neighborhood list is partial. Records whose neighborhood is not listed receive a randomly assigned ward in seed data, and manual entries receive —. Ward analytics are therefore indicative, not authoritative. Do not use them for Council reporting without correcting ward assignment in the exported CSV.

5.8RRRP rehabilitation methods

Code	Method	Application
mill-overlay	Mill & Overlay (2")	Mill the top two inches and place new surface course. For blocks with a sound base and surface-level distress. The default and the most common treatment.
full-depth	Full-Depth Reclamation	Pulverize and rebuild the full pavement section. For confirmed base failure. The most expensive treatment per lane mile.
microsurface	Micro-Surfacing + Overlay	Thin polymer-modified surface treatment. Preventive, for blocks not yet failed. Lowest cost per lane mile.
base-repair	Base Repair + HMA	Localized base reconstruction followed by hot mix. For blocks with isolated subgrade problems, often from water main breaks.

5.9RRRP block status

Status	Meaning	Effect on progress
Planned	Identified and costed; no date committed.	Progress remains as entered.
Scheduled	Date committed and resources allocated.	Progress remains as entered.
In Progress	Construction underway.	Update percent manually as work advances.
Complete	Block finished.	Forces progress to 100% automatically.

6.0Scoring & Derived Values

6.1Pavement Condition Index

PCI is a 0–100 condition score where 100 is new pavement. The system uses it for color coding, priority guidance, and program averages. It applies five color bands:

PCI range	Color	Condition	Indicated action
85 – 100	Green	Good	Preventive treatment only. Spray injection or nothing.
70 – 84	Dark green	Satisfactory	Preventive treatment; monitor.
50 – 69	Amber	Fair	Corrective treatment. Infrared or mechanized repair.
35 – 49	Orange	Poor	Structural repair. Saw cut and replace.
0 – 34	Red	Failed	Rehabilitation candidate. Escalate to RRRP.

PCI is entered by the inspector, not calculated by the system. Consistency between inspectors is the responsibility of the Division, not the application — establish a scoring reference before deployment or the analytics will reflect inspector variance rather than pavement condition.

6.2Priority derivation

The sample data generator derives priority from PCI as follows:

Condition	Assigned priority
PCI < 40	P1 — Emergency
PCI 40 – 64	P2 — Urgent
PCI ≥ 65	P3 — Routine

Manual entry differs

The intake form does not apply this rule — it defaults every new record to P3 — Routine regardless of the PCI entered. The inspector must set priority deliberately. A P1 hazard entered without changing the dropdown will sit in the routine queue.

Use the thresholds above as the manual standard, then override upward for any condition posing an immediate hazard irrespective of score — an eight-inch pothole in a travel lane is P1 even on a street scoring 70.

6.3Cost estimation

Estimated cost is area multiplied by a method unit rate. Two different calculations are in effect:

Seed records

Area × method rate

Uses the per-method rates in §5.1 — SP5E $2.50, Kasi $8, JCB $45, Saw Cut $85, RRRP $120 per square yard.

Manual entries

Area × $45

A flat JCB-equivalent rate is applied regardless of the method selected. Cost for manually entered SP5E or Saw Cut work is materially wrong.

Critical — Manual cost estimates are unreliable

A manually entered 500 SY spray-injection repair is costed at $22,500 when the method rate implies $1,250 — an 18× overstatement. A 40 SY saw cut is costed at $1,800 against a true $3,400.

Until this is corrected (§14), recalculate cost outside the system for any budget submission that includes manually entered records. The Analytics "Est. Cost" figure is trustworthy only for the seed dataset.

6.4Labor hour estimation

Manual entries calculate estimated hours as area × 0.05 — three minutes per square yard, or five hours for a 100 SY repair. Seed records instead draw from method-appropriate ranges:

Method	Seed hour range	Seed area range
Bergkamp SP5E	4 – 12 h	200 – 800 SY
RRRP Full Rehab	16 – 48 h	500 – 2,000 SY
Kasi IR / JCB / Saw Cut	0.3 – 4 h	10 – 100 SY

The same caution applies as for cost: the flat manual formula ignores method. Route hour totals that mix seed and manual records are approximate.

6.5Area measurement

Area is recorded in square yards and should reflect the repair footprint, not the defect footprint. Include the saw-cut margin, the feathering allowance, or the panel boundary as the method requires. A twelve-inch pothole in the middle of a panel may carry a nine square yard repair area if the whole panel is being replaced.

For concrete, count full panels. For brick, count the reset area including the perimeter courses needed to key the repair in. Consistency here matters more than precision — cost and hours both scale directly off this number.

7.0Standard Operating Procedures

Twelve procedures covering the full work cycle from session start to end-of-shift handoff. Each states its role, trigger, and steps. SOP-01 and SOP-12 are mandatory on every session because of the persistence model described in §1.4.

SOP-01Session initializationRole: Any · Trigger: Start of shift

Open the application URL. The map centers on Cleveland at zoom 12 and the demonstration dataset loads automatically.
Decide immediately whether you are working with real data or demonstration data. If real, go to Settings → Clear All Data and confirm. The map empties.
If resuming from a prior shift, import is not available — re-enter records from the exported CSV, or continue against a fresh set and reconcile the two files afterward. See §14 for why this is the current constraint.
Go to Crews and confirm the roster. Clearing data does not remove crews, but a reload does. Re-add any crew that is missing before dispatching.
Go to Settings → Photo Storage and note the photo count and storage figure. A large count against an empty registry indicates orphaned photos from a previous session.

Do not skip step 2

Working on top of the sample dataset is the most common operational error. Forty fictional repairs will appear in your exports, your ward counts, and your cost totals, and there is no flag distinguishing them from real records other than the RRTS-10xx ID range.

SOP-02Create a repair recordRole: Field inspector · Trigger: New defect identified

Go to the ⚙ Settings tab. The intake form is the right-hand column.
Leave Repair ID blank unless you are matching an external work order number. Blank generates a unique ID automatically.
Enter the street address. Include the house number and street name; the state suffix is added for you. This field cannot be edited later — check it now.
Capture coordinates by one of the three methods in SOP-03. Both latitude and longitude are mandatory.
Set Priority deliberately. The form defaults to P3 and will not raise it for you, whatever PCI you enter. Apply the standard in §6.2.
Set Road Surface, then Method. Surface determines which distress vocabulary applies; method drives crew matching and pin color.
Enter the Distress Type using the exact string from the §5.3 table for the surface you selected. Spelling variations fragment your reporting.
Enter PCI and Area. Blanks silently default to 45 and 20 respectively — both plausible enough that a missing value will not look wrong later. Enter real numbers.
Record the true report source as the first line of Field Notes, since the form stamps every entry as Manual Entry. Add condition detail, utility conflicts, and repeat-repair history below it.
Click + Add Repair to Tracker. A green toast confirms. Switch to the Map tab to verify the pin landed where you expect.

SOP-03Capture coordinatesRole: Field inspector · Trigger: During intake

Three methods, in descending order of accuracy for field work:

A · My Location — standing at the defect

Click 📍 My Location. Grant the browser location permission if prompted.
The button reads "Locating…" while the device resolves position, then fills both fields to five decimal places.
If it fails, a red toast appears and the fields stay empty — fall back to method B or C. Failures are normal indoors, in parking structures, and on desktop machines without GPS.

B · Pick on Map — working from the office

Click 📍 Pick on Map. The view jumps to the Map tab and a blue toast confirms pick mode is armed.
Zoom to the location. Switch to 🛰 Satellite if you need to identify the exact spot on the pavement.
Click once. The view returns to Settings with both coordinate fields filled.

Cancelling pick mode

There is no cancel button. Once armed, the next map click is consumed as a coordinate pick and the app returns to Settings. If you armed it by mistake, click any point, then correct the coordinates by hand or clear the form.

C · Manual entry

Type decimal degrees directly. Cleveland falls between roughly 41.39 and 41.60 latitude, and −81.53 to −81.88 longitude.
Longitude must be negative. A dropped minus sign places the pin in Central Asia; the pin will not appear in the Cleveland view and the record will look like it failed to save.

SOP-04Capture the condition photographRole: Field inspector · Trigger: Before work begins

Select the repair on the map, or find it in the sidebar list.
Scroll the Info panel to the photo pair. The left slot is amber and labeled Condition.
On a phone or tablet, click 📷 Camera to open the rear camera directly. On a desktop, click 📁 File to browse.
Frame the defect with a recognizable fixed reference in shot — a curb line, hydrant, or house number — so the after photo can be matched to the same position.
A blue "Processing…" toast appears while the image is resized, then a green confirmation. The thumbnail replaces the placeholder and a purple dot appears on the map pin.

Why this matters

The condition photo is the only durable evidence of pre-repair state. Because it persists in IndexedDB while the record itself does not, it will outlive an accidental page refresh — but only if it was captured before the refresh.

SOP-05Triage the open queueRole: Dispatcher · Trigger: Daily, start of planning

Go to the Map tab. Set the Status filter to Open.
Set the Priority filter to 🔴 P1. Every remaining pin requires same-day dispatch.
Work the P1 list first: select each record, confirm the method matches the distress and PCI using the ladder in §5.1, and correct it in the Edit sub-tab if not.
Switch to 🟡 P2 and review for clustering. Several P2 defects within a few blocks justify a route even when none is individually urgent.
Use the Method filter to check equipment balance. A day with twenty JCB records and no Kasi records is a single-crew day.
Reset filters to All before leaving the tab. Filters persist across tabs and silently constrain the CSV export scope and route building.

SOP-06Build and optimize a routeRole: Dispatcher · Trigger: Daily dispatch

On the Map tab, filter to the work you intend to dispatch — for example Status: Open, Method: JCB Pro, Priority: All.
Add stops one of two ways: select each record and click Add to Route in the detail panel, or go to Routes and click + Add Filtered to add the entire filtered set at once. Pins turn blue as they join.
On the Routes tab, confirm the Depot coordinates. The default 41.4775, −81.6794 is the Cleveland service yard; change it if dispatching from a satellite facility.
Choose an Algorithm per §8.1.
Select a crew in Assign Crew if you want the crew written onto every stop in one action. Leaving it as None means assigning each record individually later.
Click ⚡ Optimize Route. A minimum of two stops is required. The map draws a dashed orange line from the CITY YARD marker through the numbered stops.
Review the summary strip — stops, kilometers, hours, cost. If total hours exceed the shift, remove the lowest-priority stops with the ✕ button and re-optimize.
Click ⬇ Export Task Order CSV and issue the file to the crew lead.
Set each stop's status to Dispatched in the Edit panel.

Re-optimizing does not re-add removed stops

Removing a stop clears its route flag. Re-running Optimize sequences only what remains flagged. To restore a removed stop, select it again and click Add to Route.

SOP-07Manage the crew rosterRole: Dispatcher · Trigger: Roster change

Go to 👷 Crews.
Enter a Crew Name that identifies both the unit and its equipment, following the sample convention — Crew Alpha — SP5E. This string is written onto every repair the crew is assigned, so make it unambiguous and do not change it once assignments exist.
Set Specialty, Members, and Shift, then click + Add Crew.
Verify the new crew appears in the Assign Crew dropdown on the Routes tab.

Deleting a crew

Removing a crew card does not clear the crew name from repairs already assigned to it. Those records keep a name that no longer resolves to a roster entry. Reassign affected repairs before deleting the crew.

SOP-08Field execution and status updatesRole: Crew lead · Trigger: Arrival on site

Open the tracker on the field device and select the stop, either from the numbered route list or by searching the address.
Confirm the condition photo exists. If not, capture it now per SOP-04 — before any work starts.
Open the Edit sub-tab and set status to In Progress. The change commits on selection; there is no save step.
If actual conditions differ from the record, correct PCI, Area, or Method now and note what changed in the notes field. Discovering base failure under what was logged as a pothole is a method change from JCB to Saw Cut.
Use ↗ Street View in the Info panel to confirm you are at the correct address when the location is ambiguous.

SOP-09CloseoutRole: Crew lead · Trigger: Work complete on site

Capture the Repaired photograph in the right-hand green slot, from the same position and framing as the condition photo.
In Edit, set Completion Date to today.
Set status to Complete.
Add a closing note recording material used, actual quantity placed, and any deviation from the planned scope.
Remove the stop from the active route so the remaining sequence reflects outstanding work.

Status and date are independent

Setting status to Complete does not populate the completion date, and setting the date does not change the status. Both must be set by hand. A Complete record with a blank date will export as complete with no date, which fails most reporting checks downstream.

SOP-10Verification and warrantyRole: Inspector · Trigger: Post-completion review

Filter the map to Status: Complete.
For each record, open the Photos sub-tab and compare the pair. Confirm the repair is present, the surface is flush, and the boundary is sealed.
If acceptable, set status to Verified. This is the terminal state for normal work and moves the record into the Completed quick stat.
If the repair has failed within its warranty period, set status to Warranty, raise priority to match the hazard, and note the failure mode and original completion date.
Because Warranty is not filterable (§5.5), maintain the warranty list outside the system — search warranty, or export and filter the CSV.

SOP-11Manage RRRP blocksRole: Program manager · Trigger: Program planning cycle

Go to 🏘 RRRP.
Enter the Street / Block Range using the convention Street (From — To), matching the sample format. This is the only mandatory field.
Set Ward, Lane Miles, and Current PCI. Lane miles feeds the program rollup — leaving it blank records 0 and understates the program.
Set the Scheduled Date and select a Rehab Method per §5.8.
Enter Estimated Cost as a whole dollar figure. This is a manual capital estimate; unlike spot repairs it is not calculated.
Record coordination constraints in notes — concurrent water main work, ODOT co-funding, utility conflicts.
Click + Add RRRP Block.
As construction advances, use the status buttons on the block card to move Planned → Scheduled → In Progress → Complete, and % Update to set progress. Setting Complete forces progress to 100%.

RRRP blocks are not mapped

Blocks carry no coordinates, so they never appear as map pins and are excluded from routing and from CSV and GeoJSON exports. They exist in the RRRP tab and the analytics rollup only. To show a rehabilitation on the map, create a companion spot repair record with the RRRP method.

SOP-12End of shift — export and handoffRole: Any · Trigger: Before closing the browser

Mandatory

This procedure is the save operation. Skipping it destroys the shift's work.

Go to the Map tab and reset every filter to All. Export scope follows the active filters.
If a route is active, click Clear on the Routes tab first — otherwise CSV export writes only the route stops. See §11.2.
Go to 🛣 Repairs and click ⬇ CSV. The file downloads as CityCLE_RRTS_YYYY-MM-DD.csv.
Click ⬇ GeoJSON for the spatial copy, which downloads as CityCLE_RRTS.geojson. This filename carries no date — rename it on save or each export overwrites the last.
Open the CSV and confirm the row count matches the header's Repairs badge. A shortfall means a filter or an active route was still in effect.
File both exports to the shared drive under the shift date.
RRRP blocks are not covered by either export. Screenshot the RRRP tab or maintain the block schedule in a parallel spreadsheet.

8.0Route Optimization

8.1Algorithm selection

Algorithm	Behavior	Use when
Nearest Neighbor	Starts at the depot and repeatedly travels to the closest unvisited stop.	Default choice. Fast and adequate for routes under roughly 15 stops. Can end with a long return leg.
TSP 2-Opt	Builds a nearest-neighbor route, then repeatedly reverses path segments wherever doing so shortens the total.	Larger routes where travel time is the binding constraint. Produces a measurably tighter loop for a small computation cost.
Priority First	Sorts strictly by priority class, then by distance from depot within each class. All P1 work precedes all P2.	Any day with emergency work. Accepts longer travel in exchange for hazard sequencing. Use this whenever a P1 is on the route.
Zone Grouping	Sorts by the zone field, then by distance from depot within each zone.	Multi-crew days where geographic separation between crews matters more than any single crew's efficiency. Note that manual entries all carry zone `Custom` and will group together.

8.2Distance model

All distances are great-circle (haversine) distances in kilometers between coordinate pairs, computed on a 6,371 km earth radius.

Straight-line, not drive distance

The engine has no road network, no turn restrictions, and no traffic model. It routes through buildings, across the Cuyahoga, and the wrong way down one-way streets.

In practice, actual driving distance in Cleveland runs roughly 1.3 to 1.6 times the reported straight-line figure, and considerably more where a route crosses the river or the valley. Treat the kilometer total as a sequencing aid and a relative comparison between algorithms — never as an ETA or a mileage claim.

8.3Depot configuration

The depot is the route origin, marked CITY YARD in teal on the map. It defaults to 41.4775, −81.6794. Change both fields before optimizing when dispatching from a different facility — the depot is read at the moment Optimize is clicked, so editing it afterward does not re-sequence the route until you optimize again.

8.4Route metrics

Metric	Calculation	Reliability
Stops	Count of sequenced repairs.	Exact
km	Depot to first stop, plus each consecutive leg. Excludes the return to depot.	Indicative Straight-line, one-way.
Hrs	Sum of estimated hours across stops. Excludes travel, setup, and breaks.	Indicative Weakened by the flat manual-entry formula (§6.4).
Cost	Sum of estimated cost across stops, shown in thousands.	Unreliable when manual entries are present (§6.3).

Each stop in the list also shows a cumulative distance from depot, which is useful for identifying the point at which a route stops being efficient — a leg that adds several kilometers for one low-priority repair is usually worth deferring to the next day.

9.0Photo Documentation

9.1Storage architecture

Database	CityCLE_RRTS_v2
Object store	photos — keyed on repair ID
Record shape	{ id, before, after }
Encoding	JPEG data URL, quality 0.82
Maximum dimension	1200 × 900 px, aspect preserved
Typical size	120 – 220 KB per image

9.2Capture and compression

Images are resized in the browser before storage: the longest edge is reduced to fit within 1200 × 900 and re-encoded as JPEG. A 12 megapixel phone photo of roughly 4 MB is stored at approximately 180 KB — a 20-fold reduction with no meaningful loss of detail at the scale a pavement defect is judged.

The original file is never retained. Only the filename survives, shown beneath the thumbnail. If the full-resolution original matters for a claim or dispute, keep it on the device or in the department's photo archive as well.

9.3Slot semantics

Slot	Label	Captured	Purpose
Left / amber	Condition	Before work begins	Evidence of pre-repair state. Establishes that the defect existed, its extent, and its severity.
Right / green	Repaired	After work completes	Evidence of completion and workmanship. Basis for verification in SOP-10.

Each slot holds exactly one image. Uploading a second replaces the first, and the replaced image is not recoverable. Clicking a thumbnail opens the full-size lightbox; clicking anywhere in the lightbox closes it.

9.4Storage management

Settings → Photo Storage shows the number of images stored and an approximate byte total. The estimate is derived from the encoded string length and runs slightly high — treat it as an upper bound.

Photos stored	Approximate footprint	Action
Under 100	~18 MB	No action.
100 – 250	~45 MB	Monitor. Confirm the browser quota is not being approached.
Over 250	~50 MB+	Archive completed work externally, then clear. Writes begin failing silently once quota is reached.

Delete All Photos is irreversible

The control removes every stored image across all repairs, with a single browser confirmation and no undo. There is no bulk export — photographs cannot be extracted from the system in bulk through the interface. Before clearing, open each record you need to retain and save the lightbox image manually, or capture the record's photo pair by screenshot.

This is the strongest argument for the export path in §14. Photographic evidence with no export route is evidence that exists only until someone clicks a red button.

10.0Analytics & Reporting

10.1Dashboard metrics

Metric	Definition	Scope
Total Repairs	Count of all repair records.	Unfiltered
Avg PCI	Mean PCI across all records, rounded. An unweighted average — a 10 SY pothole counts as much as a 2,000 SY rehabilitation.	Unfiltered
Total SY	Sum of repair area in square yards.	Unfiltered
Est. Cost	Sum of estimated cost, in millions. Subject to the §6.3 caveat.	Unfiltered

Analytics ignore filters

Every chart on the dashboard reads the complete dataset. Setting the map filter to Ward 8 or to P1 does not narrow the analytics. To analyze a subset, export to CSV and pivot there.

10.2Distribution charts

Six horizontal bar groups, each showing count and percentage of total:

By Road Surface — asphalt, concrete, brick. Reveals the maintenance profile of the network being worked.
By Method — the five repair methods. Read against equipment availability; a large Saw Cut share signals deferred maintenance catching up.
By Priority — P1, P2, P3. A P1 share above roughly 20% indicates a reactive posture rather than a programmed one.
By Status — the five filterable statuses. Warranty is omitted from this chart.
Top Wards — the eight wards with the most records. Useful for Council reporting, subject to the §5.7 accuracy caveat.
RRRP Program — block status distribution plus lane mile and budget totals. Appears only when blocks are loaded.

10.3Interpreting the program picture

Three readings the dashboard supports well:

Reactive vs. programmed

P1 share

A rising P1 percentage with a rising Saw Cut share means the network is failing faster than preventive treatment is being applied. The corrective action is upstream — more SP5E and Kasi work on pavement still scoring above 50.

Cost per square yard

Est. Cost ÷ Total SY

Compute this by hand from the two headline figures. A blended rate climbing toward the Saw Cut rate confirms the network is being treated late rather than early.

Two readings it does not support: the ward chart is not reliable enough for formal allocation (§5.7), and cost is not reliable at all once manual entries are present (§6.3). Both belong in the exported CSV, corrected, before they appear in a published figure.

11.0Exports & Interoperability

11.1CSV schema

Sixteen columns, comma-delimited, with a header row. Filename: CityCLE_RRTS_YYYY-MM-DD.csv.

#	Column	Contents
1	ID	Repair identifier
2	Address	Full address string
3	Ward	Council ward or `—`
4	Neighborhood	Neighborhood or `Manual Entry`
5	Surface	Full surface label, e.g. Asphalt (HMA)
6	Method	Full method label, e.g. JCB Pothole Pro
7	Distress	Distress type string
8	PCI	Integer 0–100
9	SY	Area in square yards
10	Priority	Raw code — `p1`, `p2`, `p3`
11	Status	Display label, e.g. In Progress
12	Est Cost	Dollars, unformatted integer
13	Hours	Estimated labor hours
14	Source	Report source
15	Requested	ISO date
16	Notes	Free text; embedded double quotes are converted to single quotes

Not exported: latitude, longitude, completion date, estimated completion date, assigned crew, and zone. Crew assignment in particular is absent, so the CSV cannot answer who did the work — use GeoJSON, which carries every field, when that matters.

11.2CSV export scope — important

Critical — the CSV button changes meaning when a route is active

Both CSV buttons — the one on the Repairs toolbar and the one in the Routes summary — call the same routine. That routine exports the route stops if a route exists, and only falls back to the full repair set when the route is empty.

So clicking ⬇ CSV on the Repairs tab with a 6-stop route active produces a 6-row file, not the full registry — with no warning, and a toast that says "Exported 6 repairs." An operator expecting the full dataset will file a task order as their shift record.

Before any full export, go to Routes and click Clear. Verify the exported row count against the header's Repairs badge.

Condition	CSV contains	Filters applied?
Route has stops	Route stops only, in sequence	No — route membership already reflects the filters used to build it
Route empty	All repair records	No — the full dataset regardless of active filters

11.3GeoJSON schema

A standard FeatureCollection of Point features. Filename: CityCLE_RRTS.geojson.

Geometry is [longitude, latitude] per the GeoJSON specification — note the axis order, which is the reverse of the interface.
Properties carry every field on the record, including coordinates, crew, zone, and both date fields.
Export is always the full repair set. It ignores both filters and route state, so it is the more reliable of the two exports for archival.
RRRP blocks are excluded, having no geometry.

Filename collision

GeoJSON exports carry no date in the filename. Successive exports land as CityCLE_RRTS.geojson, (1), (2), and so on in the downloads folder, with nothing to indicate which is which. Rename on save with the shift date before filing.

11.4Downstream use

Target	Format	Notes
ArcGIS / QGIS	GeoJSON	Loads directly as a point layer. Style on the method or priority property to reproduce the map symbology.
Excel / Sheets	CSV	Pivot on ward, method, or status. Correct manual-entry cost before using any dollar figure.
Work order systems	CSV	Route export functions as a task order. Map the ID column to the external work order key.
Council reporting	CSV	Correct ward assignment first (§5.7). The system's ward derivation is incomplete.

12.0System Administration

12.1Data management

Control	Effect	Reversible
Load Sample Repair Data	Replaces all repair records with 40 generated samples. Adds the five default crews if the roster is empty. Refits the map to the sample extent.	No
Load Sample RRRP Blocks	Replaces all RRRP blocks with 8 samples.	No
Clear All Data	Removes all repairs, route stops, and map markers. Leaves crews, RRRP blocks, and photographs untouched. No confirmation prompt.	No

Clear All Data has no confirmation

It fires immediately on click, destroying every repair record in the session. It sits directly below two similar-looking buttons in the same column. Confirm you have exported before touching it.

12.2Map options

Toggle	Default	Effect when off
Route Line	On	Hides the dashed route polyline and the CITY YARD depot marker. Sequence and numbering are unaffected.
Stop Numbers	On	Removes the numeral from route pins. Useful on dense routes where numbers overlap.
Dark Tiles	On	Removes the brightness and saturation filter applied to basemap tiles, restoring standard colors. Turn off in bright sunlight for field legibility.

12.3Recommended administrative cadence

Interval	Task
Every session	Clear sample data at start (SOP-01); export CSV and GeoJSON at end (SOP-12).
Weekly	Reconcile exports into the master spreadsheet; verify photo count against completed work; confirm crew roster.
Monthly	Archive photographs for verified work externally, then clear storage; review P1 share and blended cost per SY (§10.3); update the RRRP schedule.
Quarterly	Review ward assignment accuracy against the current Council map; reassess method escalation thresholds against actual repeat-repair rates.

13.0Troubleshooting

Symptom	Cause	Resolution
Map area is blank or grey; no pins	Leaflet failed to load from unpkg.com	Check the network. On a restricted network, request allowlisting or vendor Leaflet into the file (§2.2).
Map controls work but tiles are grey	OpenStreetMap tiles blocked or rate-limited	Try the Satellite toggle. Pins and routing continue to function on a blank basemap.
All my records vanished	Page was reloaded — records are session-only	Unrecoverable. Re-enter from the last export. Adopt SOP-12 without exception (§1.4).
Sample data reappeared	The page loads the demonstration set on every start	Clear All Data at the start of every session (SOP-01).
New repair did not appear on the map	Longitude entered without the minus sign, or a filter is excluding it	Check the sign — Cleveland longitudes are negative. Then reset all filters to All and click Fit All.
"Latitude and longitude are required"	One or both coordinate fields are empty	Use My Location or Pick on Map (SOP-03). The record cannot be created without coordinates.
My Location fails	Permission denied, no GPS, or insecure context	Grant location permission; serve over HTTPS rather than `file://`; fall back to Pick on Map.
Camera button opens a file browser	Desktop browser, or camera capture unsupported	Expected on desktop. Use a phone or tablet for direct capture.
CSV has far fewer rows than expected	An active route is redirecting export scope	Clear the route, then export (§11.2).
"Add at least 2 repairs to route first"	Fewer than two records flagged for routing	Add stops via the detail panel or + Add Filtered before optimizing.
Optimize produces an illogical order	Priority First or Zone Grouping is selected — both override distance	Expected behavior. Switch to Nearest Neighbor or TSP 2-Opt for pure distance sequencing (§8.1).
Route kilometers look too low	Straight-line distance, not drive distance	Expected. Multiply by roughly 1.3–1.6 for a planning estimate (§8.2).
Photo will not save	IndexedDB quota reached, or the file is not an image	Check Settings → Photo Storage. Archive and clear if near capacity.
Photos exist but the Photos tab is empty	Photos are orphaned — their parent records no longer exist	The tab shows only photos for loaded records. Clear orphans from Settings (§2.3).
Warranty records cannot be filtered	No Warranty button exists in the status filter row	Search `warranty`, or export and filter externally (§5.5).
Cost totals look inflated	Manual entries use a flat $45/SY regardless of method	Recalculate outside the system before publishing any figure (§6.3).
Crew shows on a repair but not in the roster	The crew was deleted after assignment	Re-add the crew with the identical name, or reassign the affected repairs (§4.3).
Edits do not appear to save	Edit fields commit on change; there is no Save button	Click away from the field to trigger commit. A green toast confirms.
Side panels crowd out the map	Viewport narrower than roughly 1100 px	Maximize the window or use a larger display. The three-column layout is fixed-width.

14.0Limitations & Enhancement Backlog

Documented as-built. Each item states the current behavior and the recommended remedy, ordered by operational risk.

14.1Priority 1 — blocks production use as a system of record

#	Limitation	Recommended remedy
01	No data persistence. Records exist only in memory and are destroyed by any reload.	Mirror all four state arrays into `localStorage` on every mutation, with a restore-on-load path. A JSON import to complement the existing export would close the round trip.
02	Sample data auto-loads on every start, overwriting nothing but contaminating any real session that begins without a clear.	Load samples only on an explicit click, or gate the auto-load behind an empty-store check once persistence exists.
03	Manual cost uses a flat $45/SY regardless of method, overstating spray-injection work roughly 18×.	Apply the same per-method rate table used by the seed generator.
04	CSV export silently switches scope when a route is active.	Separate the two buttons into distinct functions, or prompt for scope when both a route and a registry exist.
05	Clear All Data has no confirmation and sits beside two benign buttons.	Add a confirmation dialog matching the pattern already used for photo deletion.
06	Photographs cannot be exported. Evidence is trapped in browser storage with a one-click bulk delete.	Add a ZIP export of all photos named by repair ID and slot, or upload to City storage on capture.

14.2Priority 2 — degrades data quality

#	Limitation	Recommended remedy
07	Warranty status is not filterable and is excluded from the completion stat.	Add the button to the status filter row and to the status distribution chart.
08	Manual entries lose neighborhood, ward, and report source, which are hard-coded rather than captured.	Add a neighborhood selector that derives ward from the existing table, and a report source dropdown.
09	The ward table omits Wards 2 and 13 and covers only 19 neighborhoods; unmatched records receive a random ward.	Complete the table against the current Council map, and default unmatched records to `—` rather than a random value.
10	Address, coordinates, distress, and source are write-once — a typo requires deletion and re-entry.	Expose all four in the edit panel.
11	Distress type is unconstrained free text, so spelling variants fragment reporting.	Replace with a dropdown filtered by the selected surface, using the §5.3 vocabulary.
12	Priority is not derived on manual entry, defaulting every record to P3 whatever the PCI.	Apply the §6.2 thresholds as the form default, leaving the operator free to override.
13	Analytics ignore active filters, so no subset can be analyzed in-app.	Read from the filtered set, with a toggle for whole-program view.

14.3Priority 3 — capability gaps

#	Limitation	Recommended remedy
14	Routing uses straight-line distance with no road network, one-way, or bridge awareness.	Integrate a routing service (OSRM, Valhalla, or a City-hosted network) for true drive distance and duration.
15	RRRP blocks have no geometry and are absent from the map and both exports.	Add start and end coordinates, render as a polyline, and include blocks in a second GeoJSON layer.
16	No multi-user support, authentication, or audit trail.	A shared backend with per-user attribution and a change log — the point at which this ceases to be a single-file tool.
17	No 311 or SeeClickFix ingestion, despite both being listed as report sources.	Poll the SeeClickFix API for open road-surface issues and create records automatically.
18	Crew specialty does not constrain assignment — a Kasi crew can be assigned saw cut work without warning.	Warn on mismatch between crew specialty and repair method at assignment.
19	No repeat-repair detection, though the escalation logic in §5.1 depends on it.	Flag new records within a set radius of a completed repair and surface the prior history in the detail panel.
20	Fixed-width layout below 1100 px limits phone and tablet use for field crews.	Collapse the side panels into drawers at narrow widths.

15.0Field Quick Reference

Print this section and keep it in the truck. It is the one-page version of everything above.

Every session — non-negotiable

Start: Settings → Clear All Data. Otherwise you are working on top of 40 fake repairs.
End: Routes → Clear, then Repairs → CSV and GeoJSON. If you skip this, the shift's work is gone.

Where things live

Add a repair → Settings tab, right column
Photos → Map tab, detail panel
Change status → Map tab → Edit sub-tab
Build a route → Routes tab
Export → Repairs tab, top right

Traps

Longitude must be negative
Priority defaults to P3 — set it yourself
Address and coordinates are write-once
Status and completion date are set separately
An active route shrinks the CSV

Priority by PCI

PCI	Priority	Method guidance
0 – 34	P1	Saw Cut R&R, or escalate to RRRP
35 – 39	P1	Saw Cut R&R
40 – 49	P2	Saw Cut R&R
50 – 64	P2	Kasi IR or JCB Pro
65 – 84	P3	Kasi IR or SP5E preventive
85 – 100	P3	SP5E preventive, or defer

Override upward for any immediate hazard regardless of score. An open pothole in a travel lane is P1 on a street scoring 80.

Status sequence

Open → Dispatched → In Progress → Complete → Verified | Warranty on failed repair

Photo rule

Condition photo before the first tool touches the pavement. Repaired photo from the same position. Both, every time — no exceptions on P1 work.

16.0Document Control

Document No.

FOS216-RRTS-OM-001

Revision

Status

Issued for Use

Date

2026-07-25

16.1Revision history

Rev	Date	Description	By
A	2026-07-25	Initial issue. Documents CityCLE_Road_Repair_Tracker.html as-built: all seven tabs, complete data dictionary, controlled vocabularies, twelve standard operating procedures, routing and photo subsystems, export schemas, and a twenty-item limitation register.	FOS216

16.2Scope of this revision

This manual documents the application as delivered. Where behavior is surprising, unreliable, or destructive, it is described plainly rather than smoothed over — see §1.4, §6.3, §11.2, and §12.1 in particular. The limitation register in §14 is written to be actionable as a development backlog rather than a disclaimer.

Sections requiring update when the application changes:

If this changes…	Update
Persistence is added	§1.4, §2.3, SOP-01, SOP-12, §14.1
Cost calculation is corrected	§6.3, §8.4, §10.1, §14.1
Methods, surfaces, or statuses are added	§5.1–§5.5, §3.4, §6.1
Ward table is completed	§5.7, §10.2, §11.4
Export schema changes	§11.1, §11.3, SOP-12

16.3Related documents

Document	Relationship
CityCLE_Road_Repair_Tracker.html	The application this manual documents.
FOS216-BLIGHT-TRK-001	Vacant Lot Blight Reduction Tracker — parallel tracking platform sharing the ward and neighborhood conventions.
FOS216-BTF-001	Cleveland Blight Task Force establishment framework — shares the Blight Severity Index scoring approach applied here to PCI.