zaparoo-core: a Go service that reads NFC cards, drives MiSTer hardware and syncs over MQTT

The README is a contributor grid, so the module file is the real documentation

The first paragraph of the README says this is the development repository for Zaparoo Core, and then points two ways out of it: to zaparoo.org for information about the project, and to a downloads page for binaries for your platform. Everything after that is a table of contributor avatars, one section for sponsors, and the licence. The contributor list is not padding, it is a naming convention, because the block is fenced with readme contributors start and readme contributors end markers, which means a bot regenerates it from commit history. The sponsors section is a single line about Windows code signing. So for anyone trying to learn what this service does, the README is close to silent, and the useful description turns out to be the dependency list, which is unusually long and unusually specific about hardware. A reader who opens go.mod learns more about the scope of the project in one pass than the front page gives.

Two NFC stacks and a smart card library, which is the service's centre of gravity

Four dependencies point at the same subsystem. There is a PN532 library, the chip family used in cheap NFC reader boards, at version 0.26.0 and maintained under the same GitHub organisation as this project. There is an NDEF library for reading and writing the tag format itself, and a second NFC library at v2 from a different author. And on Windows there is a smart card access library, which is how a PC reads contactless cards through its own credential path. Two more entries place the service physically: a library for synthetic input devices, which is how a tag read can turn into a keypress, and a Windows named pipes library, which is how a native component talks to the Go process on that platform. Put together, the picture is a service whose primary job is turning a physical card or tag into an action on a machine, across three different card interfaces, with the synthetic input path being what makes that invisible to the software being controlled.

A separate mister module and a VDF parser for MiSTer configuration

MiSTer support is not a folder of adapters inside the main module, it is a module of its own. The dependency list includes the same project at two paths, the core module and a mister submodule, which means the MiSTer specific code is versioned independently and imported rather than inlined. The support is deep enough to have its own configuration parser: a VDF library appears in the requirements, and VDF is the format the MiSTer firmware uses for its own configuration, so the service can read and write the same files the console does. Alongside that sit libraries for talking to a console and for audio, a beep player and a mixer, which suggests the service can play sound on a MiSTer as well as read its files. The repository tree carries the mister/ directory at the top level next to cmd/, internal/ and pkg/, so the separation is visible in the layout as well as in the module path.

SQLite on disk, MQTT on the network, websockets for live data

The storage and network choices are both visible as single dependencies. Persistence is SQLite, through the cgo backed driver, paired with a mock driver for tests and a RoaringBitmap library for compact set operations over identifiers. Network reach runs through an MQTT client, which is the mechanism a multi device setup would use to tell one place that a card was tapped, and a websocket client for live connections in the other direction. Two supporting entries matter for how the service behaves rather than what it stores: a clockwork library for controlling time, and an OS statistics library. There is also a Sentry client in two forms, one plain and one wired to a structured logger, so error reporting to a hosted service is part of the build rather than an add-on. Privacy conscious operators have that to consider, and nothing in the README mentions it either way, so the configuration default is the thing to check.

A system tray library, a template engine, and a Windows dialog package

Three dependencies describe a desktop presence rather than a headless daemon. A system tray library from the Fyne project puts an icon in the notification area, which is how a service that runs continuously can be started, stopped or checked without a window. A dialog package gives it modal prompts, and the Windows OLE and winio libraries give it native Windows integration including the file picker. A compiled expression language appears in the list, which is the kind of dependency that implies user supplied logic is evaluated at runtime rather than only configuration being read. There is also a terminal UI library, a text editor library, and an image matching library with an edit distance implementation, which together suggest text input handling and fuzzy matching of titles or paths. Read together with the tray, these say the service is expected to run on a machine with a person sitting at it, not only on a server.

Trademarks are licensed here only, and must be stripped if you redistribute

The most consequential line in the README is not about code. This repository contains Zaparoo trademarks which are explicitly licensed to the project in this location by the trademark owner, and those trademarks must be removed from the project or replaced if you intend to redistribute or adapt it in any form, with the Zaparoo Terms of Use page carrying the detail. So the code and the marks travel under different terms. The source is GNU General Public License v3.0, which is a strong copyleft grant and lets you fork, modify and redistribute with the same licence. The name does not follow that grant. Anyone building a fork, a derivative service or a rebranded installer has to rename it, which is a real obligation rather than a formality, and it is stated in the same README that invites contributions, so it is not a surprise waiting to be discovered later.

A Taskfile, a golangci config, a codecov file and an AGENTS.md

The top level describes a repository with conventional Go tooling and one unconventional file. There is a Taskfile.dist.yml, the distributed form of a Task runner file, so build and test steps are run through a task tool rather than a wall of make targets. There is a golangci configuration for the linter, and a codecov configuration for coverage reporting. A TESTING.md sits next to the README, which is where a reader should look for how to run the suite, and a docs/ directory for anything longer. An AGENTS.md is present, which in this ecosystem holds instructions for automated coding agents working in the repository, alongside a scripts/ directory and a testdata/ directory for fixtures. The presence of both an agent instruction file and a testdata directory in a service that drives physical hardware is telling: the project is set up for a large number of contributors to change it without a machine in front of them.

Editorial conclusion

This repository is worth reading if you want to understand what the Zaparoo service actually touches, because the go.mod is a candid inventory of the hardware and protocols involved, and it names things a marketing page would not: a PN532 NFC reader library, NDEF tag parsing, Windows smart card access, an SMB client, a VDF parser for MiSTer configuration files, a system tray library and an expression language. It is the wrong place to start if you want documentation, since the README is a contributor table with a downloads pointer, and the project documentation lives on zaparoo.org rather than in the tree. Before building it, check three things: the Go version, which go.mod pins to 1.27.1, and the module path, which carries a v2 suffix, so any import in your own code has to match; the licence and trademark terms together, since the code is GPL-3.0 but the Zaparoo trademarks are licensed to this repository only and must be removed if you redistribute or adapt the project; and the platform targets, since a dependency on Windows smart card access and another on a desktop system tray both imply behaviour that will not exist on a headless Linux host even though the code compiles there.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes