Data Flow

Primary Flows

Flow	Source	Destination	Notes
Take ticket	Staff/visitor client	Go service -> PostgreSQL	Validates project/session and party size, enforces idempotency/rate limits as applicable, checks same-phone WAITING duplicates, encrypts personal data, increments session revision
Call next	Staff client	Go service transaction -> PostgreSQL	Locks project/session, selects a contiguous FIFO prefix by ticket or people target, writes one call batch, updates tickets/revision, emits audit/event state
Browser display	Browser route	`GET /api/display/overview` or `GET /api/display/{identifier}/snapshot`	Read-only privacy-safe projections; identifier accepts project code or compatible display token
Android overview	`MainActivity`	`GET /api/display/overview` every 5 seconds	Renders project cards; no announcement coordinator exists
Android project display	`MainActivity`	`GET /api/display/{identifier}/snapshot` every 3 seconds	One response updates UI and announcement detector; first snapshot establishes a silent baseline
Android announcement	New current call batch	`AnnouncementCoordinator` -> embedded WAV composer -> `AudioTrack`	Number/range only, FIFO, three repetitions, canceled on pause or screen change

PostgreSQL owns durable queue state; the queue-session revision is the recovery/version signal.
The Go service owns all mutations and public projection allowlists.
Web and Android clients own only presentation caches, polling lifecycle, and transient UI state. The service exposes authenticated staff SSE, but the current web client does not consume it.
Android AnnouncementCoordinator tracks only the current project-screen baseline/deduplication state and resets when the screen stops.

Public display: GET /api/display/overview, GET /api/display/{identifier}/snapshot.
Public visitor: project listing, ticket creation, and private token status. The public phone lookup endpoint is a development/operational-test path and returns 404 in APP_ENV=production until replaced by OTP or an external identity provider.
Internal lookup: the same active-ticket phone lookup is restricted to private-network requests.
Staff/admin: separate authenticated route groups and cookies; staff queue reads/ticket creation/call-next, admin project/user/history APIs, and an authenticated staff SSE endpoint.
Implemented-but-unregistered: ticket transition and missed-ticket reissue handlers exist in source but have no Server.Handler() routes or current web integration; they are not part of the active external interface.
Android deep links: https://queue.nianxx.cn/admin/display and https://queue.nianxx.cn/display/{identifier}.
Android audio assets: android/app/src/main/res/raw/voice_*.wav.

2026-08-12