# quota-monitor: Feishu alerts when Hong Kong ID appointment slots appear

> A small monitor that watches the Hong Kong Immigration Department's published appointment quota for identity card replacement and pushes a Feishu group broadcast plus targeted direct messages when slots are released. Subscribers filter by date, by office or by both, and a public dashboard tracks release patterns.

**Zheyi-D/quota-monitor** — Real-time monitoring of Hong Kong Immigration Department ID card renewal appointment quotas, with dual notification channels via Feishu group and HTML email, fully automated with GitHub Actions.

- Repository: https://github.com/Zheyi-D/quota-monitor
- Stars: 32 · Forks: 6
- Language: JavaScript
- License: MIT
- Published: 2026-08-21 · Updated: 2026-08-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/zheyi-d-quota-monitor

## It watches one published number: the replacement appointment quota

The scope is narrow and worth being precise about. The monitor tracks the appointment quota published by the Hong Kong Immigration Department for replacing an identity card, and the acknowledgements name the exact source as the department's appointment quota preview enquiry page on eservices.es2.immd.gov.hk. There is no scraping of private data and no credentialed access to any government system: the project states that it only reads quota data the department publishes. That constraint is also why the tool is a notifier rather than a booking system. It tells you that a slot opened at an office on a date, and the appointment itself still happens through the department's own channels, including the phone booking route covered by the tutorial linked from the dashboard.

## Two channels fire together, but the group is the faster one

When new quota is detected the push order is fixed. A group broadcast goes out first, in parallel across multiple groups, and private direct messages go out in parallel too, but only to subscribers whose date filter matches. The two are described as arriving almost simultaneously. The caveat sits in the other direction: the direct message bot has a one to two second delay, so the README recommends joining the group when you are in a hurry. That asymmetry explains why joining the group is presented as the recommended route, with the promise that messages arrive instantly and that joining requires no configuration at all. Multiple groups are supported with automatic diversion when one fills up, and the group details and joining instructions live in a Feishu wiki page rather than in the repository.

## Subscriptions are typed text, ranges included

The direct message route starts by sending any message to the bot, which replies with an interactive card. The card offers three actions: subscribe to specific dates, subscribe to every date, or view, change and cancel an existing subscription. You can also skip the card and reply with dates directly, in a compact form such as `08/15, 08/20-08/25`, which shows both single dates and ranges are understood as plain text rather than picked from a calendar. Three filter modes are supported underneath: by date, which ignores the office, by office, which ignores the date, and by date plus office, which is an exact match. That last mode is the one that matters if you book at one counter on one day, since it is the only way to avoid alerts for slots you cannot use.

## The dashboard tracks release patterns, not just current state

The public dashboard is published at the project's GitHub Pages site and covers the whole territory rather than a single filter. It shows live quota status for every office in Hong Kong, and adds a heatmap of release patterns that visualises how often slots appear in each time slot, which is the piece of information a person actually plans around. Alongside that is a phone appointment tutorial. There is also a built-in administration backend, described as supporting subscriber management, a statistics overview and dual-channel mass sending, so the same interface that shows the public data is where an operator would manage the audience. That last feature is the one to think about before exposing anything, since mass sending is a broadcast capability rather than a read-only view.

## The package is Python while the repository is labelled JavaScript

The packaging metadata says one thing and the repository labels another. `pyproject.toml` names the project `quota-monitor` at version 1.0.0, declares MIT licensing, requires Python 3.8 or later, lists exactly one dependency, `requests` at 2.25 or newer, and exposes a console script named `quota-monitor` bound to `quota_monitor.monitor:main`. The project description and readme are in Chinese, matching the audience. Yet the repository's primary language is recorded as JavaScript. The build backend is also the legacy underscore form of setuptools rather than the usual dotted name, which is a small signal that this manifest has been carried forward rather than regenerated. None of this breaks anything for a user, but it means language-based search and filtering will mislead you.

## The root file list shows three runners and a state file

The tree explains the shape of the system without any architecture document. At the root there is `monitor.py`, `ci_run.py` and `welcome_runner.py`, three separate entry points alongside the `quota_monitor/` package, plus `feishu-ws/` for the Feishu WebSocket connection, `workers/` and `data/` directories, and a `web/` directory for whatever serves the dashboard. Two files stand out. `config.example.json` tells you configuration is supplied by copying a template, which is the only hint that credentials such as the Feishu app secret are needed at all. `state.json` sitting in the repository root, rather than under `data/` or ignored by git, suggests runtime state is a plain file next to the code, so a self-hosted operator should decide deliberately whether that belongs in version control.

## Subscriber data is encrypted, and the data read is public

The privacy section makes two claims. Feishu user data is stored with AES-256-GCM encryption and is not readable in the repository, which is the sensible minimum for holding identifiers about real people. And the monitor only reads quota data the Immigration Department publishes, so there is no scraping of anything personal. The disclaimer underneath is the part to keep in view: the system is a third-party open source tool and not an official Hong Kong Immigration Department service, and you should defer to the official site. The encryption design is not detailed in the README itself, which sends you to ARCHITECTURE.md for self-hosting, technical architecture and the encryption scheme. Anyone standing up their own instance is pointed at that document rather than at the overview.

## MIT licensing carries a non-commercial caveat on top

The license line reads MIT, credited to Deng Zheyi, and directly beneath it there is a further note stating that the open source project is for learning and exchange only and should not be used for any commercial profit purpose. That is worth pausing on, because MIT as a license does not contain a non-commercial restriction, so the practical effect is that the repository grants broad permission while asking for something narrower in prose. Anyone planning to run this as part of a paid service has to decide which instruction governs. The acknowledgements add two attributions: the department's quota preview page as the data source, and a Xiaohongshu blogger credited for the phone booking tutorial, so if you reuse that material the credit travels with it.

## Conclusion

Use this if you are waiting on a specific identity card appointment date at a specific office and you want a push the moment capacity appears, because the date filter is the feature that makes it usable rather than merely noisy. Do not treat it as authoritative: the project states plainly that it is a third-party tool and not an official Immigration Department service, and that the official site wins. Before you rely on it, read ARCHITECTURE.md for the self-hosting and encryption detail, remember that subscription data is stored encrypted yet the license adds a non-commercial restriction on top of MIT, and check the GitHub Actions workflow yourself, since the README documents the alerts but not the automation that sends them.

## FAQ

### What is quota used for?

In this repository it means appointment capacity, not a filesystem or cloud service limit. The monitor tracks the identity card replacement appointment quota published by the Hong Kong Immigration Department and notifies subscribers when new slots are released.

### What does quota mean in files?

Not that here. Nothing in this project touches disk quotas or filesystem limits; the data it reads comes from the Immigration Department's public appointment quota enquiry page, and the only state it keeps locally is a state.json file in the repository root.

### How do I subscribe to quota-monitor without joining a group?

Send any message to the Feishu bot to trigger an interactive card, then choose to subscribe to specific dates, subscribe to all dates, or manage the subscription. You can also reply directly with dates in a compact form such as `08/15, 08/20-08/25`. Direct messages carry a one to two second delay.

### Can I run quota-monitor myself?

The project points self-hosters to ARCHITECTURE.md for self-hosting, technical architecture and the encryption scheme. The package installs as a console script named quota-monitor, requires Python 3.8 or later, and depends only on requests, with configuration supplied through a config.example.json template.

## Sources

- [Official README](https://github.com/Zheyi-D/quota-monitor#readme)
- [Project repository](https://github.com/Zheyi-D/quota-monitor)
- [README](https://github.com/Zheyi-D/quota-monitor/blob/main/README.md)
- [Releases](https://github.com/Zheyi-D/quota-monitor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/zheyi-d-quota-monitor