Review application A.2.4

Problems page

The Problems page (/problems) presents the problems that the engine detected (E4) one at a time, most important first, with the stops involved on a map. Reviewers filter them by type, priority, operator and area, and step through them with buttons or the keyboard.

Layout

flowchart TB subgraph Page["Problems page: the map fills the page"] direction TB FP["Filter Panel<br/>(toolbar over the top of the map)"] MAP["Leaflet Map"] PP["Problem Panel<br/>(card over the bottom of the map)"] end FP --- MAP --- PP

The map fills the page; the filter panel and the problem panel float over it:

Section Purpose
Filter Panel A toolbar over the top of the map: priority, problem type, operator and area filters, the context toggle and the Prev/Next buttons. On screens up to 768 px wide it folds behind a Filters button.
Map Shows markers for the current problem's ATLAS and OSM stops, with optional context markers for nearby stops.
Problem Panel A card over the bottom of the map with the problem details. Chips at its top name the entry, the active problem's type and its priority; the type chip opens the type's section of E4.1.

Problem types

Every problem has a type and a priority, P1 being the most important. E4.1 Stop problems explains what each type means, what is checked and how the priority is set. The page names the types as follows:

Label Filter name (problem_type)
Distance distance
Unmatched unmatched
Attributes attributes
Contradicts Route Matching contradicts_route_matching
Duplicates duplicates
Disused OSM disused
OSM SLOID identifier

The label of identifier is "OSM" followed by the deployment's identifier label, SLOID in Switzerland. Each type's checkbox is #filterProblemType<Name> and its count #typeCount<Name>, for example #filterProblemTypeDisused and #typeCountDisused.

Disused OSM elements

The map draws the OSM element as a disused marker. The detail panel names its lifecycle prefix (osm_lifecycle, such as disused) and explains the case in one banner (generateDisusedDetailsHtml() in problems-ui.js):

Priority Banner Cause Suggested action
P1 Red ATLAS still lists a stop with the same UIC reference, and that stop has no OSM partner Check on the ground: if the stop is in service, remove the prefix in OSM; if it is gone, the ATLAS entry is outdated
P2 Amber The element still looks active to data users: an unprefixed stop tag remains, or a route relation still lists it Prefix or remove the remaining stop tags, and remove the element from routes that do not serve it

The OSM popup lists every tag of the element (A2.1). E4.1 Stop problems describes how the engine assigns these priorities.

OSM SLOIDs

Identifier matching links an OSM element to the ATLAS platform its SLOID names (E2.1). A value it cannot use becomes an identifier problem of the element, on its match rows or its unmatched row. The map draws the pair, or the element alone. The detail panel lists the element's SLOID tags beside the matched platform's SLOID, and explains the case (generateIdentifierDetailsHtml() in problems-ui.js):

Priority Banner Cause Suggested action
P1 Red The SLOID names a platform more than 150 m away; matching ignored it It was probably copied from another stop: find which platform the element is and correct the tag
P2 Amber The SLOID names no ATLAS platform Look the platform up in ATLAS; the value is outdated or mistyped
P3 Blue A value is not a SLOID (ch:1:sloid:…), such as a UIC number Replace it with the platform's SLOID, or remove it

The list API reads the element's tags (osm_tags) only for these problems.

Filtering and sorting

Filters

Filter Control Effect
Problem type Dropdown with counts; its info icon opens E4.1 Restricts to one or more types, or all
Priority Circle pills (All, P1, P2, P3) Restricts by priority level
Operator Multi-select dropdown Restricts by ATLAS operator (atlas_business_org_abbr)
Area Area button, then a rectangle drawn on a map Restricts to the problems inside the rectangle (Area)

Priority, operator, problem-type and area filters are enforced server-side.

Area

Area opens a dialog with a map, on the Problems map's view. Two clicks set opposite corners of a rectangle: between them it follows the pointer, and dragging still moves the map. Clear selection wipes the rectangle so it can be drawn again. Filter problems in this area keeps the problems whose stop lies in the rectangle: its ATLAS or its OSM position, so a matched pair counts when either side is inside. The list starts again from its first entry, the type counts follow the area, and the Problems map draws the area as a dashed outline. The chip Drawn area removes it; so does the dialog's apply button after Clear selection, when it reads Show all problems.

The rectangle is sent as bbox=west,south,east,north in degrees, rounded to 5 decimals, and kept in the page's link (A2.9). A malformed bbox is refused with HTTP 400 rather than read as "everywhere". The code is static/js/pages/problems-area.js and parse_area() / area_condition() in backend/services/problem_filters.py.

Order

The page lists problems by priority, the only order /api/problems has:

Order Behaviour
Across entries Each stop is ranked by its most urgent problem, so entries with at least one P1 issue appear before P2, then P3; stops of equal rank follow their database ID
Within an entry Issues for the same stop are ordered by ascending priority before secondary tie-breakers
Duplicate groups ATLAS-side groups (P2) come before OSM-side groups (P3), then by UIC reference and designation or local_ref

This ordering is applied at query time. The app does not rely on database insertion order, because insert order is not a stable or sufficient guarantee once filtering, grouping, and pagination are involved.

Active filter chips

Active filters are shown as removable chips below the filter panel using FilterChipUtils.renderProblemChips.

Data flow

flowchart TD A["Page loads"] --> B["Fetch /api/problems/stats"] A --> C["Fetch /api/problems?page=1&include_routes=1"] B --> D["Build filter dropdown<br/>with counts"] C --> E["Store in ProblemsState"] E --> F["Group by entry<br/>(groupProblemsByEntry)"] F --> G["Display first entry<br/>(displayProblem)"] G --> H["Render markers on map"] G --> I["Render problem detail panel"]

Paging and prefetching

Problems are loaded in pages of 100 stops (or 100 groups in the duplicates-only view). When the user navigates within 20 entries of the end of the loaded list, the next page is automatically prefetched via prefetchNextPageIfNeeded().

A permalink can open the list on a later page. The loaded pages then start there: Next still loads the following pages, and Prev at the first loaded entry loads the page before (navigateToPreviousProblem()).

Entries

Problems are grouped into entries. An entry is one stop (a matched pair, or an ATLAS or OSM element on its own) with all its problems, which the user can scroll through; in the duplicates-only view it is one duplicate group. The grouping key is:

  • For duplicates groups: group_{group_id}
  • For every other problem, a duplicate problem included: {stop_id}_{lat}_{lon}. A duplicate problem shows the stop's row of its group and links to the group in the duplicates-only view.

An ATLAS stop matched to several OSM elements, such as a PTv2 platform and its stop position, has one entry per pair. Each entry holds the problems of its pair. A duplicate is about one stop, not about a pair, so the engine reports it on one pair only (E4.1), and it shows in one entry.

The list is paged by entry, so the server's total counts entries: the stops with a problem under the filters, or the groups. problem_count counts the problems under the same filters. The summary names both, for example "43,103 problems at 38,177 stops" or "1,806 problems in 893 groups", and the entry chip numbers the entries ("Entry 6,748 of 38,177", "Group 1 of 893"). The Problem type counts are problems too: /api/problems/stats counts problem rows per type, and their sum for All.

Action Trigger
Next entry Click Next button, press → or Space
Previous entry Click Prev button, press ←; at the start of a list opened from a link, this loads the page before
Scroll issues within entry ↑ / ↓ arrows
Toggle shortcut help Press ?
Copy a link to the entry Click Copy link next to the entry chip

When multiple issues exist in one entry, an intersection observer tracks which issue is scrolled into view and highlights the corresponding map markers.

The map frames an entry in the part of the map that the filter toolbar and the problem panel leave visible. A single stop is centred at zoom 16; matched stops and duplicates are fitted above the panel (a duplicate group around its members, a stop's own duplicate problem around its pair), leaving room for the popup above them. The entry's popup pans the map until it sits below the toolbar and above the panel, also after the popup adds its Move bar. When the popup is taller than that space, its top stays below the toolbar. Of a duplicate group's popups, only the first pans (static/js/pages/problems-renderer.js).

Duplicate groups

When Duplicates is the only selected type, the backend performs special grouping logic instead of returning individual problems.

OSM duplicates (P3)

Grouped by (uic_ref, osm_local_ref): the OSM elements with a P3 duplicate problem that share a UIC reference and a local reference form a group when there are at least two.

ATLAS duplicates (P2)

A group is one of the engine's duplicate groups, stored for each ATLAS stop as duplicate_group_sloids: the platforms with the same UIC number and platform code. It is listed when any member carries a duplicate problem, and it lists every member. The engine reports a duplicate once per stop, and on some members only (E4.1): not on a member whose only match was propagated from another by source_duplicate_propagation, and as the OSM duplicate (P3) when the matched OSM element is an OSM duplicate too. A member without a problem of its own is listed without a priority, and a SLOID matched to several OSM elements is one member. So a stop duplicated on both sides, such as Vevey platform 4, is listed twice: once as an OSM group and once as an ATLAS group.

Each group contains a members array with individual stop data, and a centroid coordinate for map positioning.

A group's priority is its side's: P2 for an ATLAS group, P3 for an OSM group, whatever its members carry. The priority filter applies to it, so the duplicates-only view follows the same priority-first ordering as the rest of the page.

When duplicates are listed with other types, as in the All view, individual entries are shown with their stop details (source, identifier, name, coordinates).

Context markers

Each problem has a box: the rectangle around all of its ATLAS and OSM positions (and those of its members, for a duplicate group), widened by 0.02° of latitude and longitude on every side. In Switzerland 0.02° is about 2.2 km north–south but only about 1.5 km east–west, so a problem with a single stop gets a box of roughly 4.4 km by 3 km centred on it.

The Hide other markers / See other markers toggle, on by default, loads every ATLAS and OSM stop in that box from /api/data, once per problem. The page's filters (priority, operator, problem type, area) choose which problems are listed; they do not apply to these context markers. Context markers are displayed at reduced opacity (0.6) and include connection lines for matched pairs. When they cannot be loaded, a banner over the map says so, names the rate limit when that is the cause (A3.2), and offers Retry.

While a problem is shown, the map stays inside its box: it cannot be panned past the box's edges or zoomed out further than the zoom at which the box fills the map, so nothing outside the loaded area comes into view. The limit holds with or without context markers. When the problem's own fitted view is wider than the box, for example two stops far apart on a short screen, that view stays reachable. The limit is set again for each new problem, and lifted when no problem is shown.

The current problem is excluded from the context markers by identity, never by position:

  • Single problems are excluded by matching id, sloid, or osm_node_id.
  • Duplicate groups are first flattened to their members, then excluded using member identities.
  • Nested osm_matches payloads are also checked when present.

Excluding by position would hide co-located duplicate stops, which are real data and stay visible as separate context markers.

The address bar always names the filters and the entry on screen, so it can be shared; A2.9 Permalinks gives the parameters, how a link opens an entry deep in the list and how entry numbers behave there.

API endpoints

Endpoint Method Purpose
/api/problems GET Paginated problem list with filters and duplicate-group aggregation
/api/problems/stats GET Problem counts by type
/api/data GET Context markers (nearby stops)

/api/problems parameters

Parameter Default Description
page 1 Page number
limit 100 Items per page (max 1000)
problem_type all Filter: all, or one or more comma-separated types: distance, unmatched, attributes, contradicts_route_matching, duplicates, disused, identifier
atlas_operator — Comma-separated operator abbreviations
priority — One or more comma-separated priority levels, for example 1 or 1,2,3
bbox — west,south,east,north in degrees: only stops with their ATLAS or OSM position inside. Also read by /api/problems/stats; malformed values answer 400
include_routes 0 Include route evidence arrays in each result; the Problems page requests 1
focus_sloid, focus_osm_node_id — A stop named by a permalink (OSM ways as way_<id>). The response is the page that holds the stop's first entry, whatever page says, and carries focus_found.

With a focus, the response adds focus_found: true when the returned page holds the stop, false when no entry of that stop matches the filters; the requested page is then returned.

all means every type in VISIBLE_PROBLEM_TYPES (backend/services/problem_filters.py). /api/problems/stats returns one entry per type in that list, plus all.

Code

Browser modules

File Module Role
static/js/pages/problems-state.js ProblemsState Centralized state (IIFE with getter/setter API)
static/js/pages/problems-data.js ProblemsData Data fetching, filtering, pagination, navigation
static/js/pages/problems-map.js ProblemsMap Map initialization, context loading, keeping the view inside the problem's box, resize
static/js/pages/problems-renderer.js ProblemsRenderer Draws the problem's markers and lines, frames the view and opens its popups
static/js/pages/problems-area.js ProblemsArea Area dialog, bbox formatting and parsing, dashed outline on the map
static/js/pages/problems-ui.js ProblemsUI Problem rendering, nav buttons, scroll indicators
static/js/pages/problems-permalink.js ProblemsPermalink Filters and entry in the address bar; Copy link
static/js/pages/problems.js — Coordinator: initializes all modules, binds event handlers

Backend

File Role
backend/blueprints/problems.py /api/problems and /api/problems/stats endpoints
backend/services/problem_filters.py VISIBLE_PROBLEM_TYPES, parse_area() and area_condition(); also the map's Problems filter (has_problem_condition())
backend/serializers/stops.py format_stop_data() — serializes StopsMatched to JSON

Template

templates/pages/problems.html — Jinja2 template with filter panel, map container, and problem section. Loads all JS modules in dependency order.