Skip to content

[DRAFT] Railway use case - #34

Draft
chenkins wants to merge 48 commits into
ainetus:mainfrom
chenkins:railway-use-case
Draft

chenkins wants to merge 48 commits into
ainetus:mainfrom
chenkins:railway-use-case

Conversation

@chenkins

@chenkins chenkins commented Nov 8, 2026 •

Copy link
Copy Markdown

Changes

Summary

  • The Railway dispatcher experiment (six scripted Flatland scenarios, "Empfehlungsmodus" and "Ko-Lernen") now runs on the platform's generic pipeline, as PowerGrid does: a simulator next to the platform sends events and contexts, the Recommendation Service answers each decision from a file generated from the scenarios, and the operator's choice and the session controls go back through the frontend's same-origin proxy. Every action is logged by the platform, tied to the login's trace session.
  • The Railway page draws the track network, a time-distance diagram and a line view from the context, shows the open decision, and offers a start dialog for the Experiment or a single run, or a standalone mode with the geographic map for an external simulation; in the Experiment the participant can end the current scenario or the whole Experiment, and after logout answers the reflection questions. The page, including the consent question at login, is in German in a German browser.
  • Backwards compatible: every new event and context field is optional, events and contexts in today's schema keep today's map and recommendation catalog, and without a reachable simulator the page stays as before. Shared platform code is touched in one declared place: the login's consent question is now translated live, as its buttons already were. New deployment pieces: the simulator's own compose and the RAILWAY_SIMU_UPSTREAM setting of the frontend; the Kubernetes route is still open.

Carried out

ID Description Category Severity Commit(s)
— Plan the Railway use case on the InteractiveAI pipeline. — — 63a5062
S1 Add the scripted Railway simulator (six scenarios, two modes) under usecases_examples/Railway. chore - ba54610
S2 Add the ZWL distances, planned paths and the link map to the scenario infrastructure. feature - 1979e78
S6 Run the platform locally without Docker: dev gateway, start script, seed and smoke scripts. feature - b82cbb3
S16 Cypress spec that screenshots and records the Railway page on the dev stack. test - a5fdde4
— Plan: decide the recommendations file, the run list and the start dialog. — — 4c41d66
— Plan: decide the two-step Ko-Lernen choice, with both options shown. — — 549cdd4
— Plan: decide the end-of-session questionnaire and draw the session flow. — — b978bcd
— Plan: identify the Experiment by the platform's trace session. — — 6565aee
— Plan: keep the Railway extension backwards compatible; decide Q15 and Q26. — — cbfcd0f
— Plan: revise the plan and explain Q28 with a mockup. — — c972540
— Plan: decide Q29 and close the session end, questionnaire and step gaps. — — 893d538
— Plan: decide Q21, the study lead decides the reflection questions. — — e313c69
— Plan: decide Q27, the simulator runs as its own always-on service. — — eb3ff62
— Plan: decide Q17 and Q18 with mockups. — — 81edf24
— Plan: show the Q22 end screen options; plan the open findings as steps. — — 75263b6
— Plan: compare the cost of the two Q22 end screen options. — — 3e9fdd2
— Plan: decide Q22 and Q23, which settles Q13. — — 7a00b35
— Plan: decide Q19, the progress bar names the run's mode. — — 0c21ca8
S18–S22, 1, 2, 3, 4, 5 Record the decisions settled with others: Q4 (no time controls), Q2 a), Q10 (own compose), Q6 and Q8 confirmed. decision medium 091b3cc
S3 The Event and Context services accept the simulator's scenario, session and infrastructure fields, all optional. feature - b7e61eb
S7 The Railway page in German, with English and French kept. feature - 84391bc
S4 Session runner that publishes events and contexts on change and receives the operator's choice and the session controls. feature - 1b83049
S5 Recommendations for each decision from a file generated by the simulator, looked up by RailwayManager. feature - 2b4c7da
S8 Kartenansicht: the track network and the trains drawn from the context. feature - 8da776c
S9 ZWL Diagramm drawn from the context history. feature - 69b0200
S17 Linienansicht drawn from the link map. feature - bb3d04a
S10 Step, open decision and train table above the drawing. feature - 6c44c50
S11 Decision panel: apply an option in Empfehlungsmodus, train then action in Ko-Lernen; /railway-simu/ proxy in every nginx config. feature - d0129eb
S12 Start dialog (Experiment or single run, introductions, end screen), progress bar, reflection questions after logout. feature - 17e8657
S14 CI workflow for the simulator and the services' Railway tests. ci - 6a4ee06
S13 Cypress plays one scenario per mode to its end; comparison with the reference screenshot; all shots refreshed. test - 4190e38
S15 Simulator Dockerfile and own compose, image built with /railway-simu, cabProcess perimeter seeded, deployment docs and checklist. feature - c663b77
— Plan: record the commits and shots of S3–S15; plan the Kubernetes route as S23. — — ba78cf3
— Plan: mark the five decision findings fixed in the commit that recorded them. — — b959c09
S24 "Standalone-Modus" in the start dialog: "Karte ansehen" opens the geographic map for an external simulation, "▶ Szenario-Loader" goes back (Q31 d). feature - 43f9dff
S26, 7 Pin Werkzeug below 3 next to Flask 2.3, so a fresh install (CI) keeps the simulator's route tests green. fix medium b490b9c
S25, 6 In the Experiment, "Szenario beenden" ends the current scenario early and "✕ Experiment beenden" the whole session, through the simulator's new end-run route; a single run keeps "✕ Beenden". feature low 2ffa188
S27, 8 The consent question at login follows the page's language as its buttons do (declared exception in two shared files, Q32); the Cypress login answers in the browser's language. fix low 9a68f92
— Plan: record the commits of S24–S27 and refresh the introduction shot. — — 339c2db

Remaining

ID Description Category Severity Commit message
S23 The /railway-simu/ location in the Kubernetes ConfigMap and RAILWAY_SIMU_UPSTREAM on the frontend pod; waits for Q30, where the simulator runs on the server. feature - feat(deploy): route /railway-simu/ to the Railway simulator on Kubernetes

Requirements and walk-through

Plan: docs/plans/railway-use-case.md. Screenshots on the dev stack without Docker (usecases_examples/Railway/devstack, 4 steps/s, 1600×900), German unless noted; "before" is today's Railway page with a context in today's schema, after on this branch (4190e38; later rows on the commit that added or last changed their shot), by frontend/cypress/e2e/railway.cy.ts.

# Requirement Result Screenshot
1 Today's Railway events and contexts keep working (D20) ✅ a context without track network keeps the Leaflet map and the catalog before and after:
2 The simulator's cards in the feed (F1, D3) ✅ events sent through the Event Service after:
3 Recommendations from the Recommendation Service (D6, Q2 a) ✅ the decision's options from RailwayManager after:
4 German texts (D9, Q7) ✅ platform and Railway texts in a German browser after:
5 Kartenansicht (F3, F7–F11) ✅ track network, stations, trains with direction, held trains in red before: after:
6 ZWL Diagramm (F12–F14) ✅ actual and planned paths, current step after:
7 Linienansicht (F31, Q12) ✅ the line straight, three rows after:
8 Step, open decision and train table (F4, F35, F36) ✅ after:
9 Empfehlungsmodus: choose and apply (F15–F18, F20) ✅ options with KPIs, "Anwenden", the run resumes decision: after apply:
10 Ko-Lernen: train, then action (F19, Q8 a, Q28 a) ✅ actions not offered greyed out, infeasible ones say why, KPI preview
11 Start dialog, introductions, end screen (F21–F26, Q3 d, Q22 b) ✅ introductions with "✕ Experiment beenden" (S25) introduction: end:
12 Reflection questions after logout (F24, Q5 d) ✅ CHAINS.Railway, German
13 Close to the reference screenshot (Goal) ✅ same state as railway_sim.png; remaining differences listed in the Railway README §2.4 before (railway_sim): after:
14 No time controls for the participant (D8, Q4) ✅ the simulator sets the pace, the run pauses itself at the decision
15 Runs without Docker, one command each (T1–T3) ✅ devstack/start.sh, Cypress spec
16 Tests (T5) and CI (T6) ✅ 82 simulator tests, 12 service Railway tests, 33 Vitest tests, Railway CI workflow (fresh installs fixed by S26); Cypress (15 tests) stays a manual run
17 Deployment next to the platform (D1, Q10, Q27 a) ✅ compose; Kubernetes route open (S23, Q30)
18 Geographic map for an external simulation from the start dialog (F40, Q31 d) ✅ "Karte ansehen" in "Standalone-Modus", the Leaflet map whatever the latest context, "▶ Szenario-Loader" back after:
19 End the scenario or the Experiment (F23, finding 6) ✅ "Szenario beenden" moves on to the next introduction, "✕ Experiment beenden" ends the session after:
20 Consent question in the page's language (finding 8, Q32) ✅ question and buttons German in a German browser; on main the dialog stays English before: after:

Walk-through: the Cypress run of all 13 tests before S24–S27 (4 min), uploaded by hand:

railway-walkthrough.mp4

Follow-ups (not in this PR)

Follow-up Why not in this PR From Findings Issue
Store reflection answers in the platform. Needs a trace step or service change, outside the generic pipeline. Q5, Limitations - -
Export script of the decision log over the historic traces. Needed after the experiment, not for running it. §2 D10 - -
Cypress job in CI. Only if the run fits the CI budget. T6 - -
Recommendations from an agent route of the simulator instead of RailwayManager's file. The lookup in the file is enough for the experiment; the route can follow (Q2 a)). Q2 - -
A dashboard for the experimenter. The start dialog meets the requirement (Q3 d). Q3 b) - -
Mark a "best" option. The scenarios define none. §2 D6 - -
Scenario texts (cards, decision questions, option labels) in English and French. Needs per-language texts in the scenario files and the language in the session. Q7 - -
Fetch the context once more right after an event. Platform-wide polling change. Limitations - -

chenkins and others added 5 commits November 7, 2026 20:59
Plan for running the Railway dispatcher experiment (the cleaned simulator of
the standalone railway_sim prototype) on the platform's generic pipeline, with
requirements, design, change inventory, steps and open questions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…mples

The cleaned, headless simulator of the standalone railway_sim prototype
(branch FHNWtec-version): six scripted Flatland scenarios, two decision
modes, payload drafts and 38 tests, with a README. Only the payload
docstring changes: it points at the plan instead of the handover notes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…he scenario infrastructure

sim/marey.py ports the standalone prototype's ZWL mapping and link map
(identical results on all six maps) and adds the planned path per train;
infra_payload() sends marey_mapping, planned_paths and link_map, so the
frontend can draw the ZWL and the link map from the context.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
usecases_examples/Railway/devstack starts the Event, Context, Historic and
Recommendation services on SQLite with AUTH_DISABLED, registers Railway and
puts a gateway on port 3200 in front of them that stands in for nginx,
Keycloak and OperatorFabric. It serves the built frontend or the Vite dev
server, keeps its venv, databases and logs in the gitignored .cache/, and
comes with seed and smoke scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cypress/e2e/railway.cy.ts logs in through the dev gateway, answers the
consent question and saves the shot 00-baseline of today's Railway page;
cypress.config.ts records a video and opens a 1600x900 window. The
baseline shot is kept with the plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread docs/plans/railway-use-case.md Resolved
…art dialog

Q2 is decided as ab): RailwayManager looks the open decision's
recommendations up in a copy of recommendations.json, generated from the
scenario files by the simulator, with the option of moving the lookup into
an agent route of the simulator later. Q6 is decided as railway_sim's
Experiment, with the mode set per run. Q3 now proposes a start dialog and a
progress bar, after PowerGrid's agent choice, shown in a new sequence
diagram. The modes get requirements F37 to F39, and phases 1 and 2 are
recorded as carried out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread docs/plans/railway-use-case.md Resolved
Comment thread docs/plans/railway-use-case.md Resolved
…tions

Q8 is decided as a): the two-step choice lives in the Railway use case
only, as ColearningChoice.vue in Railway's own assistant panel, with no
change to shared code. Q8 now lists its options with a screenshot of the
platform's flat recommendation list in both modes and a mockup of the
two-step panel, and notes that the reference screenshot shows a Ko-Lernen
decision. Q2 is marked as decided, and Q6 names the cleaned simulator's
session file and why a mode per run adds little code.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Comment thread docs/plans/railway-use-case.md Resolved
Comment thread docs/plans/railway-use-case.md Resolved
chenkins and others added 18 commits November 10, 2026 09:31
…lway session flow

Q5 is decided as one questionnaire at the end through the post-logout survey,
with how the platform ties its answers to a person and how they are
collected. Q16 drops the Testprotokoll, and Q14 falls away. Q11 gets the
option of one shared user with the participant code typed into the start
dialog. Q3 gets today's page with the experimenter starting the simulation
(e) and an overlay between scenarios (f), with a mockup of introductions as
feed cards and the place of the status line. Q27 keeps the simulator an
always-on service rather than running it in the Context Service. The new
section 4.2.6 draws a session from the start dialog to the end screen, with
the experimenter's case shaded.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…session

D10 now ties every logged record to the Experiment by the platform's trace
session id or its timestamp, instead of one user per participant: the
platform logs no user and has no participant concept, and the post-logout
survey already uses that id. Q11 is decided as one shared railway_user with
no participant code; the start dialog sends the trace session id as the
experiment's session_id, which also seeds the run order. The participant
field leaves the data model, the examples, the dev gateway, Cypress and the
deployment seed files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…de Q15 and Q26

The new design requirement D20 keeps everything outside usecases_examples
backwards compatible: every field added to Railway's schemas and frontend
types is optional, and the Railway page, its apply and RailwayManager pick
the new path only when the new data is there, so today's Leaflet map,
catalog recommendations and /transport_plan keep working. Breaking changes
become none. The run's mode travels as run_mode, since the catalog path
reads event["mode"]. Q15 is decided as extending the existing Railway use
case and Q26 as a scenario list route on the simulator, so S3 and S4 are no
longer blocked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the action row options

Revise the run flow (session end time, run list on session start, 409 on a running session),
update the findings and status, and add Q28 (Ko-Lernen actions a train does not offer) with
options a)-c) and a mockup of a) and b).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ep gaps in the Railway plan

Decide Q29 a): a session start posts run 1 as ready and ends a session another login left running,
with sequence diagrams of both gaps and both options. Fix "Beenden" versus the end screen, the
German-only survey chain, the Blocked-by columns, tests, follow-ups and new patterns.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n questions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-on service

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…f both placements

Decide Q17 b), the platform's recommendation cards with the handover's KPI labels, and Q18 a), the
two-step Ko-Lernen choice in the assistant panel. Add mockups of both options, the handover's
sources, and sequence diagrams of both placements with the folders of their components.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…gs as steps

Q22 gets options a) and b) with a mockup on the Railway page. b), the
proposal, keeps F26's text and adds a logout hint, because the
questionnaire comes only after the logout. The plan's status moves into
the step tables: Commit(s), Findings, Category and Severity columns
replace the Done column and the Carried out and Remaining tables, and the
five open findings become steps S18 to S22.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ions

Q22 b) adds one view to the Szenario-Loader, which already checks the end
condition, while a) needs that check too plus a centre-panel state in
Context.vue. The difference is a few lines, so the choice rests on what the
study used and on the logout hint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…art dialog

Q22 is decided as b): F26's end text in the Szenario-Loader with a logout
hint, as the questionnaire comes only after the logout. Q23 is decided as a):
the single run with the scenario dropdown stays. With the Testprotokoll
dropped, that leaves only d) for Q13, so the start dialog offers the
Experiment and the single run. F21, F26, section 1.7, Q3 d) and S12 follow,
and S12 and S13 are no longer blocked by a decision.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Q19 gets option c), the mode only in the progress bar, as in railway_sim's
Experiment banner, with a mockup of a) to c) and their costs, advantages and
disadvantages. A state label would repeat the decision prompt and the start
dialog. F23, the components table, Q3 d) and S12 follow, and S10 is no
longer blocked by Q19.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…unblocks every step

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…Railway events and contexts

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…receive the operator's choice

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…y the simulator

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
chenkins and others added 23 commits November 11, 2026 19:29
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…re panel

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… action in Ko-Lernen

The assistant shows a simulator decision's options with the scenario KPIs and applies the chosen
one; in Ko-Lernen the operator picks a train, then an action (not offered: greyed out; infeasible:
the reason), and proposes it. The choice is posted to the simulator through the new /railway-simu/
nginx location (RAILWAY_SIMU_UPSTREAM, default host port 5124) in every nginx config, start-webui.sh,
the env examples and compose files. Catalog recommendations still go to /transport_plan.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…reflection questions at logout

A start dialog over the Railway page (shown while no run goes on and the simulator answers
GET /api/v1/scenarios) starts the Experiment or a single run for the login's trace session id,
shows each run's introduction with "Weiter" and the end screen with the logout hint. A bar above
the timeline shows the progress, the mode and "✕ Beenden". The post-logout survey gets a Railway
chain with the reflection questions in German. The Cypress spec starts its runs in the dialog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Railway CI workflow runs the simulator's tests (including the check that both
recommendations.json files match the scenario files) and the Event, Context and Recommendation
services' Railway tests with the dev stack's requirements. The Cypress spec stays a manual run on
the dev stack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… screenshot

The spec plays scenario 2 in Empfehlungsmodus and scenario 3 in Ko-Lernen from login to their end,
and shoots scenario 3 at its decision in the state of railway_sim.png (14-compare). The Railway
README compares both side by side and lists the remaining differences. All shots are refreshed in
docs/plans/railway-use-case/shots/, including 07–12 of the decision panel and the start dialog.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Dockerfile and its own compose run the simulator on the platform's host (restart:
unless-stopped, idle until the start dialog starts a session), reached through the frontend's
/railway-simu/. The frontend image is built with VITE_RAILWAY_SIMU=/railway-simu, and the start
dialog ignores a scenario list that is not one (nginx's index.html without the location). The
users service seeds the cabProcess perimeter of the Dispatcher, Planner and Supervisor groups, so
railway_user gets its cards on a fresh database without loadTestConf.sh. READMEs: deployment,
variables, port 5124 and a checklist before a session. The Kubernetes nginx location and
RAILWAY_SIMU_UPSTREAM value wait for the simulator's address on the server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ubernetes route as S23

Every step's Commit(s) column is filled and its shots are linked from docs/plans/railway-use-case/
shots/ (07–12 committed with S13, 14-compare added). Phases 3, 4 and 6 are done. The Kubernetes
part of S15 moves to S23, blocked by the new Q30 on where the simulator runs on the server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… recorded them

Findings 1-5 name 091b3cc, which recorded Q4, Q2, Q6, Q8 and Q10; their PR threads stay open
until they are resolved on GitHub. The header notes the re-check at the pushed head.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…m the Szenario-Loader

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the progress bar

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ction shot

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…steps S28 to S44

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… steps and phases done or open

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…starts

Railway's feed shows only the running scenario's cards: a card's
session_id and scenario_id must match the latest context, and between two
runs, while the next introduction shows, the feed is already empty. The
simulator only sends, so nothing is deleted; cards of other publishers and
every card without a Railway session stay. The filter lives in
entities/Railway/feed/ and reaches the shared feed through its sections
option. The timeline still lists the earlier runs' cards.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…table

The train table ("Zugtabelle") gets "Von" and "Nach" columns: the station
at the first and the last cell of the train's route, from the scenario's
infrastructure ("–" when no station is there). Texts in German, English
and French; the table's cells no longer wrap.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…its direction

In the Kartenansicht each train is a pill along its track, as long as its
name needs (about 2-3 cells), with the name inside and a "▶" at its front
in the direction it runs; north and south trains stand upright, so the
name is never upside down. The tag above the train is gone, and with it
the "+delay" label that arrived trains, which are not drawn, never showed.
Held trains stay red, highlighted ones keep their orange outline. Shots
04-map, 06-status and 14-compare are refreshed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…resolved PR threads

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The trains now carry their name and a ▶ on the map, and each scenario
starts with an empty feed: retake 01, 02, 03, 07, 08, 09, 10, 12 and 17
from the Cypress spec of c67f8a1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant