XQKqueue/.project-docs/20-architecture/module-map.md

Module Map

Source Layout

Path	Responsibility	Owner Notes
server/cmd/api	API process entry point	Keep startup configuration and lifecycle thin
server/internal/httpapi	HTTP routes, authentication boundaries, queue transactions, public projections, history, events, and currently unregistered ticket-transition/reissue handlers	High-risk concurrency and privacy boundary; do not assume a handler is exposed without checking Server.Handler()
server/internal/domain	Pure queue selection and display-number rules	Prefer deterministic unit tests
server/internal/model	Persistent domain structures and constants	Coordinate changes with migrations
server/internal/database	Database connection and maintenance/purge operations	Personal-data lifecycle is sensitive
server/internal/security	Encryption, digests, password/session helpers	Never log or expose secrets/PII
server/migrations	Ordered PostgreSQL schema changes	Production migrations precede API rollout
web/src/pages, components, hooks, lib	Browser routes, presentation, state hooks, and API client	One application serves multiple role-specific surfaces
android/app/src/main/java/cn/nianxx/queue/display	Native navigation, API client/parser, polling, Views, formatting, announcement state, WAV composition/playback	Overview must remain audio-free
android/app/src/main/res/raw	The exact embedded Mandarin announcement fragments	Format and file set are regression-tested
deliverables/android	Installable debug APK, checksum, and handoff notes	Must match the verified build output
scripts	Database setup, seed, smoke, and integration-test orchestration	Do not run demo seed in production

Dependency Direction

• Clients depend on public/service contracts; they do not own queue transitions.
• HTTP handlers may use domain, model, database, and security modules; pure domain code should not depend on transport/UI concerns.
• Android Views consume parsed display models; announcement playback consumes validated call text and embedded assets.

Risky Or Sensitive Areas

• server/internal/httpapi/staff.go: transactional queue writes, duplicate handling, FIFO selection, revisions, and audit.
• server/internal/httpapi/public.go: privacy-safe public projections and public ticket protections.
• server/internal/httpapi/reissue.go and ticket-transition logic: implemented business paths are currently not registered in Server.Handler() or wired in the web client; treat them as inactive until routes and integration tests are added.
• android/.../MainActivity.java: screen-state, poller, and announcement lifecycle boundary.
• android/.../QueueAnnouncementPlayer.java and EmbeddedWavComposer.java: cross-thread native audio lifecycle and asset validation.
• android/.../SingleLineFitTextView.java: business-critical full range-number visibility across device fonts/densities.

Last Updated

2026-08-12