# 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