wangxuming/XQKqueue
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: establish integrated project memory

Browse Source
This commit is contained in:
brother7
2026-08-12 19:33:12 +08:00
parent 50ac5bddc4
commit 1eb36645e4
31 changed files with 872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.project-docs/20-architecture/system-overview.md Normal file
View File

@@ -0,0 +1,32 @@
# System Overview
## Current Architecture
XQKqueue is a modular monolith. A Go HTTP service owns business rules and writes to PostgreSQL. One React/Vite application supplies staff, visitor, administrator, and browser-display routes. A separate native Android application consumes only privacy-safe public display endpoints for dedicated large screens.
## Main Components
| Component | Responsibility | Notes |
|---|---|---|
| Go service | Authentication, queue commands, public/read models, audit, maintenance, and HTTP transport | Standard-library router plus GORM; sole write authority |
| PostgreSQL | Projects, sessions, tickets, call batches, users, idempotency, revisions, and audit history | Versioned SQL migrations |
| React web application | Staff H5, visitor ticket/status pages, administrator UI, and browser display surfaces | REST writes and interval polling; the server SSE endpoint is not currently consumed by the web client |
| Native Android display | Overview and project-specific public display UI, polling, offline state, and project-detail announcements | Android Views; no WebView or system TTS |
| Delivery/scripts | Migrations, seed data, smoke tests, container/local startup, and APK handoff | Production must migrate before API start and must not run demo seed |
## Important Boundaries
- Queue selection, duplicate enforcement, ticket numbering, and revisions belong to the service transaction boundary, never a client.
- Public DTOs are allowlisted projections and must never include encrypted or hashed personal fields.
- Android overview and project screens are distinct states; only a valid project screen may create the announcement coordinator.
- A project snapshot is the Android project screen's single source for both rendering and new-call detection.
- Browser and Android displays may share API semantics, but neither should import or emulate privileged staff/admin behavior.
## Related Decisions
- [ADR-001: Native Android large-screen application](../10-decisions/adr-001-native-android-display.md)
- [ADR-002: Embedded audio announcements](../10-decisions/adr-002-embedded-audio-announcements.md)
## Last Updated
2026-08-12