Skip to main content

J-18 — Submit Daily Guest Registration to Authority

One-liner: Receptionist generates and submits the daily guest registration report to the local authority (jurisdiction-specific).

1. Purpose​

Where required by law (Afghanistan + many jurisdictions), generate and submit the daily list of registered guests to the local authority. Outcome: report submitted on time; receipt stored; offline-tolerant.

2. Persona Context​

  • Persona: Receptionist (operator) / Compliance admin (configurer).
  • Surface: Electron Desktop.
  • Primary BFF: bff-backoffice-service.
  • Backing services: identity-verification-service, reporting-service, compliance-adapter, audit-service.
  • Preconditions: Authority integration configured for tenant's jurisdiction.
  • Trigger: End-of-day automatic prompt OR manual "Submit registration" CTA.

3. Entry Points​

#EntryNotes
1EOD promptDefault
2Manual CTAAdhoc

4. Screen-by-Screen Flow​

4.1 RegistrationPreviewScreen​

  • Layout: List of registered guests today (name, ID type, ID number, room, check-in time); excluded guests (e.g., walk-in not yet captured) with action.
  • Components: RegistrationTable, MissingDataBanner, Button ("Submit to authority").
  • Offline: Reads from SQLite; submission queued.
  • AI: Phase 2 — auto-detect missing fields.
  • Errors: Missing fields warning.
  • Loading: Sub-200 ms.
  • A11y: Table semantics.
  • RTL: Mirror.
  • Perf: <= 200 ms.
  • Telemetry: frontend.registration.previewed.

4.2 SubmissionStatusScreen​

  • Layout: Submission status (in-flight / sent / failed), authority response code, receipt number, receipt PDF download.
  • Components: StatusPill, ReceiptDownloadButton.
  • Offline: Status pill = "Queued for submission - will send when online".
  • AI: None.
  • Errors: Authority 5xx -> retry; rejection -> drilldown to corrections.
  • Loading: Submission <= 30 s wall-clock.
  • A11y: Status announced; receipt link labelled.
  • RTL: Mirror.
  • Perf: Submission <= 30 s.
  • Telemetry: frontend.registration.submitted { status }.

5. State Machine​

6. Data Requirements​

6.1 Server state​

  • GET /api/v1/registration/today
  • POST /api/v1/registration/submit (idempotent; returns receipt)

6.2 Local persistence​

  • SQLite registration_submissions_local, outbox.

6.3 Idempotency​

  • All mutations carry X-Idempotency-Key.

7. AI Behavior​

n/a in P1; P2 — auto-detect missing fields + suggested corrections (HITL).

8. Offline Behavior​

  • Reads from SQLite.
  • Submission queued; receipt comes back on reconnect.

9. Error States​

ErrorTriggerUX shownRecoveryTelemetry
MISSING_REQUIRED_FIELDSPer-guest missing fieldsBanner + per-row markerReceptionist completesfrontend.registration.missing_fields { count }
AUTHORITY_REJECTIONAuthority 4xxDrilldown to invalid recordsCorrections + resubmitfrontend.registration.rejected
AUTHORITY_5XXServer errorBanner + retryRetry / queueerror.surfaced { code }
OFFLINE_QUEUEDOffline submitStatus: "Queued"Reconnectfrontend.registration.queued

10. E2E Test Gates​

  • Composite gate G-COMP-1: preview -> submit -> receipt; rejection -> corrections -> resubmit.
  • Offline -> reconnect -> auto-submit.

11. Performance Requirements​

MetricTarget
Preview mount<= 200 ms
Submission<= 30 s p95

12. Accessibility Requirements​

  • All keyboard-completable.
  • Status announcements.
  • Receipt link clearly labelled.

13. Telemetry​

Frontend events​

  • frontend.registration.previewed
  • frontend.registration.submitted { status }

Domain events emitted​

  • melmastoon.compliance.registration.generated.v1
  • melmastoon.compliance.registration.submitted.v1
  • melmastoon.audit.recorded.v1

14. Success Criteria​

  • Submission completes <= 30 s p95.
  • Receipt stored locally + remotely.
  • Offline path proven.
  • Rejections route through corrections.

References​