Repository navigation
Restructure the repository and document the system - #1
Merged
Merged
Conversation
Files were sitting flat in the repository root. Group them by role so the layout reflects how the system actually runs: the reader pipeline and the kiosk UI are separate processes that talk over a FIFO. card_gui.py -> src/gui/ parse_card_data.cpp -> src/reader/ run_ctls_read.exp -> src/reader/ fifo_writer.cpp -> src/tools/ start_all.sh -> deploy/scripts/ bus-kiosk.service -> deploy/systemd/ idtech-expect -> deploy/sudoers.d/busvalidator-reader.example The sudoers fragment kept a name that said nothing about what it was.
Nothing described how to build the two C++ targets or which PyQt5 version the interface expects, so both had to be rediscovered on every fresh device. validator.env.example lists every path, account and endpoint the system depends on. The prototype still has these compiled in; the file documents them now and becomes the source of them later. The ignore rules cover validator.env itself, which names the production endpoint and must never be committed.
Six documents covering what was previously only in the author's head:
ARCHITECTURE why three processes and a FIFO rather than one program
PAYMENT_FLOW EMV tag parsing, the offline queue, the FIFO protocol
HARDWARE the bill of materials, and why each sensor was chosen
over the alternatives that were evaluated
DEPLOYMENT a fresh Pi to a running unit, with a troubleshooting table
SECURITY_NOTES the gaps in this build, stated with their fixes
ROADMAP what is next, in dependency order
SECURITY_NOTES is deliberate. The build logs an unmasked pan, shells out to
curl with card-derived data, and runs the reader under a sudo rule that is
root in practice. Undocumented, those are traps for whoever deploys this
next.
CI builds both C++ targets, syntax-checks the Python and runs shellcheck. PyQt5 is not installed on the runner: the interface needs a display and the packaged Qt build, so importing it there would only produce a failure that says nothing about the change under test. Shellcheck runs at error severity. The startup script carries one known warning, SC2024, where a redirect on a sudo line is performed by the calling user; that is tracked rather than silenced. The issue templates ask for the reader and display model, since those are where behaviour that does not reproduce usually comes from, and both warn against pasting a real card number.
The README was a title and two screenshots. It now describes what the terminal does, the closed-loop system it replaces, the hardware it runs on, how to build and deploy it, and what is not finished. The capability table marks each feature as implemented, in development, planned or research, with a note that several subsystems are not yet published. Claiming the unbuilt parts would not survive the first person who looked. Apache 2.0 for the licence: it grants patent rights explicitly, terminates them for anyone who sues over them, protects the project name, and requires anyone who forks to say what they changed. The sudoers fragment gains a security note explaining that a NOPASSWD rule pointing at an expect script is effectively root, how to harden it, and how to remove the need for it with a udev rule. The rule itself is unchanged; the note is dated so it is clear it was written after the fact.
The LinkedIn link already carries it, and the README does not need to state it twice.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this changes
The repository was eight files in the root with a three-line README. This groups the sources by role, adds the documentation the project never had, and sets up a build and CI.
src/(gui, reader, tools), deployment material intodeploy/, configuration intoconfig/. All moves aregit mv, so file history is preserved.docs/: architecture, payment flow, hardware, deployment, security notes and roadmap..gitignore.idtech-expectis renamed todeploy/sudoers.d/busvalidator-reader.exampleand gains a dated security note explaining that a NOPASSWD rule pointing at an expect script is effectively root, how to harden it, and how a udev rule removes the need for it. The rule itself is unchanged.No behaviour changes. Every source file is byte-identical to what was on
main.How it was tested
cmake -B build && cmake --build build)CI steps were run locally before pushing: CMake build,
python -m compileall,ruff check, andshellcheck --severity=error. All pass.Checklist
docs/updatedCHANGELOG.mdupdated