1. System Architecture & Practice Operations
Enterprise OpenClinic AI Architecture, Data Flow, and Technology Foundations.
OpenClinic AI is an enterprise, cloud-native practice management suite designed for multi-provider dental practices, oral surgery clinics, and DSO networks. It bridges modern Web UI interfaces, high-performance REST APIs, MariaDB relational persistence, and integrated AI clinical intelligence.
- Frontend: Modern vanilla JavaScript, reactive CSS design system, responsive operatory viewports.
- Backend Gateway: FastAPI (Python 3.10) with asynchronous ASGI worker threads, Pydantic DTO validation, and Starlette routing.
- Database Persistence: MariaDB Relational Database with real-time transactional integrity across appointments, ledgers, and clinical records.
- Email Dispatch Engine: Brevo HTTPS API with automated STARTTLS Port 587 / 465 fallback for clinical reports, OTP verification, and patient statements.
| Role | Permissions & Access Scope | Primary Modules Available |
|---|---|---|
| Administrator (Admin) | Unrestricted access across all operational, clinical, billing, and system preferences. | Patients, Appointments, Treatment Plans, Ledger, Perio/Chart, Setup, Test Suite. |
| Dentist / Provider | Full clinical access to patient charts, prescriptions, treatment plans, and notes. | Appointments, Tooth Chart, Treatment Plans, Medical History, Clinical Reports. |
| Hygienist / Assistant | Clinical charting, perio charting, medical safety register updates, and vitals. | Appointments, Medical History, Perio Chart, Documents. |
| Billing Specialist | Ledger entries, insurance claims, adjustments, payments, and financial statements. | Account Ledger, Insurance, Claims, Statements & Billing Email Dispatch. |
| Patient (Portal User) | Restricted self-service view to personal profile, upcoming appointments, and statements. | Personal Portal Hub, Treatment Plan Review, Statement Viewer, Appointment Request. |
2. Authentication, User Switcher & Password Security
Free-text credential login, Role-Based Access Control, and automated 6-Digit Email OTP password recovery.
2.1 Free-Text Credentials Login
The system enforces strict zero-leakage login interfaces. Free-text inputs allow staff and patients to sign in securely without exposing registered user lists in dropdowns.
Sign In / Lock in the top navigation bar or access /app/ directly.Admin) or your patient portal email (e.g., akshi.mishra.bui@gmail.com).2.2 Self-Service Password Reset via Email OTP
In case of a forgotten password, users can request a secure 6-digit one-time passcode delivered via transactional email:
POST /api/auth/request-otp
{"identifier": "user@example.com"}
// Step 2: Confirm OTP & Change Password
POST /api/auth/reset-password-otp
{"identifier": "user@example.com", "otp": "492817", "new_password": "NewSecurePassword@2026"}
3. Patient Directory & Registration Management
Search, filtering, full international address formats, phone formats, and instant patient switching.
The Patient Directory provides instant sub-second lookup across tens of thousands of records, indexing patient names, charts, phone numbers, and dates of birth.
3.1 International Address & Phone Number Compliance
OpenClinic AI natively accommodates international postal codes, provinces, states, and E.164 phone formats:
| Field | Supported International Format | Validation Rule |
|---|---|---|
| Postal / ZIP Code | US (90210), UK (SW1A 1AA), Canada (M5V 2T6), India (110001) |
Alphanumeric with optional spaces and hyphens (3-10 chars). |
| State / Province | US States, Canadian Provinces (ON, BC), Indian States (Delhi, MH) | Full name or 2-3 letter international standard ISO codes. |
| Telephone | +1-555-0199, +44 20 7946 0991, +91 98765 43210 |
E.164 compliant with international country dialing prefixes. |
4. Clinical Documentation & 1-Click Email Dispatch
Exporting comprehensive clinical records and delivering formatted statements via Brevo email.
Staff can generate, print, and instantly dispatch complete Clinical Care Summaries directly to the patient's registered email address with a single click:
📧 Send Statement via Email automatically dispatches the latest balance ledger, insurance adjustments, and payment history to the patient.
5. Medical History & Safety Register
Active allergy monitoring, drug interaction alerts, chronic medical conditions, and emergency contacts.
Patient safety is paramount. When an allergy or chronic condition is added to a patient's chart, high-visibility visual badges appear in the top patient header across all operational screens.
6. Appointments & Operatory Scheduling Grid
Multi-operatory visual scheduling, drag-and-drop bookings, appointment status transitions, and conflict detection.
The appointment module provides multi-column operatory grid views with color-coded status states:
- Scheduled (Blue): Confirmed appointment ready for patient check-in.
- In-Chair (Orange): Patient seated in operatory; doctor actively performing care.
- Complete (Green): Procedure completed; ledger automatically updated with billing entries.
- Broken / Cancelled (Red): Missed visit recorded for audit and recall tracking.
7. 3D Interactive Tooth Chart & Treatment Plans
Universal dental numbering, surface restoration charting, CDT procedure logging, and multi-phase treatment planning.
The interactive tooth chart supports the standard Universal Numbering System (Teeth 1 through 32 for permanent dentition, Letters A through T for primary dentition). Clinicians can click individual tooth surfaces (Mesial, Distal, Occlusal, Facial, Lingual) to log restorations, crowns, root canals, and extractions.
8. Invoice, Billing Ledger & Insurance Operations
Itemized ledger transactions, patient copays, primary/secondary insurance claims, write-offs, and statement generation.
The billing ledger offers a complete double-entry financial ledger:
- Charges: Automatically posted upon procedure completion using ADA CDT code fee schedules.
- Payments: Credit card, cash, check, or online patient portal payments.
- Insurance Adjustments: Contractual write-offs and deductible tracking.
- Statements: Generate itemized PDF billing statements or dispatch via 1-click email.
9. Dedicated Patient Self-Service Portal
Secure patient hub for viewing appointments, checking balances, reviewing clinical treatment plans, and updating demographics.
When a patient logs into /app/ using their registered email and portal password, the system automatically engages Patient Portal Mode. Practice administrative controls and other patients' records are strictly sequestered.
10. System Setup & Administration
Practice preferences, staff account management, operatory configuration, and clinical fee schedule maintenance.
Accessible only by users with role Admin via the ⚙️ Setup tab. Administrators can manage practice hours, configure email SMTP credentials (Brevo), customize appointment colors, and maintain provider operatory schedules.
11. Automated Testing & Live Quality Suite
Accessing the executive board audit dashboard, running live viewport playback, and launching headed desktop reproduction.
OpenClinic AI features an automated test suite comprising 33 end-to-end verified test scenarios across all 10 clinical modules.
11.1 Accessing the Quality Dashboard
The test dashboard is deployed and accessible at:
11.2 Reproducing Scenarios Live in Desktop Chromium
To watch any test scenario execute live on your computer with human-observable pacing (slow motion 900ms):
python run_live_scenario_playwright.py --test TC-AUTH-001 --slowmo 900
# Or double click on Windows:
run_live_test.bat TC-AUTH-001
12. Frequently Asked Questions & Troubleshooting
Instant answers to common operational questions and technical resolution steps.
Setup > User Accounts.
/test/live_test_runner.html), use the ⏱️ PACING dropdown selector to toggle between:
- 🐢 Slow-Mo (1.5s / step): Best for demonstrations and detailed inspection.
- ⏱️ Realistic Live (850ms / step): Natural human-paced execution.
- ⚡ Fast (400ms / step): Rapid step validation.
- 🚀 Instant (50ms): Immediate throughput execution.
🖥️ Desktop Chrome: Spawns a physical, visible Chromium browser window on your local PC via Playwright, controlling the real mouse and keyboard with slow-motion delay.