{"id":23415907,"url":"https://github.com/eightsq/mercurius","last_synced_at":"2026-05-18T19:34:09.038Z","repository":{"id":141466526,"uuid":"121580720","full_name":"EightSQ/mercurius","owner":"EightSQ","description":"a parcel tracking system (part of a coding challenge)","archived":false,"fork":false,"pushed_at":"2018-02-28T22:45:18.000Z","size":141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T06:28:35.471Z","etag":null,"topics":["meteor","webapp"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EightSQ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-02-15T01:27:13.000Z","updated_at":"2020-03-02T00:59:43.000Z","dependencies_parsed_at":null,"dependency_job_id":"377312b5-28fb-4801-897f-47b02dd76134","html_url":"https://github.com/EightSQ/mercurius","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EightSQ/mercurius","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EightSQ%2Fmercurius","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EightSQ%2Fmercurius/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EightSQ%2Fmercurius/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EightSQ%2Fmercurius/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EightSQ","download_url":"https://codeload.github.com/EightSQ/mercurius/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EightSQ%2Fmercurius/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274046000,"owners_count":25212982,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["meteor","webapp"],"created_at":"2024-12-22T21:28:54.452Z","updated_at":"2026-05-18T19:34:04.007Z","avatar_url":"https://github.com/EightSQ.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mercurius - a parcel tracking system\n\n\u003e Mercurius\n\u003e - römische Entsprechung zum griechischen Gott Hermes\n\n## Der Stack\nMercurius basiert auf dem Realtime-Framework [Meteor](https://www.meteor.com/) und arbeitet mit MongoDB als Datenbank. Vorteil liegt hier bei der Unterstützung von Realtime-Aktualisierungen in der Anwendung. Auf eine API für externe Anwendungen (wie sie z.B. zum Eingeben von neuen Sendungen in das System durch externe Systeme, oder durch interne System für das Routing nötig werden), wird in diesem Software-Stack verzichtet, da der eigentliche Fokus auf der Webanwendung liegt. Jedoch ist es ohne weiteres möglich, entsprechende APIs an die Datenbank anzubinden.\n\n**MongoDB** ist eine NoSQL-Datenbank, d.h. sie weicht von der strikten Normalisierung klassischer, relationaler Datenbanksysteme bewusst ab. Für unsere Zwecke eignet sich ein NoSQL-System dennoch gut, da wir so bei der Form der Daten flexibel sind, und ggf. später neue Datenformate (z.B. Kundennummern, Push-Notifications, Sondermeldungen, etc.) mit in die *documents* speichern können, ohne dafür aufwendig die Datenbankstruktur migrieren zu müssen (wie es bei einer klassischen Datenbankstruktur der Fall wäre. Zudem kann MongoDB Datenbestand wie auch Arbeitslast leichter als klassische Datenbanken auf mehrere Server verteilen, wodurch auch bei sehr großem Datenaufkommen (womit bei einem großen Versanddienstleister zu rechnen ist), das System skalierbar bleibt und nicht auf Grenzen der Erweiterbarkeit stoßen wird.\n\nFür das Frontend habe ich, abweichend vom \"klassischen\" *Blaze* von MeteorJS das Framework React verwendet. Dieses ermöglicht einen hohen Abstraktionsgrad der View-Componenten und so eine einfach zu realisierende Modularität der Applikation. Die verwendet Icons stammen aus der freien Auswahl von FontAwesome.\n\n## Die Sendungsnummer\nDie **HUPID** (Hermes Universal Parcel Identification Number) besteht aus 19 Ziffern. Ein Vorteil dieser Länge liegt darin, dass eine Zahl dieser Größe als *unsigned long long* mit 64bit, d.h. in 8 Bytes platzsparend gespeichert werden kann.\n\n![HUPID Blueprint](/blueprints/hupid_blueprint.png)\n\n### Type specifier\nMit einer Ziffer wird der Sendungstyp kodiert. Dieser steht von **0 - 5** für die Hermes-üblichen Typen Päckchen bis XXL-Paket. Die Ziffer **9** steht für Sperrgut. Die Ziffern **6-8** sind zwecks Erweiterbarkeit des Systems reserviert.\n\n### Unique Digits\n7 Ziffern genügen für 10 Mio. Sendungen pro Tag pro Tupel von Start-/ Ziel-Verteilzentrum bzw. Land. Diese Range erscheint ausreichend, um ein einfaches \"Raten\" von möglichen Sendungsnummern auszuschließen.\n\n### Origin-/ Destination-Center\nHermes unterhält 63 Paketzentren in Deutschland. Da der Unternehmensschwerpunkt in Deutschland sind, sind 63 Zahlen (aus zwei Ziffern) für jene reserviert. Mit den übrigen Zahlen können, für Sendungen aus, ins oder durch das Ausland, Länder kodiert werden. Die hier eingebauten Informationen über Start und Ziel der Sendung ermöglichen ein einfaches Routing in einem Paketzentrum, ohne dass dort zunächst das Ziel hinter einer Sendungsnummer etwa aus einer Datenbank herausgesucht werden muss.\n\n### Year specifier\nZwei Ziffern für die Jahresangabe reichen aus, um für 100 Jahre eindeutige Sendungsnummern zu haben.\n\n### Checksumme\nUm beim Eintippen der Sendungsnummer nicht ständig auf Fehler zu tappen, enthält die **HUPID** eine Checksumme, die aus einfach mit einer Art von Quersumme gebildet wird (Codebeispiel zur Implementierung [hier](https://github.com/EightSQ/mercurius/blob/24c555764da82f799ab2fc51a18afc31c95e892c/imports/api/helpers.parcels.js#L13).\n\n### Implementierung\nIn meiner Implementierung (dieser Anwendung) befindet sich die gesamte Logik das Generieren und validieren der HUPIDs im Backend. Das Frontend greift auf die entsprechenden Methoden über Meteor *methods* zu. (Siehe auch [hier](https://guide.meteor.com/methods.html#what-is-a-method))\n\n## Einrichtung\n\n1. Docker Container bauen: `docker build -t eightsq/mercurius .`\n2. Container starten: `docker run -d -p 3000:3000 eightsq/mercurius`\n3. Enjoy the show at [localhost:3000](http://localhost:3000)\n\n## Bedienung des Demo-Modus\n\nDie Grundfunktionalität ist stets unter [localhost:3000](http://localhost:3000) erreichbar. Unterhalb der Trackingnummer-Eingabezeile befindet sich ein Link \"Neue Sendung erstellen\". Dahinter verbirgt sich ein kleines Tool, mit dem Daten generiert und in die Datenbank injiziert werden können. Mit dem Tool lässt sich der Sendungstyp einstellen, in der Praxis gehört natürlich eine Ermittlung von Start- und Ziel-Paketzentrum mit dazu. Ein Klick auf \"Sendung erstellen\" erstellt die Sendung anschließend in der Datenbank. Die Sendungsnummer der erstellten Sendung erscheint nun als Link. Es empfiehlt sich, das Tracking (hinter dem Link) in einem neuen Tab zu öffnen, da die erstellte Sendung, einmal aus dem Tool heraus, nicht mehr über das Tool \"weitergebracht\" werden kann. Mit einem Klick auf auf \"Sendungsstatus erneuern\" lässt sich die bereits erstellte Sendung einen Transportschritt weiter schieben. Die Änderung lässt sich, dank Realtime-Push des Frameworks MeteorJS im anderen Tab mit der Tracking-View live beobachten.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feightsq%2Fmercurius","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feightsq%2Fmercurius","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feightsq%2Fmercurius/lists"}