Read-Only Mode

When subscription payment lapses or a platform administrator locks an account, EaseLab enters read-only mode. Staff can view historical data but cannot create, edit, or delete records through most API routes.

Triggers

flowchart TD
    A{Tenant state}
    A -->|Trial expired| B[Lock + read-only]
    A -->|Subscription expired| B
    A -->|Payment overdue/unpaid| B
    A -->|Admin manual lock| B
    A -->|Current + unlocked| C[Full access]

Trigger	Typical lock reason message
Trial ended	"Your free trial has ended..."
Subscription expired	"Your subscription period has ended..."
Platform lock	Custom LockReason from admin portal
Payment status Overdue/Unpaid	Billing enforcement

TenantLockMiddleware evaluates rules on each request and may auto-lock without restart.

What still works

Capability	Available?
Login / auth	Yes
View patients, invoices, results	Yes
Export / print existing reports	Yes
Billing & checkout routes	Yes
/tenant info endpoints	Yes
Public patient portal	Yes
Platform admin impersonation	Platform only

What is blocked

HTTP mutations (POST, PUT, PATCH, DELETE) on non-exempt paths return:

{
  "message": "Your lab is in read-only mode. Subscribe to restore full access.",
  "code": "TENANT_READONLY",
  "readonlyMode": true
}

Blocked examples
New invoice or patient
Sample collection
Result entry and verification
Catalog edits
SMS send (non-billing)
Manual backup trigger
Analyzer ingest (TENANT_LOCKED)

Exempt path prefixes include /auth, /billing, /tenant, /public, /webhooks, /admin (platform), /integrations (partial).

Exempt billing

Checkout remains available so locked labs can self-recover without support tickets.

User interface

Element	Behavior
Read-only banner	Top of app with lock reason
Subscribe CTA	Links to /billing/plans
Activate free plan	When free tier available
Disabled buttons	Save actions greyed with tooltip
Dashboard notice	Explains limitations

Frontend uses useReadonlyMode() hook reading tenant.isLocked and lockReason.

Recovery steps

flowchart LR
    A[Read-only detected] --> B[Owner opens billing]
    B --> C[Subscribe or renew]
    C --> D[Payment confirmed]
    D --> E[IsLocked cleared]
    E --> F[Refresh browser]

1. Lab owner logs in.
2. Navigate to Billing → Plans.
3. Complete checkout or activate free plan.
4. Wait for webhook processing (usually seconds).
5. Hard refresh if banner persists.

Platform admins can unlock manually from Tenant Management after offline payment.

Impact on integrations

Integration	Read-only effect
Analyzer POST	403 Forbidden
Public report lookup	Still works
SMS quick send	Blocked
API integrations	Mutations fail

Schedule maintenance windows after renewal — backlog of samples may accumulate during lock.

Data safety

Read-only mode does not delete data. All records remain queryable. Backups may still run on schedule depending on policy — verify with platform settings.

Extended lockout

Long read-only periods stall lab operations but preserve records. Communicate with staff to avoid parallel paper workflows that won't sync.

Platform vs automatic lock

Source	Resolution
Automatic billing	Self-serve checkout
Manual platform lock	Contact EaseLab support / account manager
Provisioning failure	Separate from read-only — see tenant status

Monitoring

Administrators should watch:

• TrialEndsAt approaching
• Email renewal reminders from gateway
• PaymentStatus in admin subscription page

Related documentation

• Billing Overview
• Plans & Checkout
• Usage & Limits
• Troubleshooting: Billing