Skip to content

docs: publish architectural and mathematical audit on /docs - #62

Merged
fjarmula merged 4 commits into
mainfrom
docs/app-logic-audit
Oct 30, 2026
Merged

fjarmula merged 4 commits into
mainfrom
docs/app-logic-audit

Conversation

@fjarmula

@fjarmula fjarmula commented Oct 30, 2026 •

Copy link
Copy Markdown
Member

Summary

The architectural and mathematical audit is now available directly on /docs#logic as System logic / Logika systemu, in Polish and English. It includes readable mathematical notation, text state diagrams and the complete engine/ETL parameter reference, rather than requiring visitors to open a GitHub document.

  • Explain mode/configuration precedence, routing and resource policy, nominal versus simulated journey times, rolling motion, TTI/cascade/hold equations, deterministic outcomes, request/intersection/signal lifecycles, savings, SSE and mock/backend differences.
  • Record model limitations and configuration gaps; correct overview wording about per-stop-line penalties and resource-aware ranking.
  • Retain the source-linked Markdown audit in docs/architecture/system-logic.md and remove the redundant Live demo header button.
  • Reuse the existing docs layout; formula/state figures are keyboard-scrollable and have no shell-command copy control. No new dependency.

Verification

  • Backend audit baseline: uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest — passed; 1,553 tests. Follow-up does not modify backend code.
  • Final frontend: npm run lint && npm run typecheck && npm run format:check && npm test && npm run build — passed; 1,286 tests across 127 files. Existing Vite native-config compatibility warning remains.
  • Test-first failures reproduced missing hash navigation, tab, formula renderer and in-app content before implementation. Docs-content checks include PL/EN structural parity.
  • Playwright CLI against the production build, PL and EN at 1440, 390 and 320 px: direct /docs#logic selection, 16 formula blocks, substantive parameter content, no page overflow, keyboard navigation and browser back all passed. Live demo remains absent.
  • Independent source/UI review; both findings corrected (TTI re-eligibility transition and Polish diagram annotations). Diff and audit-source links checked.

Contract or safety impact

No backend runtime, schema, generated contract, dependency or signal-actuation changes. Reference parameter data is client-safe documentation, not runtime configuration. Findings describe the simulation and make no physical accuracy or operational safety claim.

Follow-ups

The in-app findings and source-linked audit identify future work on zero-speed TTI, hold bounds, rolling-floor assumptions, timing consistency and calibration. No such runtime behavior change is included.

Document implemented modes, configuration, routing and timing equations, ITS lifecycles, signal schedules, and model limitations with source references.

Remove the redundant Live demo link from the documentation header and update its assertions. Verify both quality suites and the production docs page.
@fjarmula
fjarmula requested a review from piotr-lorek as a code owner October 30, 2026 07:38
Add the bilingual System logic tab at /docs#logic with mathematical notation, state diagrams, parameter references and implementation findings.

Preserve the repository audit, correct overview claims and verify all frontend checks plus desktop and phone browser navigation.
@fjarmula fjarmula changed the title docs: audit application logic and simulation mathematics docs: publish architectural and mathematical audit on /docs Oct 30, 2026
@fjarmula
fjarmula merged commit 93b5c30 into main Oct 30, 2026
6 checks passed
@fjarmula
fjarmula deleted the docs/app-logic-audit branch October 30, 2026 08:56
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.

2 participants