> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adhdsimple.co.uk/llms.txt
> Use this file to discover all available pages before exploring further.

# ADHD Clinical Architecture Overview

> Real system architecture for ADHD Simple Clinical platform

## Overview

The ADHD Simple Clinical platform is a React web application with a Supabase backend, deployed on Netlify. It manages ADHD patient records, prescriptions, and medication delivery using a **service layer architecture** that centralizes business logic and provides consistent error handling.

## High-Level Architecture

```mermaid theme={null}
graph TB
    Users[Clinicians & Staff] --> Web[React Web App]
    Web --> Netlify[Netlify Hosting]
    Web --> Services[Service Layer]
    Services --> Edge[Edge Functions]
    Edge --> Supabase[Supabase Backend]
    Supabase --> PG[(PostgreSQL Database)]
    Supabase --> Auth[Supabase Auth + 2FA]
    Edge --> DHL[DHL API Integration]
    
    subgraph "Service Layer"
        CoreServices[Core Services]
        FeatureServices[Feature Services]
        SharedUtils[Shared Utilities]
    end
    
    Services --> CoreServices
    Services --> FeatureServices
    Services --> SharedUtils
    
    subgraph "Clinical Data"
        Patients[Patient Records]
        Meds[Medication Management]
        Health[Health Metrics]
        Compliance[Controlled Drug Compliance]
    end
    
    PG --> Patients
    PG --> Meds
    PG --> Health
    PG --> Compliance
```

## Technology Stack

### Frontend

* **React 18** with TypeScript
* **Vite** for build tooling
* **Material-UI (MUI)** for components
* **Tailwind CSS** for styling
* **React Router** for navigation
* **Service Layer Architecture** - No direct Supabase calls

### Backend

* **Supabase** as backend-as-a-service
* **PostgreSQL** database
* **Supabase Auth** with mandatory 2FA
* **Edge Functions** for business logic
* **Supabase Storage** for medication images

### Deployment

* **Netlify** hosting with automatic deployments
* **GitHub Actions** for CI/CD
* Custom domain with SSL

## Service Layer Architecture

The platform uses a **service layer architecture** that eliminates direct Supabase calls from the frontend, providing:

### Core Services (4)

* **PatientService** - Patient CRUD operations, health metrics, monitoring
* **PrescriptionService** - Prescription orders, item management, charge calculations
* **MedicationService** - Medication library, active medication tracking, stock management
* **AuthService** - User authentication, session management, MFA support

### Feature Services (7)

* **ShipmentService** - Shipment creation, tracking, label generation, DHL integration
* **PaymentService** - Payment settings, Stripe integration, authorization processing
* **PatientRequestService** - Patient app request management, review workflows
* **AddressService** - UK postcode lookup, address validation, pickup addresses
* **ClinicService** - Clinic settings and configuration management
* **DeliveryService** - Delivery fee calculation, shipping cost management
* **PharmacyService** - Order management, pharmacy statistics, controlled drugs register

### Benefits

* **Centralized business logic** - All operations go through services
* **Consistent error handling** - Using shared `handle()` utility
* **Type safety** - Full TypeScript support with Zod validation
* **Zero direct Supabase calls** - Complete separation of concerns
* **Testable architecture** - Services can be mocked and tested independently

## Key Features

### Authentication & Security

* Mandatory TOTP 2FA for all users
* Role-based access control (admin, prescriber, staff)
* Session management with automatic timeouts

### Patient Management

* Comprehensive ADHD patient records
* Health metrics tracking (weight, BP, pulse, symptoms)
* Clinical pathways: new → titration → stable care

### Prescription Management

* Digital prescription creation and editing
* Controlled drug compliance monitoring
* 28-day prescription cycles
* DHL integration for medication delivery

### Clinical Data

* Real-time data synchronization
* Audit trails for all clinical actions
* NHS/GDPR compliant data handling

## Database Structure

Key tables include:

* **`users`** - Clinician accounts and profiles
* **`patients`** - Patient records and clinical data
* **`prescriptions`** - Prescription records and orders
* **`health_metrics`** - Patient monitoring data
* **`shipments`** - DHL delivery tracking
* **`audit_logs`** - Complete audit trail

## Edge Functions

The system uses consolidated Supabase Edge Functions corresponding to each service:

### Core Operations

* **`auth-operations`** - User authentication, session management, MFA
* **`patient-operations`** - Patient CRUD, health metrics, monitoring
* **`clinical-prescription-operations`** - Prescription management, order processing
* **`clinical-medication-operations`** - Medication library, active medication tracking

### Feature Operations

* **`clinical-shipment-operations`** - Shipment creation, tracking, DHL integration
* **`clinical-payment-operations`** - Payment processing, Stripe integration
* **`clinical-request-operations`** - Patient app request management
* **`clinical-address-operations`** - Address validation, postcode lookup
* **`clinical-clinic-operations`** - Clinic settings management
* **`clinical-delivery-operations`** - Delivery fee calculation and configuration
* **`clinical-pharmacy-operations`** - Pharmacy order management and statistics

### Specialized Functions

* **`generate-medication-image`** - Medication image generation
* **`prescription-notifications`** - Email and push notifications
* **`send-email`** - Email service integration
* **`send-push-notification`** - Push notification service

## External Integrations

### DHL API

* Automated shipment creation with tracking numbers
* Van pickup scheduling
* Real-time delivery tracking
* Patient delivery confirmations

### Compliance

* Controlled drug monitoring
* NHS Digital standards compliance
* GDPR data protection measures

## Development

### Local Setup

* Supabase local development with Docker
* Hot reload with Vite HMR
* TypeScript for type safety

### Service Layer Development

* Services can be mocked for testing
* Consistent error handling patterns
* Zod validation for all inputs
* Type-safe service interfaces

### Testing

* Playwright for end-to-end testing
* Component testing with Jest
* Service layer unit testing
* Clinical workflow testing

### Deployment

* Automatic Netlify deployments from main branch
* Environment-based configuration
* Database migrations via Supabase CLI
* Edge function deployments

<Note>
  This architecture prioritizes clinical safety, regulatory compliance, and operational efficiency for ADHD care delivery through a robust service layer that eliminates direct database access from the frontend.
</Note>