# SMART SCHOOL Beta 1.0 – Blueprint

## Architecture
Existing PHP Native CMS remains the system of record for public website and existing users/students. This package adds a namespaced `ss_*` extension schema, attendance service, device-authenticated scan endpoint, WhatsApp consent/template/queue tables, Meta Cloud API worker, and webhook receiver.

## Attendance flow
1. QR/barcode/NFC reader obtains an opaque card credential.
2. Device posts transaction UUID, credential, method, event type, device code and scan timestamp to the attendance API.
3. API authenticates the device token, resolves the card by SHA-256 credential hash, records immutable scan log and updates the daily attendance projection in one DB transaction.
4. A production event dispatcher must create a WhatsApp queue event after commit, only for contacts with approved consent and an approved template.
5. Worker sends the approved Meta template; webhook updates delivery state.

## Device notes
- USB barcode readers in keyboard-wedge mode can feed a browser input.
- USB NFC readers generally need PC/SC middleware/local bridge.
- Android NFC should use a Kotlin app and supported NFC APIs.
- Web NFC is not universal and must not be assumed on desktop browsers.
- Do not trust plain card UID as an authentication secret. Prefer cryptographic NFC cards and secure key management.

## WhatsApp notes
- This package targets the official Meta WhatsApp Business Platform Cloud API.
- School owns the gateway application, database, queue, templates mapping, dashboard and webhook processing.
- Meta remains the message transport provider; this is not an independently implemented WhatsApp protocol.
- Obtain opt-in, use approved templates for proactive messages as applicable, honor opt-out, and follow current Meta policies/pricing.
- Webhook signature uses `X-Hub-Signature-256` HMAC SHA-256 with the Meta app secret.

## Production gaps
The beta scan handler is a foundation, not final attendance policy. It does not yet implement schedule/holiday/session resolution, late rules, checkout policy, attendance event outbox, parent relationship resolution, notification enqueue transaction, complete status webhook normalization, or a complete RBAC/admin UI. Add these before production.
