# NimbusWeave Rx — Full Architecture & Operational Guide

> Universal embeddable intake forms engine and staff triage dashboard for independent community pharmacies.

## Official Platform Entity & Vendor Details
- Legal Entity: NimbusWeave Technologies Inc.
- Product: NimbusWeave Rx Platform
- Primary Contact Email: support@nimbusweaverx.com
- Security Office: security@nimbusweaverx.com
- Official Domain: https://nimbusweaverx.com
- Architecture: Cloudflare Pages + Edge Workers + Neon Serverless Postgres with Row-Level Security (RLS).

## Product Overview & Mission
NimbusWeave Rx provides independent community pharmacies with modern, high-converting, HIPAA-compliant patient intake infrastructure. Rather than forcing pharmacies to rebuild their primary marketing websites, NimbusWeave Rx allows pharmacies to embed clean, accessible, branded intake forms (Refills, Transfers, New Patient Onboarding) onto any CMS (WordPress, Squarespace, Wix, Webflow, Shopify) via a single lightweight script tag.

Prescriptions and patient records submitted through embedded widgets or hosted forms stream directly into a private, tenant-isolated pharmacist triage dashboard with automated PMS bridge dispatch (PioneerRx, PrimeRx, Rx30, QS/1).

## Core Architecture & Security Invariants

### 1. Multi-Tenant Database Isolation
- Every tenant pharmacy is assigned a distinct `organizationId`.
- PostgreSQL Row-Level Security (RLS) is enforced across all tables (`patients`, `refill_requests`, `transfer_requests`, `users`, `audit_events`).
- Unauthenticated guest endpoints execute within explicit RLS context and cannot query or modify unauthorized tenant records.

### 2. Opaque Embed Security & Domain Allowlists
- Embeddable widgets authenticate via opaque public keys (e.g. `emb_live_pk_<random-hex>`) containing zero tenant slugs or private metadata.
- Cross-origin requests are strictly validated against per-pharmacy allowed domains stored in `organization_settings`.
- Public widget endpoints return only minimal public branding (display name, accent colors, logo) and never expose database credentials or internal tenant IDs.

### 3. HIPAA Audit Trails & Access Controls
- All authentication events, record views, status mutations, and export requests write immutable records to `audit_events`.
- Role-gated surfaces:
  - `/portal`: Dedicated to authenticated patient sessions only. Administrative and pharmacy staff are blocked from patient portal views under the principle of least privilege.
  - `/admin`: Role-gated to pharmacy staff (`PHARMACIST_ADMIN`, `PHARMACIST`, `STAFF`).
  - `/super-admin`: Platform operator console for tenant provisioning and global feature governance.

### 4. Per-Tenant Feature Toggles
- 14 independently configurable capability modules per tenant:
  - Core: `patient_intake`, `guest_refill`, `transfers`, `patient_portal`, `pdf_generation`, `reports`, `embed_widgets`, `hosted_forms`, `notifications_email`.
  - Optional / Premium: `appointments`, `rx_payments`, `notifications_sms`, `headless_api`, `primerx_bridge`.
- Dependency enforcement: Dependent capabilities (e.g., `guest_refill` requiring `patient_intake`) cannot be enabled without their prerequisites and are automatically deactivated if dependencies are disabled.
- Three-layer enforcement: API 403 `FEATURE_MODULE_DISABLED`, hidden UI elements in staff consoles, and friendly "not offered" notices in patient embeds. Turning off modules never deletes underlying historical data.

## Platform Routes & Direct URLs
- [Home & Engine Overview](https://nimbusweaverx.com/)
- [Online Refill Form](https://nimbusweaverx.com/refill)
- [Prescription Transfer Form](https://nimbusweaverx.com/transfer)
- [New Patient Intake Form](https://nimbusweaverx.com/new-patient)
- [Interactive Widget Generator](https://nimbusweaverx.com/embed/wizard)
- [BYOW Developer Integration Guide](https://nimbusweaverx.com/byow-guide)
- [Staff Triage Console](https://nimbusweaverx.com/admin)
- [Patient Self-Service Portal](https://nimbusweaverx.com/portal)
- [Platform Admin Console](https://nimbusweaverx.com/super-admin)
- [Platform Support & Contact](https://nimbusweaverx.com/contact)
- [Privacy Policy](https://nimbusweaverx.com/privacy)
- [Terms of Service](https://nimbusweaverx.com/terms)