​

OdontoX v1.8 Stable — internal release notes

​

What shipped in v1.8 — feature headlines

• Ruby Reception Cockpit — Day Brief, per-appointment Prep Hints, End-of-Day Wrap-Up (§2)
• Ruby Insights reorganised into Plan ahead / Collect / Recover, shared per-clinic cache, 15/day limit (§2, §3)
• Payment reminders — Email + WhatsApp send, edit-before-send, send history, 3/day cap (§3)
• Owner dashboard rebuilt — dental KPIs, Today’s Schedule worklist, Action Required panel, Provider Performance (§3)
• Personalised dashboard — drag / resize / hide widgets + redesigned Revenue chart (§3)
• Todos planner — task fields, assignees, tags, voice dictation, two-pane bucketed planner (§3)
• Calendar v2 — redesigned Day/Week/Month, zoom, utilization bars + heat strips, smart overflow (§3)
• Visiting doctors + unassigned bookings + reassignment (§3)
• WhatsApp for doctors & receptionists; automations editor; quotation/receipt attachments (§3)
• Service Catalog procedure picker; per-clinic per-role module visibility (§3)
• Sidebar order + one-click presets (Front Desk / Chairside / Billing); appearance Live Preview (§3)

• Analytics DB read-replica routing — reporting/dashboard/stats reads offloaded to the ep-icy-tooth read replica via getAnalyticsDb + ANALYTICS_DATABASE_URL (configured on prod)
• App-wide caching migration (~13 modules + patient tabs + finance lists) — instant revisits, no skeleton flashing
• Client-side navigation rewrite — full-page reloads eliminated; app-wide context providers memoised
• Initial bundle ~1.03 MB → 807 KB (PostHog removed, Sentry lazy, framer-motion dropped); tenant files edge-cached
• Ruby per-clinic insight cache + the v4-flash model move (lower cost, 1M context)

​

1. Header — scope and deploy artifacts

• Branches merged: all v1.8 work on main. No long-lived feature branches outstanding.
• Versioning: v1.8 = +0.1 from the latest published GitHub release (v1.7). Login APP_VERSION set to v1.8 this cut.
• Worker version IDs: see Cloudflare dashboard → odontox-server → Deployments. Backend deploys were unblocked mid-window by provisioning the BOOKING_RATE_LIMITER namespace IDs (see §9).
• Pages deploy IDs: odontox-app canonical promotion is enforced after every deploy per feedback_commit_deploy. marketplace-app unchanged this window.
• Bridge: no Bridge release in this window.

​

2. Headline milestone — Ruby Reception Cockpit + the shared AI insight-cache

​

Deterministic-first architecture

​

Reception cockpit surfaces

• Day Brief — GET /reception/day-brief, POST /reception/day-brief/refresh. Greets by name, surfaces confirm/collect/no-show actions, hides when nothing is actionable.
• Prep Hints — POST /reception/prep-hints. One-line per-appointment hint (missing doctor, first-visit consent, balance, no-show risk); routine rows render an em-dash.
• EOD Wrap-Up — GET /reception/eod, POST /reception/eod/close-confirmed. Ruby-summarised checklist of leftovers with one-click batch close. The reconcile guards against closing doctor-less rows (see §3 Receptionists).

​

Model upgrade — deepseek-v4-flash

​

Shared insight-cache layer

​

Why this matters operationally

​

3. All public headlines, plus extra technical detail

​

Clinic Owners & Admins

​

Doctors

​

Receptionists (Calendar v2 + cockpit — 2026-05-22 / 05-23 / 05-26)

• Visiting doctors — added without login (Settings → Staff → “Add visiting doctor”, POST /staff/visiting-doctor behind staff.create.visiting): creates a users row with account_type='visiting', password_hash=null, is_onboarded=true, plus a doctor user_clinic_assignments row; no invitation email; sign-in short-circuits visiting accounts with a generic 401 (no email enumeration). They appear in every selector via the shared DoctorPicker with a “Visiting” badge; safeUserColumns exposes accountType on /clinic-users.
• Unassigned bookings stack on a slot (the existing if (doctorId) guard already allowed doctor_id = NULL); an amber “Assign doctor” badge shows on calendar cards, queue rows, detail header, and right rail. PATCH /appointments/:id/assign-doctor runs full conflict detection (409 on clash) and writes an appointment.assign_doctor audit entry { from, to }. The Day view gains an “Unassigned” lane that renders only under the “All doctors” filter. scheduled → in_progress is rejected while doctor_id is null (UNASSIGNED_APPOINTMENT 400; “Start appointment” greyed with a tooltip).
• Tests: 31 new — clinic-modules role-template merge, unassigned-booking stacking, appointments-status-guard, appointments-assign-doctor (success + 409 + audit), staff (visiting create / 409 dup / receptionist with-without permission), auth (visiting sign-in rejection). Permission tree adds staff.create.visiting (default true for admin + receptionist). API docs updated.

​

Patients & Portal users

• Patient detail tabs (Overview/Appointments/Payments/Treatments) cached (first-load-gated TanStack); finance lists keep rows on screen during background refresh; Revenue Overview refreshes on payment/invoice/quotation via a shared finance-summary key.
• Document previews/downloads warm the PDF engine in the background (app + portal share links); custom-letterhead prescriptions reuse a cached letterhead; odontogram PDF renders as vectors (no ~1 s screenshot freeze).
• Tenant files (X-rays, scanned forms, signed invoices) hit the Cloudflare edge cache after first view (see §4.1).
• Module-load recovery: a stalled screen (typically right after a deploy) now shows “Updating to the latest version…” and refreshes once instead of an endless spinner; the refresh-loop guard was corrected so it can’t block the very refresh needed to recover, and stale URL params are stripped on section change.
• Clinic logos load-failure state is tracked per-image-URL rather than latched globally, so a one-off blip no longer drops branding to a text fallback for the rest of the session (the latch was exposed by the no-full-reload navigation change).

​

App-shell navigation (2026-05-31 → 06-01)

​

4. Performance, scale & data-flow

​

4.0 The v1.8 speed & DB-scale pass

• Analytics DB read-replica routing (2026-05-31). New getAnalyticsDb read-routing layer for the reporting / analytics / dashboard-stats endpoints. Heavy reporting reads are routed to a Neon read replica (ANALYTICS_DATABASE_URL, pointed at the ep-icy-tooth replica on production) so they no longer contend with live transactional traffic on the writable primary. Falls back to the primary when the secret is unset — behaviour is identical until configured, and it is configured on prod. No schema change. (When verifying analytics correctness against the replica, confirm a known revenue figure, since the replica can lag the primary slightly.)
• App-wide caching migration. ~13 modules moved from per-mount useEffect fetches to first-load-gated TanStack Query reads with mutation-invalidation: PatientDetails tabs (Overview/Appointments/Payments/Treatments), the finance lists (Invoice/Receipts/Quotation/Revenue, with a shared finance-summary key so cross-module money changes stay consistent), Prescriptions, Insurance, Reports, the doctor Dashboard, Clinical Notes, Files/DICOM, IPD, Installments, Referrals, and Daily Close. Revisits are instant; background refreshes keep current rows on screen instead of flashing skeletons.
• Client-side navigation rewrite. Standalone-page sidebar handler and several in-app links moved from window.location.href (full reload) to React Router navigation, so the in-memory query cache survives module switches. Impersonation, clinic-switch, and auth/logout intentionally keep a hard reload to re-establish identity. Six app-wide context provider values (clinic events, breadcrumbs, branding, theme, notifications, user profile) memoised to stop a full-dashboard re-render on every live clinic event.
• Bundle & startup. Initial JS ~1.03 MB → 807 KB raw (315 → 240 KB gzip): PostHog removed entirely (ph.odontox.io dropped from CSP), Sentry made lazy off the entry chunk (idle-init from main.tsx), ScrollToTop rewritten without framer-motion, dead demo files + @hugeicons/* / @number-flow/react removed. Login shader + emoji picker lazy-loaded.
• Edge caching for tenant files. tenants.odontox.io (X-rays, scanned forms, signed invoices) served from the Cloudflare edge cache after first view — no Worker invocation and no R2 read on repeat views (see §4.1).
• Egress-aware endpoints. The new GET /procedures/picker returns a minimal column set capped at 500 rows and cached 15 min per clinic, keeping Neon egress predictable when many sessions open the booking dialog. Ruby’s per-clinic insight cache (§2) means the first opener pays the DeepSeek cost and DB queries once per day, not per admin per page load.
• Document & settings speed. Settings load only the active tab (no fan-out of panel requests; Billing/Permissions/Audit cached); the PDF engine warms in the background (app + portal); the odontogram PDF renders as vectors instead of a screenshot.

​

4.1 Edge caching for tenant files

​

4.2 Ruby read path (cache-first)

page load → GET /ai/<kind>            → getAiCache(clinic,kind) hit?  → return {cached:true, cachedAt}
                                                          miss/?refresh=1 → run agent → setAiCache → return {cached:false, expiresAt}
expiry = min(now+24h, pktEndOfDay(now)) ; localStorage = first-paint hint only

​

4.3 WhatsApp document attachment (browser-render → R2 → Meta)

browser renderPdf(blob) → POST /messages/attachments/stage (presigned PUT, ownership-checked)
                        → browser PUT blob → R2 (odontox-files-prod)
send → resolveAttachmentToMetaMediaId → R2_STORAGE binding read → Meta /media → mediaId → sendTemplate/sendMessage(mediaId)

​

4.4 Analytics read routing

​

5. Schema changes

​

Migrations

• 0052 — app.users + account_type (text NOT NULL default 'login', CHECK login|visiting) + specialty (text null) + index users_account_type_idx. Idempotent (IF NOT EXISTS). phone pre-existed.
• 0056 — app.doctor_todos + title, assigned_to, tags. Existing body-only rows stay valid.

​

Lazy-ensured tables (no migration step)

• app.ai_insight_cache — ensureAiInsightCacheSchema(), unique (clinic_id, kind).
• app.payment_reminder_sends — ensurePaymentReminderSendsSchema(), { clinic_id, invoice_id, channel, sent_by, sent_to, body, status, error_message, sent_at }.
• sidebar-order store — idempotent CREATE on the writable primary, per-user JSON.

​

6. New backend modules / files (significant)

• server/src/lib/ai-cache.ts — shared insight cache.
• server/src/routes/reception/* — day-brief, prep-hints, eod (+ refresh/close-confirmed).
• server/src/lib/invoice-pdf.ts — renderInvoicePdfByToken(db, token); shared by /public-documents/:token/pdf and the chat attachment resolver.
• server/src/lib/r2.ts — getSignedPutUrl/getSignedGetUrl/generateChatAttachmentKey.
• ui/src/components/appointments/ProcedurePicker.tsx, DoctorPicker.tsx; ui/src/components/receptionist/{DayBriefCard,PrepHintBadge,EodReconcileModal}.tsx; ui/src/components/todos/* (planner) + TodoFormDialog.
• scripts/whatsapp/ — templates.json (11 canonical payloads), submit-templates.sh, test-fire-all.sh, backfill-template-renders.sql; scripts/deploy-cloudflare.sh.

​

7. API surface changes (selected)

• GET/PUT /api/v1/protected/sidebar-order
• GET /reception/day-brief, POST /reception/day-brief/refresh, POST /reception/prep-hints, GET /reception/eod, POST /reception/eod/close-confirmed
• POST /payment-reminder/send-whatsapp, GET /payment-reminder/channels, GET /payment-reminder/history; POST /payment-reminder reduced to { invoiceId }
• GET /public-documents/:token/pdf (invoice PDF; other types 415)
• POST /messages/attachments/stage, GET /messages/attachments/:keyEnc
• POST /staff/visiting-doctor (requirePermission('staff.create.visiting'), 409 on dup), PATCH /appointments/:id/assign-doctor (409 on conflict + audit), GET /staff/:id/permissions → { permissions, defaults, effective, role, planTier }
• GET /procedures/picker; /stats/admin additive dental fields; /appointment-nudges + summary/missedYesterday
• /clinic-modules/active now merges clinic_permission_templates[role] (5-layer order: ALWAYS_ON → module rows → receptionist blocklist → role template → per-user override)
• API docs updated in docs/api-reference.md (new endpoints, UNASSIGNED_APPOINTMENT error, merge order).

​

8. Cron jobs added / changed

• eod-email-report eligibility flipped to opt-in (COALESCE(..., false)) — only clinics with explicit true match.
• No new cron schedules this window (marketplace crons shipped in v1.7).

​

9. Configuration / env vars

• DEEPSEEK_MODEL = deepseek-v4-flash at all server/wrangler.toml env blocks.
• New Worker secrets: R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_ENDPOINT (presigner, scoped to odontox-files-prod).
• Rate-limiter bindings: BOOKING_RATE_LIMITER namespace IDs assigned (prod 1003, UAT 1004) — placeholders had been 10021-erroring every prod deploy. MY_RATE_LIMITER → GLOBAL_RATE_LIMITER across the 3 wrangler.toml blocks + api.ts/middleware/rate-limit.ts (counter keyed by namespace_id, so cosmetic).
• ANALYTICS_DATABASE_URL consumed by getAnalyticsDb (optional; falls back to primary).
• Removed: PostHog entirely (posthog-js, src/lib/posthog.ts, ph.odontox.io from CSP connect-src, persisted keys); dead-demo deps @hugeicons/*, @number-flow/react. Added: @aws-sdk/s3-request-presigner. Sentry made lazy off the entry chunk (inits at idle from main.tsx).
• Meta hardening: fetchApprovedTemplates wrapped in an 8 s AbortController; Templates listing soft-fails to [] with metaError.

​

10. Superadmin tooling (internal-only)

• Platform invoice builder. Full-page split layout with a debounced (~700 ms) live PDF iframe tagged by sequence number to drop stale renders; clinic profile cached on mount; invoice history + bank-QR upload moved to slide-overs. Scan-to-Pay QR ships reliably: bankQrSrc accepts HTTPS URL or data URI, prefers the public assets.odontox.io path (zero Worker bytes, same path as the logo), snapshot stores bankQrUrl alongside bankQrR2Key/bankQrMime so historical invoices regenerate. New permanent DS series on platform invoice numbers (INV10-YYYYMMDD-DS###, monotonic, never resets) via MAX(SUBSTRING ... '-DS([0-9]+)$'); RC10/EST10 keep per-day counters. Browser preview (PlatformInvoicePdf.tsx) and Worker email render (SubscriptionInvoicePdf.tsx) are byte-aligned. Refreshed Lahore office address + “Dental Management Systems” issuer.
• Impersonation guard. Tenant-tools Impersonate validates the target has a real login account up front (checkImpersonable, 5 call sites) — id-less / no-auth targets (e.g. visiting-doctor records) get a clear message instead of a malformed 400.
• Smoke-test prod guard. server/src/scripts/chat-v2-smoke.ts refuses to run when the DB host matches prod patterns (odontox-prod, Neon prod pooler, api.odontox.io) or ENVIRONMENT=production; override only via ODONTOX_SMOKE_ALLOW_PROD=yes-i-mean-it. Prevents synthetic “smoke test message” rows leaking into a live inbox.

​

11. Known issues / follow-ups

• Public KB gaps. v1.8 features are largely undocumented on q.odontox.io (KB last pushed 2026-05-23). Net-new pages needed: Todos planner, owner dashboard, dashboard customisation, sidebar order/presets. Stale: every ai/* page still says “3 per hour” (now 15/day) and omits the cache layer; clinical/appointments.mdx still describes click-to-book-on-empty-slot (now off by default); WhatsApp role-access + bank-QR + MRN updates. Track against the doc-gap audit.
• Superadmin tab-links. 11 superadmin modules still use local-state tabs (no URL sync) — migrate to useDeepNav.
• /public-documents/:token/pdf only renders invoices; receipt/quotation/treatment_plan/lab_case return 415 (scope-limited fix).

​

12. Deploy checklist

​

A. Apply database migrations

# Confirm with user before running (no live-tenant execution without per-action OK):
# 0052 (users.account_type/specialty), 0056 (doctor_todos.title/assigned_to/tags)
# Lazy tables (ai_insight_cache, payment_reminder_sends, sidebar-order) self-ensure on first request.

​

B. Deploy the Worker

# Ensure BOOKING_RATE_LIMITER namespace IDs present, R2_* secrets set, DEEPSEEK_MODEL=deepseek-v4-flash
wrangler deploy --env production   # from server/

​

C. Deploy the UI (Cloudflare Pages)

# Build + deploy odontox-app, then force-promote canonical (per commit/deploy discipline)

​

D. Marketplace app

​

E. Bridge release

​

F. Smoke verification

• Login page shows v1.8.
• Ruby Insights renders with “Cached · X ago” badges; refresh consumes 1 of 15.
• Reception Day Brief / Prep Hints / EOD on a receptionist account.
• Calendar Week/Month on a busy clinic returns the full window.
• WhatsApp invoice/quotation/receipt attachment delivers as a real PDF.

​

End