docs: establish integrated project memory

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

@@ -0,0 +1,37 @@
+# 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