Upload 31 files

Dockerfile

@@ -0,0 +1,22 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PIP_NO_CACHE_DIR=1 \
+    PORT=7860
+
+# HuggingFace Spaces requires writeable HOME; create a non-root user.
+RUN useradd -m -u 1000 user
+WORKDIR /app
+
+# Install dependencies first for better Docker layer caching.
+COPY --chown=user:user requirements.txt /app/requirements.txt
+RUN pip install --upgrade pip && pip install -r /app/requirements.txt
+
+# Copy the rest of the application.
+COPY --chown=user:user . /app
+
+USER user
+EXPOSE 7860
+
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,12 +1,64 @@
 ---
-title: Scheduler
-emoji: 😻
-colorFrom: yellow
-colorTo: green
+title: SOS Care Now Scheduling
+emoji: 🩺
+colorFrom: blue
+colorTo: indigo
 sdk: docker
+app_port: 7860
 pinned: false
-license: mit
-short_description: Medical Scheduler for SOS Care Now Chicago
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# SOS Care Now — Medical Scheduling Agent (HTML Edition)
+
+A modern, FastAPI + HTML/JS rewrite of the Streamlit scheduling dashboard. Designed for
+deployment on HuggingFace Spaces via Docker.
+
+## Architecture
+
+- **Backend:** FastAPI (Python) — reuses the existing `core/`, `agent/`, and `utils/` modules.
+- **Frontend:** Single-page HTML app with Tailwind CSS, Alpine.js, and FullCalendar.js.
+- **Data:** Google Sheets (via `gspread`), Google Calendar, Google Maps, Gmail.
+- **Scheduling logic:** LangGraph agent (unchanged from the Streamlit version).
+
+## Local development
+
+```bash
+pip install -r requirements.txt
+# Set required env vars (see below), then:
+uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+```
+
+Open <http://localhost:7860>.
+
+## HuggingFace Spaces deployment
+
+Push this folder as the root of a Docker-mode Space. The `Dockerfile` handles the rest.
+The Space needs the secrets listed below. Port `7860` is reserved by HF.
+
+## Required environment variables (Secrets in HF)
+
+| Variable | Description |
+|----------|-------------|
+| `OPENAI_API_KEY`              | OpenAI API key for GPT |
+| `GOOGLE_CALENDAR_CREDENTIALS` | Base64-encoded service-account JSON |
+| `GOOGLE_MAPS_API_KEY`         | Maps Distance Matrix + Geocoding |
+| `GMAIL_ADDRESS`               | From-address for notifications |
+| `GMAIL_CLIENT_ID`             | OAuth client ID (gmail.send scope) |
+| `GMAIL_CLIENT_SECRET`         | OAuth client secret |
+| `GMAIL_REFRESH_TOKEN`         | OAuth refresh token |
+| `ADMIN_USERNAME`              | Admin login username |
+| `ADMIN_PASSWORD`              | Admin login password |
+| `SHARED_CALENDAR_ID`          | Shared Google Calendar ID |
+| `GOOGLE_SHEET_ID`             | Spreadsheet ID backing all CRUD operations |
+
+## What's new vs. the Streamlit version
+
+- Modern multi-view single-page UI (sidebar navigation, modals, toasts).
+- **On-call toggle** — clickable switch on each on-call date for both admin and provider views.
+- FullCalendar with provider color coding and event detail modals.
+- Mobile-friendly responsive layout.
+- Session-cookie auth instead of Streamlit `session_state`.
+
+All existing features from the Streamlit dashboard are preserved: provider CRUD,
+patient CRUD, days off / standing days, on-call (24-hour window 07:00→07:00),
+LangGraph scheduling agent, audit log, provider portal.

agent/__init__.py

@@ -0,0 +1 @@
+"""agent package."""

agent/graph.py

@@ -0,0 +1,83 @@
+"""
+LangGraph Graph Definition — compiles the scheduling workflow into an executable graph.
+"""
+from langgraph.graph import StateGraph, END
+from langgraph.checkpoint.memory import MemorySaver
+from agent.state import SchedulingState
+from agent.nodes import (
+    validate_inputs,
+    check_availability,
+    calculate_travel,
+    rank_and_present,
+    book_appointment,
+    send_notifications,
+    no_match,
+)
+
+
+def should_continue_after_availability(state: SchedulingState) -> str:
+    """Routing function after availability check.
+
+    Returns 'calculate_travel' if providers are available, 'no_match' otherwise.
+    """
+    if state.get("available_providers"):
+        return "calculate_travel"
+    return "no_match"
+
+
+def build_scheduling_graph():
+    """Build and compile the scheduling LangGraph.
+
+    Graph flow:
+        validate_inputs → check_availability → [conditional]
+            → calculate_travel → rank_and_present → (INTERRUPT for user selection)
+            → book_appointment → send_notifications → END
+        or:
+            → no_match → END
+
+    The graph uses interrupt_before=["book_appointment"] to pause for human-in-the-loop
+    confirmation. The Streamlit UI should:
+        1. Run the graph until it hits the interrupt
+        2. Display ranked_matches to the user
+        3. Get user selection
+        4. Update state with user_selection
+        5. Resume the graph
+
+    Returns:
+        Compiled LangGraph
+    """
+    workflow = StateGraph(SchedulingState)
+
+    # Add nodes
+    workflow.add_node("validate_inputs", validate_inputs)
+    workflow.add_node("check_availability", check_availability)
+    workflow.add_node("calculate_travel", calculate_travel)
+    workflow.add_node("rank_and_present", rank_and_present)
+    workflow.add_node("book_appointment", book_appointment)
+    workflow.add_node("send_notifications", send_notifications)
+    workflow.add_node("no_match", no_match)
+
+    # Set entry point
+    workflow.set_entry_point("validate_inputs")
+
+    # Add edges
+    workflow.add_edge("validate_inputs", "check_availability")
+    workflow.add_conditional_edges(
+        "check_availability",
+        should_continue_after_availability,
+        {
+            "calculate_travel": "calculate_travel",
+            "no_match": "no_match",
+        }
+    )
+    workflow.add_edge("calculate_travel", "rank_and_present")
+    workflow.add_edge("rank_and_present", "book_appointment")
+    workflow.add_edge("book_appointment", "send_notifications")
+    workflow.add_edge("send_notifications", END)
+    workflow.add_edge("no_match", END)
+
+    # Compile with interrupt for human-in-the-loop
+    # The graph pauses before book_appointment so the UI can show options and get user selection
+    graph = workflow.compile(checkpointer=MemorySaver(), interrupt_before=["book_appointment"])
+
+    return graph

agent/nodes.py

@@ -0,0 +1,392 @@
+"""
+LangGraph Node Functions — each function represents one step in the scheduling graph.
+
+Each node takes the current SchedulingState and returns a partial state update (dict).
+"""
+from agent.state import SchedulingState
+from core import data_manager, scheduling_engine, google_services
+from core import settings_manager as settings
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+
+
+# Lazy-initialize the LLM to avoid import-time failures if the API key isn't set yet.
+_llm = None
+
+def _get_llm():
+    global _llm
+    if _llm is None:
+        from langchain_openai import ChatOpenAI
+        _llm = ChatOpenAI(model=settings.get_openai_model())
+    return _llm
+
+
+def validate_inputs(state: SchedulingState) -> dict:
+    """Validate all inputs from the dashboard before proceeding.
+
+    Checks:
+        - Patient exists
+        - Visit level is valid
+        - Address is not empty
+        - Preferred dates are at least 24 hours in the future
+        - Time window is valid (start < end, within reason)
+
+    Returns:
+        {"error": "message"} if validation fails, otherwise empty dict {}
+    """
+    # Patient must exist
+    patient = data_manager.get_patient_by_id(state["patient_id"])
+    if not patient:
+        return {"error": f"Patient '{state['patient_id']}' not found."}
+
+    # Visit level must be in the configured set
+    if state["visit_level"] not in settings.get_visit_levels():
+        return {"error": f"Invalid visit level: {state['visit_level']}"}
+
+    # Visit address must not be blank
+    if not state.get("visit_address", "").strip():
+        return {"error": "Visit address is required."}
+
+    # At least one preferred date must be provided
+    if not state.get("preferred_dates"):
+        return {"error": "At least one preferred date is required."}
+
+    # Every preferred date must be at least the configured lead time from now.
+    # Lead time always applies, even for on-call providers.
+    # Compare in the configured timezone so a UTC server doesn't mis-evaluate local times.
+    lead_hours = settings.get_min_lead_time_hours()
+    now_local = datetime.now(ZoneInfo(settings.get_timezone())).replace(tzinfo=None)
+    min_allowed_dt = now_local + timedelta(hours=lead_hours)
+    window_start = state.get("preferred_time_window", {}).get("start", "08:00")
+    for date_str in state["preferred_dates"]:
+        try:
+            proposed_dt = datetime.strptime(f"{date_str} {window_start}", "%Y-%m-%d %H:%M")
+        except ValueError:
+            return {"error": f"Invalid date format: '{date_str}'. Expected YYYY-MM-DD."}
+        if proposed_dt < min_allowed_dt:
+            return {"error": f"Date {date_str} at {window_start} does not meet the {lead_hours}-hour lead time requirement."}
+
+    # Time window must have start before end
+    window = state.get("preferred_time_window", {})
+    w_start = window.get("start", "")
+    w_end = window.get("end", "")
+    if w_start and w_end:
+        if scheduling_engine.parse_time(w_start) >= scheduling_engine.parse_time(w_end):
+            return {"error": "Time window start must be before end."}
+
+    return {}
+
+
+def check_availability(state: SchedulingState) -> dict:
+    """Check which providers are available for the requested visit.
+
+    For each preferred date/time combo:
+        1. Get all active providers
+        2. Get each provider's existing appointments for that date
+        3. Run scheduling_engine.is_provider_available for each
+
+    Returns:
+        {"available_providers": [...]} — list of provider dicts with an added 'available_slots' field
+        If none available: {"available_providers": [], "error": "No providers available..."}
+    """
+    # Skip if a previous node already set an error
+    if state.get("error"):
+        return {"available_providers": []}
+
+    all_providers = data_manager.get_all_providers(active_only=True)
+    visit_level = state["visit_level"]
+    visit_duration = scheduling_engine.get_visit_duration(visit_level)
+    window_start = state["preferred_time_window"]["start"]
+    window_end = state["preferred_time_window"]["end"]
+
+    available = []
+    for date in state["preferred_dates"]:
+        # Build a per-provider appointment index for this date (one read per provider)
+        appointments_by_provider = {
+            p["id"]: data_manager.get_appointments_for_provider(p["id"], date)
+            for p in all_providers
+        }
+
+        for provider in all_providers:
+            existing = appointments_by_provider[provider["id"]]
+            # Iterate through the time window in 30-minute increments
+            current_time = window_start
+            while scheduling_engine.parse_time(current_time) < scheduling_engine.parse_time(window_end):
+                if scheduling_engine.is_provider_available(
+                    provider, date, current_time, visit_level, existing
+                ):
+                    end_time = scheduling_engine.add_minutes(current_time, visit_duration)
+                    enriched = dict(provider)
+                    enriched["available_date"] = date
+                    enriched["available_start_time"] = current_time
+                    enriched["available_end_time"] = end_time
+                    enriched["is_oncall"] = scheduling_engine.is_oncall_for_slot(
+                        provider, date, current_time, end_time
+                    )
+                    available.append(enriched)
+                current_time = scheduling_engine.add_minutes(current_time, 30)
+
+    if not available:
+        return {
+            "available_providers": [],
+            "error": (
+                "No providers are available for the requested dates and time. "
+                "Try different dates or a different time window."
+            ),
+        }
+
+    return {"available_providers": available}
+
+
+def calculate_travel(state: SchedulingState) -> dict:
+    """Calculate travel times for all available providers to the patient's address.
+
+    For each available provider:
+        1. Determine their "origin" — the address of their previous appointment that day,
+           or their home address if it's their first visit
+        2. Call google_services.calculate_travel_time(origin, visit_address)
+        3. Also check if provider has other visits nearby (for area-affinity boost)
+
+    Returns:
+        {"travel_times": [...]} — provider dicts enriched with 'travel_time_minutes' and 'has_nearby_visits'
+    """
+    visit_address = state["visit_address"]
+    enriched_providers = []
+
+    for provider in state["available_providers"]:
+        available_date = provider["available_date"]
+        available_start = provider["available_start_time"]
+        arrival_by = datetime.strptime(f"{available_date} {available_start}", "%Y-%m-%d %H:%M")
+
+        # Fetch existing appointments for this provider on the proposed date
+        existing = data_manager.get_appointments_for_provider(provider["id"], available_date)
+
+        # Origin = home address, or the last appointment address that ends before proposed start
+        origin = provider["address"]
+        for appt in sorted(existing, key=lambda a: a["end_time"]):
+            if appt["end_time"] <= available_start:
+                origin = appt["visit_address"]
+
+        # Travel time from origin to patient visit address (traffic-aware two-pass)
+        travel_result = google_services.calculate_travel_time(origin, visit_address, arrival_by)
+        travel_time = travel_result["travel_minutes"]
+        if travel_time < 0:
+            travel_time = 0  # Graceful fallback if the Maps API fails
+        recommended_departure = travel_result["recommended_departure"]
+
+        # Area affinity: does the provider have any visits close to the patient that day?
+        has_nearby = False
+        if existing:
+            appt_addresses = [a["visit_address"] for a in existing]
+            nearby_results = google_services.calculate_travel_times_batch(
+                visit_address, appt_addresses, arrival_by
+            )
+            # "Nearby" = within 15 minutes of the proposed visit address
+            has_nearby = any(r["travel_minutes"] >= 0 and r["travel_minutes"] <= 15 for r in nearby_results)
+
+        enriched = dict(provider)
+        enriched["travel_time_minutes"] = travel_time
+        enriched["has_nearby_visits"] = has_nearby
+        enriched["recommended_departure_time"] = recommended_departure.strftime("%H:%M")
+        enriched_providers.append(enriched)
+
+    return {"travel_times": enriched_providers}
+
+
+def rank_and_present(state: SchedulingState) -> dict:
+    """Rank available providers by travel time and area affinity, then format for display.
+
+    Uses scheduling_engine.rank_providers_by_travel.
+
+    Returns:
+        {"ranked_matches": [...]} — sorted list of match dicts with fields:
+            provider_id, provider_name, provider_email, date, start_time, end_time,
+            travel_time_minutes, has_nearby_visits, summary
+    """
+    ranked = scheduling_engine.rank_providers_by_travel(state["travel_times"])
+    level_label = settings.get_visit_levels()[state["visit_level"]]["label"]
+
+    matches = []
+    for provider in ranked:
+        is_oncall = provider.get("is_oncall", False)
+        nearby_note = ", nearby visits" if provider["has_nearby_visits"] else ""
+        departure = provider.get("recommended_departure_time", "")
+        departure_note = f", depart by {departure}" if departure else ""
+        oncall_note = "[ON CALL] " if is_oncall else ""
+        summary = (
+            f"{oncall_note}{provider['name']} — {level_label} on {provider['available_date']} "
+            f"at {provider['available_start_time']}–{provider['available_end_time']} "
+            f"({provider['travel_time_minutes']} min travel{nearby_note}{departure_note})"
+        )
+        matches.append({
+            "provider_id": provider["id"],
+            "provider_name": provider["name"],
+            "provider_email": provider.get("email", ""),
+            "date": provider["available_date"],
+            "start_time": provider["available_start_time"],
+            "end_time": provider["available_end_time"],
+            "travel_time_minutes": provider["travel_time_minutes"],
+            "has_nearby_visits": provider["has_nearby_visits"],
+            "is_oncall": is_oncall,
+            "recommended_departure_time": departure,
+            "summary": summary,
+        })
+
+    return {"ranked_matches": matches}
+
+
+def book_appointment(state: SchedulingState) -> dict:
+    """Book the selected appointment.
+
+    Steps:
+        1. Final overlap check (in case something changed)
+        2. Create appointment record via data_manager.add_appointment
+        3. Create Google Calendar event via google_services.create_calendar_event
+        4. Update appointment record with google_event_id
+        5. Log action to audit log
+
+    Returns:
+        {"booked_appointment": {...}} or {"error": "Booking failed: ..."}
+    """
+    selection = state["user_selection"]
+    provider_id = selection["provider_id"]
+    date = selection["date"]
+    start_time = selection["start_time"]
+
+    # Final freshness check: re-fetch the provider and their current appointments
+    provider = data_manager.get_provider_by_id(provider_id)
+    if not provider:
+        return {"error": f"Booking failed: provider '{provider_id}' not found."}
+
+    existing = data_manager.get_appointments_for_provider(provider_id, date)
+    if not scheduling_engine.is_provider_available(
+        provider, date, start_time, state["visit_level"], existing
+    ):
+        return {"error": "Booking failed: the selected slot is no longer available."}
+
+    # Persist the appointment record
+    appointment_data = {
+        "patient_id": state["patient_id"],
+        "patient_name": state["patient_name"],
+        "provider_id": provider_id,
+        "provider_name": selection["provider_name"],
+        "date": date,
+        "start_time": start_time,
+        "end_time": selection["end_time"],
+        "visit_level": state["visit_level"],
+        "visit_address": state["visit_address"],
+        "recommended_departure_time": selection.get("recommended_departure_time", ""),
+        "status": "scheduled",
+        "google_event_id": None,
+    }
+    appointment = data_manager.add_appointment(appointment_data)
+
+    # Create Google Calendar event (non-critical — failure doesn't block booking)
+    try:
+        level_label = settings.get_visit_levels()[state["visit_level"]]["label"]
+        event_summary = f"[{level_label}] {state['patient_name']} — {selection['provider_name']}"
+        description = (
+            f"Patient: {state['patient_name']}\n"
+            f"Provider: {selection['provider_name']}\n"
+            f"Visit Level: {level_label}\n"
+            f"Address: {state['visit_address']}"
+        )
+        event_id = google_services.create_calendar_event(
+            summary=event_summary,
+            description=description,
+            location=state["visit_address"],
+            start_datetime=f"{date}T{start_time}:00",
+            end_datetime=f"{date}T{selection['end_time']}:00",
+        )
+        data_manager.update_appointment(appointment["id"], {"google_event_id": event_id})
+        appointment["google_event_id"] = event_id
+    except Exception:
+        pass
+
+    # Audit log
+    data_manager.log_action(
+        user="admin",
+        action="SCHEDULE",
+        details=(
+            f"Scheduled {settings.get_visit_levels()[state['visit_level']]['label']} visit for "
+            f"{state['patient_name']} with {selection['provider_name']} "
+            f"on {date} at {start_time}"
+        ),
+        appointment_id=appointment["id"],
+    )
+
+    return {"booked_appointment": appointment}
+
+
+def send_notifications(state: SchedulingState) -> dict:
+    """Send confirmation emails to both the provider and patient.
+
+    Uses google_services.send_scheduling_notification.
+
+    Returns:
+        {"notifications_sent": True/False}
+    """
+    appointment = state.get("booked_appointment")
+    if not appointment:
+        return {"notifications_sent": False}
+
+    selection = state["user_selection"]
+    appointment_details = {
+        "patient_name": state["patient_name"],
+        "provider_name": selection["provider_name"],
+        "date": appointment["date"],
+        "start_time": appointment["start_time"],
+        "end_time": appointment["end_time"],
+        "visit_level": settings.get_visit_levels()[state["visit_level"]]["label"],
+        "address": state["visit_address"],
+        "recommended_departure_time": appointment.get("recommended_departure_time", ""),
+    }
+
+    try:
+        result = google_services.send_scheduling_notification(
+            provider_email=selection.get("provider_email", ""),
+            patient_email=state.get("patient_email", ""),
+            appointment_details=appointment_details,
+        )
+        sent = result.get("provider_sent", False) or result.get("patient_sent", False)
+    except Exception:
+        sent = False
+
+    return {"notifications_sent": sent}
+
+
+def no_match(state: SchedulingState) -> dict:
+    """Handle the case where no providers are available.
+
+    Uses the LLM to generate a helpful message suggesting alternative dates/times.
+
+    Returns:
+        {"error": "No matching providers found. <suggestion>"}
+    """
+    existing_error = state.get("error", "No providers are available for the requested visit.")
+
+    try:
+        llm = _get_llm()
+        preferred_dates = state.get("preferred_dates", [])
+        visit_level = state.get("visit_level", "")
+        level_label = settings.get_visit_levels().get(visit_level, {}).get("label", str(visit_level))
+        window = state.get("preferred_time_window", {})
+
+        prompt = (
+            f"A home healthcare {level_label} visit could not be scheduled. "
+            f"Requested dates: {', '.join(preferred_dates)}. "
+            f"Requested time window: {window.get('start', '?')}–{window.get('end', '?')}. "
+            f"Provide 2–3 brief, practical suggestions the scheduler can try next "
+            f"(e.g., different dates, expanded time window, or different visit level if appropriate). "
+            f"Keep the response to 2 sentences maximum."
+        )
+
+        response = llm.invoke(prompt)
+        suggestion = response.content.strip()
+    except Exception:
+        suggestion = (
+            "Try selecting different dates, expanding the time window, "
+            "or contacting the scheduling team for assistance."
+        )
+
+    return {"error": f"{existing_error} {suggestion}"}

agent/state.py

@@ -0,0 +1,44 @@
+"""
+LangGraph State Schema — defines the typed state that flows through the scheduling graph.
+"""
+from typing import TypedDict, Optional
+
+
+class SchedulingState(TypedDict):
+    """State object that passes through all nodes in the scheduling graph.
+
+    Fields populated by the dashboard (input):
+        - patient_id, visit_level, visit_address, preferred_dates, preferred_time_window
+
+    Fields populated by agent nodes (intermediate):
+        - available_providers, travel_times, ranked_matches
+
+    Fields requiring human-in-the-loop (interaction):
+        - user_selection
+
+    Fields populated at completion (output):
+        - booked_appointment, notifications_sent, error
+    """
+    # --- Inputs from dashboard ---
+    patient_id: str
+    patient_name: str
+    patient_email: str
+    visit_level: int | str
+    visit_address: str
+    visit_lat: float
+    visit_lng: float
+    preferred_dates: list[str]           # ["2026-03-20", "2026-03-21"]
+    preferred_time_window: dict          # {"start": "09:00", "end": "12:00"}
+
+    # --- Intermediate results ---
+    available_providers: list[dict]      # Providers passing availability check
+    travel_times: list[dict]             # Provider dicts enriched with travel_time_minutes
+    ranked_matches: list[dict]           # Final ranked list presented to user
+
+    # --- Human-in-the-loop ---
+    user_selection: Optional[dict]       # The provider+time combo the user picked
+
+    # --- Outputs ---
+    booked_appointment: Optional[dict]   # The created appointment record
+    notifications_sent: bool
+    error: Optional[str]                 # Error message if something went wrong

api/appointments.py

@@ -0,0 +1,113 @@
+"""Appointment routes — list, cancel, and complete."""
+from datetime import datetime
+from zoneinfo import ZoneInfo
+from fastapi import APIRouter, Depends, HTTPException
+from core import data_manager, google_services
+from core import settings_manager as settings
+from api.deps import get_current_session
+
+router = APIRouter(prefix="/api/appointments", tags=["appointments"])
+
+
+@router.get("")
+def list_appointments(status: str | None = None, provider_id: str | None = None, session: dict = Depends(get_current_session)):
+    appts = data_manager.get_all_appointments(status=status)
+    if session.get("user_role") == "provider":
+        # Providers see only their own appointments
+        appts = [a for a in appts if a.get("provider_id") == session.get("provider_id")]
+    elif provider_id:
+        appts = [a for a in appts if a.get("provider_id") == provider_id]
+    return appts
+
+
+@router.delete("/{appointment_id}")
+def cancel_appointment(appointment_id: str, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider":
+        raise HTTPException(status_code=403, detail="Providers cannot cancel appointments")
+
+    appt = next((a for a in data_manager.get_all_appointments() if a.get("id") == appointment_id), None)
+    if not appt:
+        raise HTTPException(status_code=404, detail="Appointment not found")
+
+    cancelled = data_manager.cancel_appointment(appointment_id)
+    if not cancelled:
+        raise HTTPException(status_code=500, detail="Cancellation failed")
+
+    # Delete Google Calendar event (non-critical)
+    if appt.get("google_event_id"):
+        try:
+            google_services.delete_calendar_event(appt["google_event_id"])
+        except Exception:
+            pass
+
+    # Send cancellation notifications (non-critical)
+    try:
+        provider = data_manager.get_provider_by_id(appt["provider_id"])
+        patient = data_manager.get_patient_by_id(appt["patient_id"])
+        appointment_details = {
+            "patient_name": appt.get("patient_name", ""),
+            "provider_name": appt.get("provider_name", ""),
+            "date": appt.get("date", ""),
+            "start_time": appt.get("start_time", ""),
+            "end_time": appt.get("end_time", ""),
+            "address": appt.get("visit_address", ""),
+        }
+        google_services.send_cancellation_notification(
+            provider_email=provider.get("email", "") if provider else "",
+            patient_email=patient.get("email", "") if patient else "",
+            appointment_details=appointment_details,
+        )
+    except Exception:
+        pass
+
+    data_manager.log_action(
+        user=session["current_user"],
+        action="CANCEL",
+        details=(
+            f"Cancelled {appt.get('visit_level', '')} visit for "
+            f"{appt.get('patient_name', '')} with {appt.get('provider_name', '')} "
+            f"on {appt.get('date', '')} at {appt.get('start_time', '')}"
+        ),
+        appointment_id=appointment_id,
+    )
+    return {"ok": True}
+
+
+@router.post("/{appointment_id}/complete")
+def complete_appointment(appointment_id: str, session: dict = Depends(get_current_session)):
+    """Mark an appointment as completed. Provider-only; only allowed once the
+    appointment's start time has passed (compared in the platform timezone)."""
+    appt = next((a for a in data_manager.get_all_appointments() if a.get("id") == appointment_id), None)
+    if not appt:
+        raise HTTPException(status_code=404, detail="Appointment not found")
+
+    if session.get("user_role") == "provider" and session.get("provider_id") != appt.get("provider_id"):
+        raise HTTPException(status_code=403, detail="Can only complete your own appointments")
+
+    if appt.get("status") != "scheduled":
+        raise HTTPException(status_code=400, detail=f"Cannot complete appointment with status '{appt.get('status')}'")
+
+    # Compare in the platform timezone so a UTC server doesn't mis-evaluate.
+    try:
+        start_dt = datetime.strptime(f"{appt['date']} {appt['start_time']}", "%Y-%m-%d %H:%M")
+    except (KeyError, ValueError):
+        raise HTTPException(status_code=500, detail="Appointment has invalid date/time")
+    now_local = datetime.now(ZoneInfo(settings.get_timezone())).replace(tzinfo=None)
+    if now_local < start_dt:
+        raise HTTPException(status_code=400, detail="Appointment has not started yet")
+
+    completed = data_manager.complete_appointment(appointment_id)
+    if not completed:
+        raise HTTPException(status_code=500, detail="Failed to mark complete")
+
+    data_manager.log_action(
+        user=session["current_user"],
+        action="COMPLETE",
+        details=(
+            f"Completed {appt.get('visit_level', '')} visit for "
+            f"{appt.get('patient_name', '')} with {appt.get('provider_name', '')} "
+            f"on {appt.get('date', '')} at {appt.get('start_time', '')}"
+        ),
+        appointment_id=appointment_id,
+    )
+    return {"ok": True, "appointment": completed}

api/audit.py

@@ -0,0 +1,34 @@
+"""Audit log route."""
+from fastapi import APIRouter, Depends
+from core import data_manager
+from api.deps import require_admin_session
+
+router = APIRouter(prefix="/api/audit", tags=["audit"])
+
+
+@router.get("")
+def list_audit(
+    search: str | None = None,
+    action: str | None = None,
+    limit: int = 500,
+    session: dict = Depends(require_admin_session),
+):
+    log = data_manager.get_audit_log(limit=limit)
+    if action and action != "All":
+        log = [e for e in log if e.get("action") == action]
+    if search:
+        s = search.lower()
+        log = [
+            e for e in log
+            if s in str(e.get("details", "")).lower()
+            or s in str(e.get("action", "")).lower()
+            or s in str(e.get("user", "")).lower()
+            or s in str(e.get("appointment_id", "")).lower()
+        ]
+    return log
+
+
+@router.get("/actions")
+def action_types(session: dict = Depends(require_admin_session)):
+    log = data_manager.get_audit_log(limit=1000)
+    return sorted({e.get("action", "") for e in log if e.get("action")})

api/auth.py

@@ -0,0 +1,74 @@
+"""Auth routes: login (admin/provider), logout, me."""
+import os
+from fastapi import APIRouter, HTTPException, Response, Cookie
+from pydantic import BaseModel
+from utils import auth as auth_utils
+from api.deps import SESSION_COOKIE
+
+router = APIRouter(prefix="/api/auth", tags=["auth"])
+
+
+# HuggingFace Spaces serves the app inside a cross-site iframe, so the session
+# cookie needs SameSite=None; Secure to be sent. Locally over http://localhost,
+# `secure=True` would prevent the cookie from being set at all — so we detect
+# the environment and pick the right pair. HF sets SPACE_ID automatically.
+_IN_HF_SPACE = bool(os.environ.get("SPACE_ID"))
+_COOKIE_KW = (
+    {"samesite": "none", "secure": True} if _IN_HF_SPACE else {"samesite": "lax"}
+)
+
+
+class LoginRequest(BaseModel):
+    username: str
+    password: str
+
+
+class ProviderLoginRequest(BaseModel):
+    name: str
+    password: str
+
+
+@router.post("/login")
+def login(req: LoginRequest, response: Response):
+    if not auth_utils.check_credentials(req.username, req.password):
+        raise HTTPException(status_code=401, detail="Invalid username or password")
+    token = auth_utils.create_session(user_role="admin", current_user=req.username)
+    response.set_cookie(key=SESSION_COOKIE, value=token, httponly=True, max_age=60 * 60 * 24 * 7, **_COOKIE_KW)
+    return {"user_role": "admin", "current_user": req.username}
+
+
+@router.post("/provider-login")
+def provider_login(req: ProviderLoginRequest, response: Response):
+    provider = auth_utils.check_provider_credentials(req.name, req.password)
+    if not provider:
+        raise HTTPException(status_code=401, detail="Invalid provider name or password")
+    token = auth_utils.create_session(
+        user_role="provider",
+        current_user=provider["name"],
+        provider_id=provider["id"],
+    )
+    response.set_cookie(key=SESSION_COOKIE, value=token, httponly=True, max_age=60 * 60 * 24 * 7, **_COOKIE_KW)
+    return {"user_role": "provider", "current_user": provider["name"], "provider_id": provider["id"]}
+
+
+@router.post("/logout")
+def logout(response: Response, session_token: str | None = Cookie(default=None, alias=SESSION_COOKIE)):
+    auth_utils.destroy_session(session_token)
+    response.delete_cookie(SESSION_COOKIE)
+    return {"ok": True}
+
+
+@router.get("/me")
+def me(session_token: str | None = Cookie(default=None, alias=SESSION_COOKIE)):
+    session = auth_utils.get_session(session_token)
+    if not session:
+        return {"authenticated": False}
+    return {"authenticated": True, **session}
+
+
+@router.get("/provider-names")
+def provider_names():
+    """Public list of provider names for the login dropdown."""
+    from core import data_manager
+    providers = data_manager.get_all_providers(active_only=False)
+    return [{"id": p["id"], "name": p["name"]} for p in providers]

api/calendar.py

@@ -0,0 +1,187 @@
+"""Calendar route — produces FullCalendar-compatible events from appointments + provider blocks."""
+from datetime import datetime, timedelta
+from fastapi import APIRouter, Depends
+from core import data_manager
+from core import settings_manager as settings
+from core.scheduling_engine import add_minutes
+from api.deps import get_current_session
+
+router = APIRouter(prefix="/api/calendar", tags=["calendar"])
+
+
+# Deterministic color palette assigned to providers in load order.
+_PROVIDER_COLORS = [
+    "#2563eb", "#16a34a", "#dc2626", "#9333ea", "#ea580c",
+    "#0891b2", "#ca8a04", "#db2777", "#4f46e5", "#65a30d",
+]
+
+
+def _provider_color_map(providers: list[dict]) -> dict[str, str]:
+    return {p["id"]: _PROVIDER_COLORS[i % len(_PROVIDER_COLORS)] for i, p in enumerate(providers)}
+
+
+@router.get("/events")
+def get_events(
+    start: str | None = None,
+    end: str | None = None,
+    provider_ids: str | None = None,
+    show_unavailable: bool = True,
+    show_travel: bool = True,
+    show_oncall: bool = True,
+    session: dict = Depends(get_current_session),
+):
+    providers = data_manager.get_all_providers(active_only=False)
+    color_map = _provider_color_map(providers)
+
+    selected_ids: set[str] | None = None
+    if session.get("user_role") == "provider":
+        selected_ids = {session.get("provider_id")}
+    elif provider_ids:
+        selected_ids = set(provider_ids.split(",")) if provider_ids else None
+
+    visible_providers = [p for p in providers if (selected_ids is None or p["id"] in selected_ids)]
+
+    events = []
+    is_provider_view = session.get("user_role") == "provider"
+
+    # Appointments — include both scheduled and completed; render completed in grey.
+    appointments = [a for a in data_manager.get_all_appointments() if a.get("status") in ("scheduled", "completed")]
+    for a in appointments:
+        pid = a.get("provider_id")
+        if selected_ids is not None and pid not in selected_ids:
+            continue
+        status = a.get("status", "scheduled")
+        is_completed = status == "completed"
+        color = "#94a3b8" if is_completed else color_map.get(pid, "#2563eb")
+        if is_provider_view:
+            title = f"Visit — {a.get('visit_level', '')}"
+        else:
+            title = f"{a.get('patient_name', '')} — {a.get('provider_name', '')}"
+        if is_completed:
+            title = f"✓ {title}"
+        events.append({
+            "id": f"appt_{a['id']}",
+            "title": title,
+            "start": f"{a['date']}T{a['start_time']}:00",
+            "end": f"{a['date']}T{a['end_time']}:00",
+            "backgroundColor": color,
+            "borderColor": color,
+            "classNames": ["event-completed"] if is_completed else [],
+            "extendedProps": {
+                "type": "appointment",
+                "status": status,
+                "appointment_id": a["id"],
+                "patient_name": a.get("patient_name", ""),
+                "provider_name": a.get("provider_name", ""),
+                "provider_id": pid,
+                "visit_level": str(a.get("visit_level", "")),
+                "visit_address": a.get("visit_address", ""),
+                "recommended_departure_time": a.get("recommended_departure_time", ""),
+                "start_time": a.get("start_time", ""),
+                "end_time": a.get("end_time", ""),
+                "date": a.get("date", ""),
+                "completed_at": a.get("completed_at", ""),
+            },
+        })
+        # Travel block (30 min before, if departure time exists) — skip for completed visits.
+        if show_travel and not is_completed:
+            departure = a.get("recommended_departure_time")
+            if departure:
+                events.append({
+                    "id": f"travel_{a['id']}",
+                    "title": f"Travel to {a.get('patient_name', 'visit')}",
+                    "start": f"{a['date']}T{departure}:00",
+                    "end": f"{a['date']}T{a['start_time']}:00",
+                    "backgroundColor": color,
+                    "borderColor": color,
+                    "classNames": ["event-travel"],
+                    "extendedProps": {
+                        "type": "travel",
+                        "provider_id": pid,
+                        "provider_name": a.get("provider_name", ""),
+                    },
+                })
+
+    # Days-off blocks
+    if show_unavailable:
+        for p in visible_providers:
+            for off in p.get("days_off", []) or []:
+                if isinstance(off, str):
+                    off = {"date": off, "all_day": True, "title": "Day Off"}
+                d = off.get("date")
+                if not d:
+                    continue
+                title = off.get("title", "Unavailable")
+                if off.get("all_day", True):
+                    start_iso = f"{d}T00:00:00"
+                    end_iso = f"{d}T23:59:59"
+                else:
+                    start_iso = f"{d}T{off.get('start_time','00:00')}:00"
+                    end_iso = f"{d}T{off.get('end_time','23:59')}:00"
+                events.append({
+                    "id": f"off_{p['id']}_{d}_{title}",
+                    "title": f"{p['name']} — {title}",
+                    "start": start_iso,
+                    "end": end_iso,
+                    "backgroundColor": "#fecaca",
+                    "borderColor": "#dc2626",
+                    "textColor": "#7f1d1d",
+                    "extendedProps": {
+                        "type": "days_off",
+                        "provider_id": p["id"],
+                        "provider_name": p["name"],
+                        "title": title,
+                    },
+                })
+            # Recurring weekdays — render as background events for whole date range
+            recurring = p.get("recurring_days_off", []) or []
+            if recurring and start and end:
+                weekday_to_num = {"Monday":0,"Tuesday":1,"Wednesday":2,"Thursday":3,"Friday":4,"Saturday":5,"Sunday":6}
+                try:
+                    s_dt = datetime.strptime(start[:10], "%Y-%m-%d")
+                    e_dt = datetime.strptime(end[:10], "%Y-%m-%d")
+                except ValueError:
+                    s_dt = e_dt = None
+                if s_dt and e_dt:
+                    cur = s_dt
+                    while cur < e_dt:
+                        if cur.strftime("%A") in recurring:
+                            d_str = cur.strftime("%Y-%m-%d")
+                            events.append({
+                                "id": f"rec_{p['id']}_{d_str}",
+                                "title": f"{p['name']} — Standing Day Off",
+                                "start": f"{d_str}T00:00:00",
+                                "end": f"{d_str}T23:59:59",
+                                "display": "background",
+                                "backgroundColor": "#e5e7eb",
+                                "extendedProps": {"type": "recurring_off", "provider_id": p["id"]},
+                            })
+                        cur += timedelta(days=1)
+
+            # On-call dates highlight — 24h window from on_call_start_hour on date D
+            # to the same hour on D+1 (matches scheduling_engine.is_oncall_for_slot).
+            start_hour = settings.get_on_call_start_hour()  # "HH:MM"
+            for d in (p.get("on_call", []) or []) if show_oncall else []:
+                try:
+                    window_start = datetime.strptime(f"{d} {start_hour}", "%Y-%m-%d %H:%M")
+                except ValueError:
+                    continue
+                window_end = window_start + timedelta(hours=24)
+                events.append({
+                    "id": f"oncall_{p['id']}_{d}",
+                    "title": f"{p['name']} — ON CALL",
+                    "start": window_start.strftime("%Y-%m-%dT%H:%M:%S"),
+                    "end": window_end.strftime("%Y-%m-%dT%H:%M:%S"),
+                    "backgroundColor": "#10b981",
+                    "borderColor": "#047857",
+                    "textColor": "#ffffff",
+                    "extendedProps": {"type": "on_call", "provider_id": p["id"]},
+                })
+
+    return {
+        "events": events,
+        "providers": [
+            {"id": p["id"], "name": p["name"], "color": color_map[p["id"]]}
+            for p in providers
+        ],
+    }

api/deps.py

@@ -0,0 +1,30 @@
+"""FastAPI dependencies — auth, current user."""
+from fastapi import Cookie, HTTPException, status
+from utils import auth as auth_utils
+
+SESSION_COOKIE = "session_token"
+
+
+def get_current_session(session_token: str | None = Cookie(default=None, alias=SESSION_COOKIE)) -> dict:
+    session = auth_utils.get_session(session_token)
+    if not session:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    return session
+
+
+def require_admin(session: dict = None) -> dict:
+    if session is None:
+        from fastapi import Depends
+        session = Depends(get_current_session)
+    if session.get("user_role") != "admin":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin required")
+    return session
+
+
+def require_admin_session(session_token: str | None = Cookie(default=None, alias=SESSION_COOKIE)) -> dict:
+    session = auth_utils.get_session(session_token)
+    if not session:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Not authenticated")
+    if session.get("user_role") != "admin":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin required")
+    return session

api/patients.py

@@ -0,0 +1,106 @@
+"""Patient CRUD routes."""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from core import data_manager, google_services
+from api.deps import get_current_session, require_admin_session
+
+router = APIRouter(prefix="/api/patients", tags=["patients"])
+
+
+class PatientCreate(BaseModel):
+    name: str
+    email: str = ""
+    address: str = ""
+    notes: str = ""
+
+
+class PatientUpdate(BaseModel):
+    name: str | None = None
+    email: str | None = None
+    address: str | None = None
+    notes: str | None = None
+
+
+def _geocode(address: str) -> tuple[float | None, float | None]:
+    try:
+        result = google_services.geocode_address(address)
+        if result:
+            return result[0], result[1]
+    except Exception:
+        pass
+    return None, None
+
+
+@router.get("")
+def list_patients(session: dict = Depends(get_current_session)):
+    return data_manager.get_all_patients()
+
+
+@router.get("/{patient_id}")
+def get_patient(patient_id: str, session: dict = Depends(get_current_session)):
+    p = data_manager.get_patient_by_id(patient_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Patient not found")
+    return p
+
+
+@router.post("")
+def create_patient(req: PatientCreate, session: dict = Depends(require_admin_session)):
+    if not req.name:
+        raise HTTPException(status_code=400, detail="Patient name is required")
+    lat, lng = _geocode(req.address) if req.address else (None, None)
+    patient_data = {
+        "name": req.name,
+        "email": req.email,
+        "address": req.address,
+        "notes": req.notes,
+        "lat": lat,
+        "lng": lng,
+    }
+    new_patient = data_manager.add_patient(patient_data)
+    data_manager.log_action(
+        session["current_user"], "ADD_PATIENT",
+        f"Added patient: {req.name} ({new_patient['id']})",
+    )
+    return new_patient
+
+
+@router.put("/{patient_id}")
+def update_patient(patient_id: str, req: PatientUpdate, session: dict = Depends(require_admin_session)):
+    existing = data_manager.get_patient_by_id(patient_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Patient not found")
+    updates: dict = {}
+    if req.name is not None:
+        updates["name"] = req.name
+    if req.email is not None:
+        updates["email"] = req.email
+    if req.notes is not None:
+        updates["notes"] = req.notes
+    if req.address is not None:
+        updates["address"] = req.address
+        if req.address != existing.get("address"):
+            lat, lng = _geocode(req.address) if req.address else (None, None)
+            updates["lat"] = lat
+            updates["lng"] = lng
+    updated = data_manager.update_patient(patient_id, updates)
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PATIENT",
+        f"Updated patient: {updated['name']} ({patient_id})",
+    )
+    return updated
+
+
+@router.delete("/{patient_id}")
+def delete_patient(patient_id: str, session: dict = Depends(require_admin_session)):
+    p = data_manager.get_patient_by_id(patient_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Patient not found")
+    ok = data_manager.delete_patient(patient_id)
+    if not ok:
+        raise HTTPException(status_code=500, detail="Delete failed")
+    data_manager.log_action(
+        session["current_user"], "DELETE_PATIENT",
+        f"Deleted patient: {p['name']} ({patient_id})",
+    )
+    return {"ok": True}

api/providers.py

@@ -0,0 +1,309 @@
+"""Provider CRUD routes."""
+from datetime import date as date_cls
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from typing import Any
+from core import data_manager
+from core.scheduling_engine import normalize_time_str
+from api.deps import get_current_session, require_admin_session
+
+router = APIRouter(prefix="/api/providers", tags=["providers"])
+
+
+# --- Pydantic models ---
+
+class WorkHours(BaseModel):
+    start: str
+    end: str
+
+
+class ProviderCreate(BaseModel):
+    name: str
+    email: str = ""
+    password: str = ""
+    address: str = ""
+    category: str = "provider"  # provider | nurse
+    work_hours: WorkHours
+    lunch_break: WorkHours
+    service_levels: list[Any] = []
+
+
+class ProviderUpdate(BaseModel):
+    name: str | None = None
+    email: str | None = None
+    password: str | None = None
+    address: str | None = None
+    category: str | None = None
+    work_hours: WorkHours | None = None
+    lunch_break: WorkHours | None = None
+    service_levels: list[Any] | None = None
+
+
+class RecurringDaysOff(BaseModel):
+    recurring_days_off: list[str]
+
+
+class DaysOffEntry(BaseModel):
+    date: str
+    all_day: bool = True
+    start_time: str | None = None
+    end_time: str | None = None
+    title: str = "Unavailable"
+
+
+class OnCallEntry(BaseModel):
+    date: str
+
+
+def _normalize_hours(work_hours: WorkHours, lunch: WorkHours) -> tuple[dict, dict]:
+    fields = {
+        "Work Hours Start": work_hours.start,
+        "Work Hours End": work_hours.end,
+        "Lunch Start": lunch.start,
+        "Lunch End": lunch.end,
+    }
+    out = {}
+    for label, value in fields.items():
+        n = normalize_time_str(value)
+        if n is None:
+            raise HTTPException(status_code=400, detail=f"{label} is not a valid time (HH:MM): {value!r}")
+        out[label] = n
+    return (
+        {"start": out["Work Hours Start"], "end": out["Work Hours End"]},
+        {"start": out["Lunch Start"], "end": out["Lunch End"]},
+    )
+
+
+@router.get("")
+def list_providers(active_only: bool = False, session: dict = Depends(get_current_session)):
+    return data_manager.get_all_providers(active_only=active_only)
+
+
+@router.get("/{provider_id}")
+def get_provider(provider_id: str, session: dict = Depends(get_current_session)):
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    # Provider users can only access their own record
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    return p
+
+
+@router.post("")
+def create_provider(req: ProviderCreate, session: dict = Depends(require_admin_session)):
+    if not req.name:
+        raise HTTPException(status_code=400, detail="Provider name is required")
+    wh, lb = _normalize_hours(req.work_hours, req.lunch_break)
+    provider_data = {
+        "name": req.name,
+        "email": req.email,
+        "password": req.password,
+        "address": req.address,
+        "category": req.category,
+        "work_hours": wh,
+        "lunch_break": lb,
+        "service_levels": req.service_levels,
+    }
+    new_prov = data_manager.add_provider(provider_data)
+    data_manager.log_action(
+        session["current_user"], "ADD_PROVIDER",
+        f"Added provider: {req.name} ({new_prov['id']})",
+    )
+    return new_prov
+
+
+@router.put("/{provider_id}")
+def update_provider(provider_id: str, req: ProviderUpdate, session: dict = Depends(get_current_session)):
+    # Providers may only edit themselves
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+
+    existing = data_manager.get_provider_by_id(provider_id)
+    if not existing:
+        raise HTTPException(status_code=404, detail="Provider not found")
+
+    updates: dict = {}
+    if req.name is not None:
+        updates["name"] = req.name
+    if req.email is not None:
+        updates["email"] = req.email
+    if req.password is not None:
+        updates["password"] = req.password
+    if req.address is not None:
+        updates["address"] = req.address
+    if req.category is not None:
+        updates["category"] = req.category
+    if req.service_levels is not None:
+        updates["service_levels"] = req.service_levels
+    if req.work_hours is not None and req.lunch_break is not None:
+        wh, lb = _normalize_hours(req.work_hours, req.lunch_break)
+        updates["work_hours"] = wh
+        updates["lunch_break"] = lb
+    elif req.work_hours is not None:
+        # normalize alone
+        s = normalize_time_str(req.work_hours.start)
+        e = normalize_time_str(req.work_hours.end)
+        if not s or not e:
+            raise HTTPException(status_code=400, detail="Invalid work hours")
+        updates["work_hours"] = {"start": s, "end": e}
+    elif req.lunch_break is not None:
+        s = normalize_time_str(req.lunch_break.start)
+        e = normalize_time_str(req.lunch_break.end)
+        if not s or not e:
+            raise HTTPException(status_code=400, detail="Invalid lunch break")
+        updates["lunch_break"] = {"start": s, "end": e}
+
+    updated = data_manager.update_provider(provider_id, updates)
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Updated provider: {updated['name']} ({provider_id})",
+    )
+    return updated
+
+
+@router.delete("/{provider_id}")
+def delete_provider(provider_id: str, session: dict = Depends(require_admin_session)):
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    ok = data_manager.delete_provider(provider_id)
+    if not ok:
+        raise HTTPException(status_code=500, detail="Delete failed")
+    data_manager.log_action(
+        session["current_user"], "DELETE_PROVIDER",
+        f"Deleted provider: {p['name']} ({provider_id})",
+    )
+    return {"ok": True}
+
+
+# --- Recurring days off ---
+
+@router.put("/{provider_id}/recurring-days-off")
+def update_recurring_days_off(provider_id: str, req: RecurringDaysOff, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    updated = data_manager.update_provider(provider_id, {"recurring_days_off": req.recurring_days_off})
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Updated standing days off for {p['name']}: {', '.join(req.recurring_days_off) or 'None'}",
+    )
+    return updated
+
+
+# --- Days off (unavailable blocks) ---
+
+@router.post("/{provider_id}/days-off")
+def add_days_off(provider_id: str, req: DaysOffEntry, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+
+    is_all_day = req.all_day
+    new_entry = {
+        "date": req.date,
+        "all_day": is_all_day,
+        "start_time": None if is_all_day else req.start_time,
+        "end_time": None if is_all_day else req.end_time,
+        "title": req.title or "Unavailable",
+    }
+    current = p.get("days_off", []) or []
+    current.append(new_entry)
+    updated = data_manager.update_provider(provider_id, {"days_off": current})
+    detail = f"all day on {req.date}" if is_all_day else f"{req.start_time}–{req.end_time} on {req.date}"
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Added unavailable block for {p['name']}: {req.title} ({detail})",
+    )
+    return updated
+
+
+@router.delete("/{provider_id}/days-off/{index}")
+def remove_days_off(provider_id: str, index: int, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    current = p.get("days_off", []) or []
+    if index < 0 or index >= len(current):
+        raise HTTPException(status_code=400, detail="Invalid index")
+    removed = current.pop(index)
+    updated = data_manager.update_provider(provider_id, {"days_off": current})
+    label = removed if isinstance(removed, str) else f"{removed.get('date')} {removed.get('title','')}"
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Removed unavailable block from {p['name']}: {label}",
+    )
+    return updated
+
+
+# --- On-Call ---
+
+@router.post("/{provider_id}/on-call")
+def add_on_call(provider_id: str, req: OnCallEntry, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    current = sorted(p.get("on_call", []) or [])
+    if req.date in current:
+        return {"ok": True, "duplicate": True, "provider": p}
+    current = sorted(current + [req.date])
+    updated = data_manager.update_provider(provider_id, {"on_call": current})
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Added on-call day for {p['name']}: {req.date}",
+    )
+    return updated
+
+
+@router.delete("/{provider_id}/on-call/{date}")
+def remove_on_call(provider_id: str, date: str, session: dict = Depends(get_current_session)):
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    current = [d for d in (p.get("on_call", []) or []) if d != date]
+    updated = data_manager.update_provider(provider_id, {"on_call": current})
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"Removed on-call day for {p['name']}: {date}",
+    )
+    return updated
+
+
+class OnCallToggle(BaseModel):
+    date: str
+    on_call: bool
+
+
+@router.post("/{provider_id}/on-call/toggle")
+def toggle_on_call(provider_id: str, req: OnCallToggle, session: dict = Depends(get_current_session)):
+    """Toggle on-call status for a specific date. Convenience endpoint for the UI switch."""
+    if session.get("user_role") == "provider" and session.get("provider_id") != provider_id:
+        raise HTTPException(status_code=403, detail="Forbidden")
+    p = data_manager.get_provider_by_id(provider_id)
+    if not p:
+        raise HTTPException(status_code=404, detail="Provider not found")
+    current = set(p.get("on_call", []) or [])
+    if req.on_call:
+        current.add(req.date)
+        action_word = "Enabled"
+    else:
+        current.discard(req.date)
+        action_word = "Disabled"
+    new_list = sorted(current)
+    updated = data_manager.update_provider(provider_id, {"on_call": new_list})
+    data_manager.log_action(
+        session["current_user"], "UPDATE_PROVIDER",
+        f"{action_word} on-call for {p['name']}: {req.date}",
+    )
+    return updated

api/schedule.py

@@ -0,0 +1,133 @@
+"""Schedule visit routes — find matches and book via LangGraph agent."""
+import uuid
+import threading
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from typing import Any
+from core import data_manager
+from core import settings_manager as settings
+from agent.graph import build_scheduling_graph
+from api.deps import require_admin_session
+
+router = APIRouter(prefix="/api/schedule", tags=["schedule"])
+
+_graph = None
+_graph_lock = threading.Lock()
+
+
+def _get_graph():
+    global _graph
+    with _graph_lock:
+        if _graph is None:
+            _graph = build_scheduling_graph()
+        return _graph
+
+
+# In-memory thread-id store for active scheduling sessions.
+_threads: dict[str, dict] = {}
+
+
+class FindMatchesRequest(BaseModel):
+    patient_id: str
+    visit_level: Any  # int or "Nurse"
+    visit_address: str
+    preferred_dates: list[str]
+    preferred_time_window: dict  # {"start": "09:00", "end": "12:00"}
+
+
+class BookRequest(BaseModel):
+    thread_id: str
+    selection_index: int
+
+
+@router.get("/visit-levels")
+def visit_levels():
+    return [{"key": k, "label": v["label"], "duration_minutes": v["duration_minutes"]} for k, v in settings.get_visit_levels().items()]
+
+
+@router.get("/config")
+def schedule_config():
+    """Public scheduling config used by the date/time picker."""
+    return {
+        "min_lead_time_hours": settings.get_min_lead_time_hours(),
+        "timezone": settings.get_timezone(),
+    }
+
+
+@router.post("/find-matches")
+def find_matches(req: FindMatchesRequest, session: dict = Depends(require_admin_session)):
+    patient = data_manager.get_patient_by_id(req.patient_id)
+    if not patient:
+        raise HTTPException(status_code=404, detail="Patient not found")
+
+    # Convert visit_level to int if numeric string
+    vl: Any = req.visit_level
+    if isinstance(vl, str) and vl.isdigit():
+        vl = int(vl)
+
+    initial_state = {
+        "patient_id": req.patient_id,
+        "patient_name": patient["name"],
+        "patient_email": patient.get("email", ""),
+        "visit_level": vl,
+        "visit_address": req.visit_address,
+        "visit_lat": patient.get("lat"),
+        "visit_lng": patient.get("lng"),
+        "preferred_dates": req.preferred_dates,
+        "preferred_time_window": req.preferred_time_window,
+        "available_providers": [],
+        "travel_times": [],
+        "ranked_matches": [],
+        "user_selection": None,
+        "booked_appointment": None,
+        "notifications_sent": False,
+        "error": None,
+    }
+
+    thread_id = str(uuid.uuid4())
+    config = {"configurable": {"thread_id": thread_id}}
+    result = _get_graph().invoke(initial_state, config)
+
+    _threads[thread_id] = {"config": config, "ranked_matches": result.get("ranked_matches", [])}
+
+    if result.get("error"):
+        return {"thread_id": thread_id, "error": result["error"], "ranked_matches": []}
+    return {
+        "thread_id": thread_id,
+        "ranked_matches": result.get("ranked_matches", []),
+        "error": None,
+    }
+
+
+@router.post("/book")
+def book(req: BookRequest, session: dict = Depends(require_admin_session)):
+    record = _threads.get(req.thread_id)
+    if not record:
+        raise HTTPException(status_code=400, detail="Invalid or expired thread_id")
+    matches = record["ranked_matches"]
+    if req.selection_index < 0 or req.selection_index >= len(matches):
+        raise HTTPException(status_code=400, detail="Invalid selection_index")
+    match = matches[req.selection_index]
+    user_selection = {
+        "provider_id": match["provider_id"],
+        "provider_name": match["provider_name"],
+        "provider_email": match.get("provider_email", ""),
+        "date": match["date"],
+        "start_time": match["start_time"],
+        "end_time": match["end_time"],
+        "recommended_departure_time": match.get("recommended_departure_time", ""),
+    }
+    graph = _get_graph()
+    config = record["config"]
+    graph.update_state(config, {"user_selection": user_selection})
+    result = graph.invoke(None, config)
+
+    # Clean up thread
+    _threads.pop(req.thread_id, None)
+
+    if result.get("error"):
+        return {"error": result["error"]}
+    return {
+        "booked_appointment": result.get("booked_appointment"),
+        "notifications_sent": result.get("notifications_sent", False),
+    }

api/settings.py

@@ -0,0 +1,110 @@
+"""Settings routes — admin-editable runtime configuration."""
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from typing import Any
+
+from core import data_manager
+from core import settings_manager as settings
+from core.scheduling_engine import normalize_time_str
+from api.deps import require_admin_session
+
+router = APIRouter(prefix="/api/settings", tags=["settings"])
+
+
+class SettingsUpdate(BaseModel):
+    min_lead_time_hours: int | None = None
+    buffer_minutes: int | None = None
+    visit_levels: dict | None = None
+    on_call_start_hour: str | None = None
+    region_name: str | None = None
+    timezone: str | None = None
+    service_area: str | None = None
+    openai_model: str | None = None
+
+
+def _audit(user: str, detail: str) -> None:
+    data_manager.log_action(user, "UPDATE_SETTING", detail)
+
+
+@router.get("")
+def get_settings(session: dict = Depends(require_admin_session)):
+    """Return current effective values plus the per-key defaults."""
+    return {
+        "current": settings.get_all_settings(),
+        "defaults": settings.get_schema_defaults(),
+    }
+
+
+@router.put("")
+def update_settings(req: SettingsUpdate, session: dict = Depends(require_admin_session)):
+    current = settings.get_all_settings()
+    changes: list[str] = []
+
+    if req.min_lead_time_hours is not None and req.min_lead_time_hours != current["min_lead_time_hours"]:
+        if req.min_lead_time_hours < 0 or req.min_lead_time_hours > 168:
+            raise HTTPException(status_code=400, detail="min_lead_time_hours must be 0-168")
+        settings.set_setting("min_lead_time_hours", int(req.min_lead_time_hours))
+        changes.append(f"min_lead_time_hours: {current['min_lead_time_hours']} → {req.min_lead_time_hours}")
+
+    if req.buffer_minutes is not None and req.buffer_minutes != current["buffer_minutes"]:
+        if req.buffer_minutes < 0 or req.buffer_minutes > 120:
+            raise HTTPException(status_code=400, detail="buffer_minutes must be 0-120")
+        settings.set_setting("buffer_minutes", int(req.buffer_minutes))
+        changes.append(f"buffer_minutes: {current['buffer_minutes']} → {req.buffer_minutes}")
+
+    if req.on_call_start_hour is not None and req.on_call_start_hour != current["on_call_start_hour"]:
+        normalized = normalize_time_str(req.on_call_start_hour)
+        if normalized is None:
+            raise HTTPException(status_code=400, detail="on_call_start_hour must be HH:MM (e.g. 07:00)")
+        settings.set_setting("on_call_start_hour", normalized)
+        changes.append(f"on_call_start_hour: {current['on_call_start_hour']} → {normalized}")
+
+    if req.visit_levels is not None and req.visit_levels != current["visit_levels"]:
+        # Validate shape: each value must have 'label' and integer 'duration_minutes'.
+        for k, v in req.visit_levels.items():
+            if not isinstance(v, dict) or "duration_minutes" not in v:
+                raise HTTPException(status_code=400, detail=f"visit_levels[{k}] missing duration_minutes")
+            try:
+                int(v["duration_minutes"])
+            except Exception:
+                raise HTTPException(status_code=400, detail=f"visit_levels[{k}].duration_minutes not an integer")
+        # Re-key: convert digit-string keys back to ints so the format matches the schema.
+        normalized_levels = {
+            (int(k) if isinstance(k, str) and k.isdigit() else k): {
+                "label": v.get("label", str(k)),
+                "duration_minutes": int(v["duration_minutes"]),
+            }
+            for k, v in req.visit_levels.items()
+        }
+        settings.set_setting("visit_levels", normalized_levels)
+        changes.append("visit_levels updated")
+
+    if req.region_name is not None and req.region_name != current["region_name"]:
+        settings.set_setting("region_name", req.region_name)
+        changes.append(f"region_name: {current['region_name']} → {req.region_name}")
+
+    if req.timezone is not None and req.timezone != current["timezone"]:
+        settings.set_setting("timezone", req.timezone)
+        changes.append(f"timezone: {current['timezone']} → {req.timezone}")
+
+    if req.service_area is not None and req.service_area != current["service_area"]:
+        settings.set_setting("service_area", req.service_area)
+        changes.append(f"service_area: {current['service_area']} → {req.service_area}")
+
+    if req.openai_model is not None and req.openai_model != current["openai_model"]:
+        settings.set_setting("openai_model", req.openai_model)
+        changes.append(f"openai_model: {current['openai_model']} → {req.openai_model}")
+
+    if changes:
+        _audit(session["current_user"], "; ".join(changes))
+
+    return {"changes": changes, "current": settings.get_all_settings()}
+
+
+@router.post("/reset")
+def reset_to_defaults(session: dict = Depends(require_admin_session)):
+    defaults = settings.get_schema_defaults()
+    for key, default in defaults.items():
+        settings.set_setting(key, default)
+    _audit(session["current_user"], "Reset all settings to defaults")
+    return {"current": settings.get_all_settings()}

config.py

@@ -0,0 +1,35 @@
+"""
+Configuration — constants, business rules, and region-specific settings.
+Change REGION_NAME, TIMEZONE, and SERVICE_AREA when forking for other regions.
+"""
+
+# Region configuration — change these when forking for FL
+REGION_NAME = "Chicago"
+TIMEZONE = "America/Chicago"
+SERVICE_AREA = "Chicago, IL metro area"
+
+# Visit level definitions
+VISIT_LEVELS = {
+    1:      {"label": "Level 1", "duration_minutes": 45},
+    2:      {"label": "Level 2", "duration_minutes": 60},
+    3:      {"label": "Level 3", "duration_minutes": 90},
+    "Nurse": {"label": "Nurse Visit", "duration_minutes": 60},
+}
+
+BUFFER_MINUTES = 15  # Buffer between visits (on top of travel time)
+MIN_LEAD_TIME_HOURS = 24  # Minimum scheduling lead time
+DEFAULT_WORK_HOURS = {"start": "08:00", "end": "17:00"}
+DEFAULT_LUNCH_BREAK = {"start": "12:00", "end": "13:00"}
+
+# Legacy JSON paths (kept for seed_sheets.py migration script)
+DATA_DIR = "data"
+PROVIDERS_FILE = "data/providers.json"
+PATIENTS_FILE = "data/patients.json"
+APPOINTMENTS_FILE = "data/appointments.json"
+AUDIT_LOG_FILE = "data/audit_log.json"
+
+# OpenAI
+OPENAI_MODEL = "gpt-5.2"
+
+# Organization
+ORG_NAME = "SOS Care Now"

core/__init__.py

@@ -0,0 +1 @@
+"""core package."""

core/data_manager.py

@@ -0,0 +1,379 @@
+"""
+Data Manager — CRUD operations backed by Google Sheets.
+Refactored for FastAPI: module-level caching instead of streamlit.session_state.
+"""
+import json
+import base64
+import os
+import time
+import threading
+from datetime import datetime
+
+import gspread
+from google.oauth2 import service_account
+
+
+def _get_secret(key: str) -> str:
+    return os.environ.get(key)
+
+
+# --- Module-level caching ---
+# RLock (reentrant): some helpers acquire the lock while calling another helper
+# that also acquires it (e.g. _get_worksheet -> _get_spreadsheet). A plain Lock
+# would deadlock.
+_lock = threading.RLock()
+_state: dict = {
+    "spreadsheet": None,
+    "worksheets": {},
+    "headers": {},
+    "read_cache": {},  # name -> (timestamp, list[dict])
+}
+_READ_TTL_SECONDS = 60
+
+
+def _get_spreadsheet() -> gspread.Spreadsheet:
+    with _lock:
+        if _state["spreadsheet"] is None:
+            creds_b64 = _get_secret("GOOGLE_CALENDAR_CREDENTIALS")
+            creds_json = json.loads(base64.b64decode(creds_b64).decode("utf-8"))
+            credentials = service_account.Credentials.from_service_account_info(
+                creds_json,
+                scopes=[
+                    "https://www.googleapis.com/auth/spreadsheets",
+                    "https://www.googleapis.com/auth/drive",
+                ],
+            )
+            client = gspread.authorize(credentials)
+            sheet_id = _get_secret("GOOGLE_SHEET_ID")
+            _state["spreadsheet"] = client.open_by_key(sheet_id)
+        return _state["spreadsheet"]
+
+
+def _get_worksheet(name: str) -> gspread.Worksheet:
+    with _lock:
+        if name not in _state["worksheets"]:
+            _state["worksheets"][name] = _get_spreadsheet().worksheet(name)
+        return _state["worksheets"][name]
+
+
+_JSON_FIELDS = {
+    "work_hours", "lunch_break", "days_off", "recurring_days_off", "service_levels",
+    "on_call",
+}
+
+
+def _serialize_row(data: dict) -> dict:
+    row = {}
+    for k, v in data.items():
+        if k in _JSON_FIELDS:
+            row[k] = json.dumps(v)
+        elif v is None:
+            row[k] = ""
+        elif isinstance(v, bool):
+            row[k] = str(v)
+        else:
+            row[k] = str(v)
+    return row
+
+
+def _deserialize_row(row: dict) -> dict:
+    data = {}
+    for k, v in row.items():
+        if k in _JSON_FIELDS:
+            try:
+                data[k] = json.loads(v) if v else []
+            except (json.JSONDecodeError, TypeError):
+                data[k] = []
+        elif k in ("lat", "lng"):
+            if v == "" or v is None:
+                data[k] = None
+            else:
+                try:
+                    data[k] = float(v)
+                except (ValueError, TypeError):
+                    data[k] = None
+        elif k == "active":
+            data[k] = v.lower() == "true" if isinstance(v, str) else bool(v)
+        elif k == "visit_level":
+            try:
+                data[k] = int(v)
+            except (ValueError, TypeError):
+                data[k] = v
+        else:
+            data[k] = v
+    return data
+
+
+def _read_all(worksheet_name: str) -> list[dict]:
+    with _lock:
+        cached = _state["read_cache"].get(worksheet_name)
+        if cached and (time.time() - cached[0]) < _READ_TTL_SECONDS:
+            return list(cached[1])
+    ws = _get_worksheet(worksheet_name)
+    records = ws.get_all_records()
+    data = [_deserialize_row(r) for r in records]
+    with _lock:
+        _state["read_cache"][worksheet_name] = (time.time(), data)
+    return list(data)
+
+
+def _invalidate_cache(worksheet_name: str) -> None:
+    with _lock:
+        _state["read_cache"].pop(worksheet_name, None)
+
+
+def _get_headers(worksheet_name: str) -> list[str]:
+    with _lock:
+        if worksheet_name in _state["headers"]:
+            return list(_state["headers"][worksheet_name])
+    ws = _get_worksheet(worksheet_name)
+    headers = ws.row_values(1)
+    with _lock:
+        _state["headers"][worksheet_name] = headers
+    return list(headers)
+
+
+def _col_letter(n: int) -> str:
+    result = ""
+    while n > 0:
+        n, remainder = divmod(n - 1, 26)
+        result = chr(65 + remainder) + result
+    return result
+
+
+def _ensure_columns(worksheet_name: str, required: list[str]) -> list[str]:
+    headers = _get_headers(worksheet_name)
+    missing = [c for c in required if c not in headers]
+    if not missing:
+        return headers
+    ws = _get_worksheet(worksheet_name)
+    new_headers = headers + missing
+    end_col = _col_letter(len(new_headers))
+    ws.update(values=[new_headers], range_name=f"A1:{end_col}1", value_input_option="RAW")
+    with _lock:
+        _state["headers"][worksheet_name] = new_headers
+    _invalidate_cache(worksheet_name)
+    return new_headers
+
+
+def _find_row_index(worksheet_name: str, id_column: str, id_value: str) -> int | None:
+    records = _read_all(worksheet_name)
+    for i, record in enumerate(records):
+        if record.get(id_column) == id_value:
+            return i + 2
+    return None
+
+
+def _append_row(worksheet_name: str, data: dict) -> None:
+    ws = _get_worksheet(worksheet_name)
+    headers = _get_headers(worksheet_name)
+    row_values = [_serialize_row(data).get(h, "") for h in headers]
+    ws.append_row(row_values, value_input_option="RAW")
+    _invalidate_cache(worksheet_name)
+
+
+def _update_row(worksheet_name: str, row_index: int, data: dict) -> None:
+    ws = _get_worksheet(worksheet_name)
+    headers = _get_headers(worksheet_name)
+    serialized = _serialize_row(data)
+    row_values = [serialized.get(h, "") for h in headers]
+    end_col = _col_letter(len(headers))
+    ws.update(values=[row_values], range_name=f"A{row_index}:{end_col}{row_index}", value_input_option="RAW")
+    _invalidate_cache(worksheet_name)
+
+
+def _generate_id(prefix: str, existing_ids: list[str]) -> str:
+    if not existing_ids:
+        return f"{prefix}_001"
+    nums = []
+    for eid in existing_ids:
+        parts = eid.split("_")
+        if len(parts) >= 2:
+            try:
+                nums.append(int(parts[-1]))
+            except ValueError:
+                pass
+    next_num = max(nums, default=0) + 1
+    return f"{prefix}_{next_num:03d}"
+
+
+# --- Providers ---
+
+def get_all_providers(active_only: bool = True) -> list[dict]:
+    providers = _read_all("Providers")
+    if active_only:
+        return [p for p in providers if p.get("active", True)]
+    return providers
+
+
+def get_provider_by_id(provider_id: str) -> dict | None:
+    for p in _read_all("Providers"):
+        if p.get("id") == provider_id:
+            return p
+    return None
+
+
+def get_provider_by_name(name: str) -> dict | None:
+    for p in _read_all("Providers"):
+        if p.get("name", "").lower() == name.lower():
+            return p
+    return None
+
+
+def add_provider(provider_data: dict) -> dict:
+    _ensure_columns("Providers", ["on_call"])
+    providers = _read_all("Providers")
+    existing_ids = [p["id"] for p in providers if "id" in p]
+    provider_data["id"] = _generate_id("prov", existing_ids)
+    provider_data.setdefault("active", True)
+    provider_data.setdefault("days_off", [])
+    provider_data.setdefault("recurring_days_off", [])
+    provider_data.setdefault("on_call", [])
+    provider_data.setdefault("lat", None)
+    provider_data.setdefault("lng", None)
+    _append_row("Providers", provider_data)
+    return provider_data
+
+
+def update_provider(provider_id: str, updates: dict) -> dict | None:
+    if "on_call" in updates:
+        _ensure_columns("Providers", ["on_call"])
+    row_idx = _find_row_index("Providers", "id", provider_id)
+    if row_idx is None:
+        return None
+    providers = _read_all("Providers")
+    for p in providers:
+        if p.get("id") == provider_id:
+            p.update(updates)
+            _update_row("Providers", row_idx, p)
+            return p
+    return None
+
+
+def delete_provider(provider_id: str) -> bool:
+    row_idx = _find_row_index("Providers", "id", provider_id)
+    if row_idx is None:
+        return False
+    ws = _get_worksheet("Providers")
+    ws.delete_rows(row_idx)
+    _invalidate_cache("Providers")
+    return True
+
+
+# --- Patients ---
+
+def get_all_patients() -> list[dict]:
+    return _read_all("Patients")
+
+
+def get_patient_by_id(patient_id: str) -> dict | None:
+    for p in _read_all("Patients"):
+        if p.get("id") == patient_id:
+            return p
+    return None
+
+
+def add_patient(patient_data: dict) -> dict:
+    patients = _read_all("Patients")
+    existing_ids = [p["id"] for p in patients if "id" in p]
+    patient_data["id"] = _generate_id("pat", existing_ids)
+    patient_data.setdefault("lat", None)
+    patient_data.setdefault("lng", None)
+    patient_data.setdefault("notes", "")
+    _append_row("Patients", patient_data)
+    return patient_data
+
+
+def update_patient(patient_id: str, updates: dict) -> dict | None:
+    row_idx = _find_row_index("Patients", "id", patient_id)
+    if row_idx is None:
+        return None
+    patients = _read_all("Patients")
+    for p in patients:
+        if p.get("id") == patient_id:
+            p.update(updates)
+            _update_row("Patients", row_idx, p)
+            return p
+    return None
+
+
+def delete_patient(patient_id: str) -> bool:
+    row_idx = _find_row_index("Patients", "id", patient_id)
+    if row_idx is None:
+        return False
+    ws = _get_worksheet("Patients")
+    ws.delete_rows(row_idx)
+    _invalidate_cache("Patients")
+    return True
+
+
+# --- Appointments ---
+
+def get_all_appointments(status: str | None = None) -> list[dict]:
+    appointments = _read_all("Appointments")
+    if status:
+        return [a for a in appointments if a.get("status") == status]
+    return appointments
+
+
+def get_appointments_for_provider(provider_id: str, date: str | None = None) -> list[dict]:
+    appointments = _read_all("Appointments")
+    result = [a for a in appointments if a.get("provider_id") == provider_id and a.get("status") == "scheduled"]
+    if date:
+        result = [a for a in result if a.get("date") == date]
+    return result
+
+
+def get_appointments_for_patient(patient_id: str) -> list[dict]:
+    appointments = _read_all("Appointments")
+    return [a for a in appointments if a.get("patient_id") == patient_id and a.get("status") == "scheduled"]
+
+
+def add_appointment(appointment_data: dict) -> dict:
+    appointments = _read_all("Appointments")
+    existing_ids = [a["id"] for a in appointments if "id" in a]
+    appointment_data["id"] = _generate_id("appt", existing_ids)
+    appointment_data["created_at"] = datetime.now().isoformat()
+    appointment_data.setdefault("status", "scheduled")
+    _append_row("Appointments", appointment_data)
+    return appointment_data
+
+
+def update_appointment(appointment_id: str, updates: dict) -> dict | None:
+    row_idx = _find_row_index("Appointments", "id", appointment_id)
+    if row_idx is None:
+        return None
+    appointments = _read_all("Appointments")
+    for a in appointments:
+        if a.get("id") == appointment_id:
+            a.update(updates)
+            _update_row("Appointments", row_idx, a)
+            return a
+    return None
+
+
+def cancel_appointment(appointment_id: str) -> dict | None:
+    return update_appointment(appointment_id, {"status": "cancelled", "cancelled_at": datetime.now().isoformat()})
+
+
+def complete_appointment(appointment_id: str) -> dict | None:
+    return update_appointment(appointment_id, {"status": "completed", "completed_at": datetime.now().isoformat()})
+
+
+# --- Audit Log ---
+
+def log_action(user: str, action: str, details: str, appointment_id: str | None = None) -> None:
+    entry = {
+        "timestamp": datetime.now().isoformat(),
+        "user": user,
+        "action": action,
+        "details": details,
+        "appointment_id": appointment_id or "",
+    }
+    _append_row("AuditLog", entry)
+
+
+def get_audit_log(limit: int = 100) -> list[dict]:
+    log = _read_all("AuditLog")
+    log.sort(key=lambda x: x.get("timestamp", ""), reverse=True)
+    return log[:limit]

core/google_services.py

@@ -0,0 +1,484 @@
+"""
+Google Services — Calendar, Maps, and Gmail integrations.
+"""
+import os
+import base64
+import json
+import math
+import uuid
+from datetime import datetime, timedelta
+from email.mime.text import MIMEText
+from email.mime.multipart import MIMEMultipart
+from email.mime.base import MIMEBase
+from email import encoders
+
+from google.oauth2 import service_account
+from google.oauth2.credentials import Credentials
+from googleapiclient.discovery import build
+import googlemaps
+
+import config
+from core import settings_manager as settings
+
+
+def get_secret(key: str) -> str:
+    """Retrieve a secret from environment variables."""
+    return os.environ.get(key)
+
+
+# ============================================================
+# Google Calendar
+# ============================================================
+
+def get_calendar_service():
+    """Initialize and return a Google Calendar API service client.
+
+    Uses GOOGLE_CALENDAR_CREDENTIALS from secrets (base64-encoded service account JSON).
+    """
+    credentials_b64 = get_secret("GOOGLE_CALENDAR_CREDENTIALS")
+    credentials_json = base64.b64decode(credentials_b64).decode("utf-8")
+    credentials_info = json.loads(credentials_json)
+
+    credentials = service_account.Credentials.from_service_account_info(
+        credentials_info,
+        scopes=["https://www.googleapis.com/auth/calendar"]
+    )
+
+    service = build("calendar", "v3", credentials=credentials)
+    return service
+
+def create_calendar_event(summary: str, description: str, location: str, start_datetime: str, end_datetime: str) -> str:
+    """Create an event on the shared Google Calendar.
+
+    Args:
+        summary: Event title, e.g., "[Level 1] Robert Williams — John Moustoukas, MD"
+        description: Event details (addresses, contact info)
+        location: Visit address
+        start_datetime: ISO format datetime string
+        end_datetime: ISO format datetime string
+
+    Returns:
+        The created event's Google Calendar event ID
+    """
+    service = get_calendar_service()
+    calendar_id = get_secret("SHARED_CALENDAR_ID")
+
+    event = {
+        "summary": summary,
+        "description": description,
+        "location": location,
+        "start": {
+            "dateTime": start_datetime,
+            "timeZone": settings.get_timezone(),
+        },
+        "end": {
+            "dateTime": end_datetime,
+            "timeZone": settings.get_timezone(),
+        },
+    }
+
+    created_event = service.events().insert(calendarId=calendar_id, body=event).execute()
+    return created_event["id"]
+
+def delete_calendar_event(event_id: str) -> bool:
+    """Delete an event from the shared Google Calendar.
+
+    Returns True if successful.
+    """
+    try:
+        service = get_calendar_service()
+        calendar_id = get_secret("SHARED_CALENDAR_ID")
+        service.events().delete(calendarId=calendar_id, eventId=event_id).execute()
+        return True
+    except Exception:
+        return False
+
+def get_calendar_events(date: str) -> list[dict]:
+    """Fetch all events from the shared calendar for a given date (YYYY-MM-DD).
+
+    Returns list of event dicts with 'summary', 'start', 'end', 'id'.
+    """
+    service = get_calendar_service()
+    calendar_id = get_secret("SHARED_CALENDAR_ID")
+
+    # Create time bounds for the given date
+    date_obj = datetime.strptime(date, "%Y-%m-%d")
+    time_min = date_obj.isoformat()+"Z"# + "T00:00:00Z" claude messed up here
+    time_max = (date_obj + timedelta(days=1)).isoformat()+"Z"# + "T00:00:00Z"
+    print(time_min, time_max)
+
+    events_result = service.events().list(
+        calendarId=calendar_id,
+        timeMin=time_min,
+        timeMax=time_max,
+        singleEvents=True,
+        orderBy="startTime"
+    ).execute()
+
+    events = events_result.get("items", [])
+
+    return [
+        {
+            "id": event["id"],
+            "summary": event.get("summary", ""),
+            "start": event["start"].get("dateTime", event["start"].get("date")),
+            "end": event["end"].get("dateTime", event["end"].get("date")),
+        }
+        for event in events
+    ]
+
+
+# ============================================================
+# Google Maps
+# ============================================================
+
+def get_maps_client():
+    """Initialize and return a Google Maps client.
+
+    Uses GOOGLE_MAPS_API_KEY from secrets.
+    """
+    return googlemaps.Client(key=get_secret("GOOGLE_MAPS_API_KEY"))
+
+def calculate_travel_time(origin_address: str, destination_address: str, arrival_by: datetime) -> dict:
+    """Calculate driving travel time between two addresses using traffic-aware two-pass estimation.
+
+    Pass 1: Get rough travel duration (no departure_time).
+    Pass 2: Estimate departure = arrival_by - rough duration, then re-query with departure_time
+             to get duration_in_traffic.
+    Final recommended departure = arrival_by - traffic-aware duration.
+
+    Args:
+        origin_address: Full address string
+        destination_address: Full address string
+        arrival_by: When the provider must arrive (appointment start datetime)
+
+    Returns:
+        Dict with 'travel_minutes' (int) and 'recommended_departure' (datetime).
+        Returns travel_minutes=0 if same address.
+        Returns travel_minutes=-1 if the API call fails.
+    """
+    if origin_address.strip().lower() == destination_address.strip().lower():
+        return {"travel_minutes": 0, "recommended_departure": arrival_by}
+
+    try:
+        client = get_maps_client()
+
+        # Pass 1: rough estimate (no traffic)
+        result = client.distance_matrix(
+            origins=[origin_address],
+            destinations=[destination_address],
+            mode="driving"
+        )
+        element = result["rows"][0]["elements"][0]
+        if element["status"] != "OK":
+            return {"travel_minutes": -1, "recommended_departure": arrival_by}
+
+        rough_seconds = element["duration"]["value"]
+        rough_minutes = math.ceil(rough_seconds / 60)
+        rough_departure = arrival_by - timedelta(minutes=rough_minutes)
+
+        # Pass 2: traffic-aware estimate using rough departure time
+        result = client.distance_matrix(
+            origins=[origin_address],
+            destinations=[destination_address],
+            mode="driving",
+            departure_time=rough_departure
+        )
+        element = result["rows"][0]["elements"][0]
+        if element["status"] != "OK":
+            return {"travel_minutes": rough_minutes, "recommended_departure": arrival_by - timedelta(minutes=rough_minutes)}
+
+        traffic_seconds = element.get("duration_in_traffic", element["duration"])["value"]
+        traffic_minutes = math.ceil(traffic_seconds / 60)
+        recommended_departure = arrival_by - timedelta(minutes=traffic_minutes)
+
+        return {"travel_minutes": traffic_minutes, "recommended_departure": recommended_departure}
+    except Exception:
+        return {"travel_minutes": -1, "recommended_departure": arrival_by}
+
+def geocode_address(address: str) -> tuple[float, float] | None:
+    """Convert an address string to (latitude, longitude).
+
+    Returns None if geocoding fails.
+    """
+    try:
+        client = get_maps_client()
+        result = client.geocode(address)
+
+        if not result:
+            return None
+
+        location = result[0]["geometry"]["location"]
+        return (location["lat"], location["lng"])
+    except Exception:
+        return None
+
+def calculate_travel_times_batch(origin: str, destinations: list[str], arrival_by: datetime) -> list[dict]:
+    """Calculate travel times from one origin to multiple destinations using traffic-aware two-pass estimation.
+
+    Pass 1: Get rough durations for all destinations (no departure_time).
+    Pass 2: Use the max rough duration to compute a single departure_time for the batch,
+             then re-query to get duration_in_traffic per destination.
+
+    Returns a list of dicts with 'travel_minutes' and 'recommended_departure', in the same order as destinations.
+    """
+    if not destinations:
+        return []
+
+    try:
+        client = get_maps_client()
+
+        # Pass 1: rough estimates (no traffic)
+        result = client.distance_matrix(
+            origins=[origin],
+            destinations=destinations,
+            mode="driving"
+        )
+
+        rough_seconds_list = []
+        for element in result["rows"][0]["elements"]:
+            if element["status"] == "OK":
+                rough_seconds_list.append(element["duration"]["value"])
+            else:
+                rough_seconds_list.append(-1)
+
+        # Use max rough duration to compute a single departure_time for the batch
+        valid_seconds = [s for s in rough_seconds_list if s >= 0]
+        if not valid_seconds:
+            return [{"travel_minutes": -1, "recommended_departure": arrival_by} for _ in destinations]
+
+        max_rough_minutes = math.ceil(max(valid_seconds) / 60)
+        rough_departure = arrival_by - timedelta(minutes=max_rough_minutes)
+
+        # Pass 2: traffic-aware estimates
+        result = client.distance_matrix(
+            origins=[origin],
+            destinations=destinations,
+            mode="driving",
+            departure_time=rough_departure
+        )
+
+        travel_results = []
+        for element in result["rows"][0]["elements"]:
+            if element["status"] == "OK":
+                traffic_seconds = element.get("duration_in_traffic", element["duration"])["value"]
+                traffic_minutes = math.ceil(traffic_seconds / 60)
+                travel_results.append({
+                    "travel_minutes": traffic_minutes,
+                    "recommended_departure": arrival_by - timedelta(minutes=traffic_minutes),
+                })
+            else:
+                travel_results.append({"travel_minutes": -1, "recommended_departure": arrival_by})
+
+        return travel_results
+    except Exception:
+        return [{"travel_minutes": -1, "recommended_departure": arrival_by} for _ in destinations]
+
+
+# ============================================================
+# Gmail
+# ============================================================
+
+def _build_ics(appointment_details: dict, method: str = "REQUEST") -> str:
+    """Build an .ics calendar string from appointment details.
+
+    Args:
+        appointment_details: Dict with date, start_time, end_time, patient_name,
+                             provider_name, address.
+        method: VCALENDAR METHOD — "REQUEST" for new/updated, "CANCEL" for cancellations.
+    """
+    appt_date = appointment_details.get("date", "")
+    start_time = appointment_details.get("start_time", "00:00")
+    end_time = appointment_details.get("end_time", "00:00")
+    patient_name = appointment_details.get("patient_name", "")
+    provider_name = appointment_details.get("provider_name", "")
+    address = appointment_details.get("address", "")
+
+    dt_start = datetime.strptime(f"{appt_date} {start_time}", "%Y-%m-%d %H:%M")
+    dt_end = datetime.strptime(f"{appt_date} {end_time}", "%Y-%m-%d %H:%M")
+    now = datetime.utcnow()
+
+    uid = uuid.uuid5(uuid.NAMESPACE_URL, f"{appt_date}-{start_time}-{patient_name}-{provider_name}")
+
+    return (
+        "BEGIN:VCALENDAR\r\n"
+        "VERSION:2.0\r\n"
+        "PRODID:-//SOS Care Now//Scheduling//EN\r\n"
+        f"METHOD:{method}\r\n"
+        "BEGIN:VEVENT\r\n"
+        f"UID:{uid}\r\n"
+        f"DTSTAMP:{now:%Y%m%dT%H%M%SZ}\r\n"
+        f"DTSTART;TZID={settings.get_timezone()}:{dt_start:%Y%m%dT%H%M%S}\r\n"
+        f"DTEND;TZID={settings.get_timezone()}:{dt_end:%Y%m%dT%H%M%S}\r\n"
+        f"SUMMARY:{config.ORG_NAME} — {patient_name} with {provider_name}\r\n"
+        f"LOCATION:{address}\r\n"
+        f"STATUS:{'CANCELLED' if method == 'CANCEL' else 'CONFIRMED'}\r\n"
+        "END:VEVENT\r\n"
+        "END:VCALENDAR\r\n"
+    )
+
+
+def get_gmail_service():
+    """Initialize and return a Gmail API service client.
+
+    Uses GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, and GMAIL_REFRESH_TOKEN from
+    secrets. The refresh token is exchanged for a short-lived access token by
+    the underlying google-auth library on each request.
+    """
+    creds = Credentials.from_authorized_user_info(
+        {
+            "client_id": get_secret("GMAIL_CLIENT_ID"),
+            "client_secret": get_secret("GMAIL_CLIENT_SECRET"),
+            "refresh_token": get_secret("GMAIL_REFRESH_TOKEN"),
+        },
+        scopes=["https://www.googleapis.com/auth/gmail.send"],
+    )
+    return build("gmail", "v1", credentials=creds, cache_discovery=False)
+
+
+def send_email(to_address: str, subject: str, body: str, ics_content: str | None = None) -> bool:
+    """Send an email via the Gmail API.
+
+    Uses GMAIL_ADDRESS as the From header and the OAuth credentials in
+    GMAIL_CLIENT_ID / GMAIL_CLIENT_SECRET / GMAIL_REFRESH_TOKEN.
+    If ics_content is provided, attaches it as a .ics calendar invite.
+
+    Returns True if sent successfully.
+    """
+    try:
+        gmail_address = get_secret("GMAIL_ADDRESS")
+
+        message = MIMEMultipart()
+        message["From"] = gmail_address
+        message["To"] = to_address
+        message["Subject"] = subject
+        message.attach(MIMEText(body, "plain"))
+
+        if ics_content:
+            ics_part = MIMEBase("text", "calendar", method="REQUEST", name="invite.ics")
+            ics_part.set_payload(ics_content.encode("utf-8"))
+            encoders.encode_base64(ics_part)
+            ics_part.add_header("Content-Disposition", "attachment", filename="invite.ics")
+            message.attach(ics_part)
+
+        raw = base64.urlsafe_b64encode(message.as_bytes()).decode("utf-8")
+        service = get_gmail_service()
+        service.users().messages().send(userId="me", body={"raw": raw}).execute()
+
+        return True
+    except Exception:
+        return False
+
+def send_scheduling_notification(provider_email: str, patient_email: str, appointment_details: dict) -> dict:
+    """Send scheduling confirmation emails to both the provider and patient.
+
+    Args:
+        provider_email: Provider's email
+        patient_email: Patient's email
+        appointment_details: Dict with keys: patient_name, provider_name, date, start_time, end_time, visit_level, address
+
+    Returns:
+        Dict with 'provider_sent': bool, 'patient_sent': bool
+    """
+    patient_name = appointment_details.get("patient_name", "Patient")
+    provider_name = appointment_details.get("provider_name", "Provider")
+    date = appointment_details.get("date", "")
+    start_time = appointment_details.get("start_time", "")
+    end_time = appointment_details.get("end_time", "")
+    visit_level = appointment_details.get("visit_level", "")
+    address = appointment_details.get("address", "")
+    recommended_departure = appointment_details.get("recommended_departure_time", "")
+
+    # Email to provider
+    provider_subject = f"{config.ORG_NAME} - New Appointment Scheduled"
+    departure_line = f"\nRecommended Departure Time: {recommended_departure}" if recommended_departure else ""
+    provider_body = f"""Hello {provider_name},
+
+A new appointment has been scheduled:
+
+Patient: {patient_name}
+Date: {date}
+Time: {start_time} - {end_time}
+Visit Level: {visit_level}
+Address: {address}{departure_line}
+
+Please ensure you arrive on time.
+
+Best regards,
+{config.ORG_NAME}
+"""
+
+    # Email to patient
+    patient_subject = f"{config.ORG_NAME} - Appointment Confirmation"
+    patient_body = f"""Hello {patient_name},
+
+Your appointment has been confirmed:
+
+Provider: {provider_name}
+Date: {date}
+Time: {start_time} - {end_time}
+
+Your provider will visit you at:
+{address}
+
+If you need to reschedule or cancel, please contact us as soon as possible.
+
+Best regards,
+{config.ORG_NAME}
+"""
+
+    ics = _build_ics(appointment_details)
+    provider_sent = send_email(provider_email, provider_subject, provider_body, ics) if provider_email else False
+    patient_sent = send_email(patient_email, patient_subject, patient_body, ics) if patient_email else False
+
+    return {"provider_sent": provider_sent, "patient_sent": patient_sent}
+
+def send_cancellation_notification(provider_email: str, patient_email: str, appointment_details: dict) -> dict:
+    """Send cancellation notification emails to both the provider and patient.
+
+    Returns:
+        Dict with 'provider_sent': bool, 'patient_sent': bool
+    """
+    patient_name = appointment_details.get("patient_name", "Patient")
+    provider_name = appointment_details.get("provider_name", "Provider")
+    date = appointment_details.get("date", "")
+    start_time = appointment_details.get("start_time", "")
+    end_time = appointment_details.get("end_time", "")
+
+    # Email to provider
+    provider_subject = f"{config.ORG_NAME} - Appointment Cancelled"
+    provider_body = f"""Hello {provider_name},
+
+The following appointment has been cancelled:
+
+Patient: {patient_name}
+Date: {date}
+Time: {start_time} - {end_time}
+
+This time slot is now available for other appointments.
+
+Best regards,
+{config.ORG_NAME}
+"""
+
+    # Email to patient
+    patient_subject = f"{config.ORG_NAME} - Appointment Cancellation Confirmation"
+    patient_body = f"""Hello {patient_name},
+
+Your appointment has been cancelled:
+
+Provider: {provider_name}
+Date: {date}
+Time: {start_time} - {end_time}
+
+If you would like to reschedule, please contact us.
+
+Best regards,
+{config.ORG_NAME}
+"""
+
+    ics = _build_ics(appointment_details, method="CANCEL")
+    provider_sent = send_email(provider_email, provider_subject, provider_body, ics) if provider_email else False
+    patient_sent = send_email(patient_email, patient_subject, patient_body, ics) if patient_email else False
+
+    return {"provider_sent": provider_sent, "patient_sent": patient_sent}

core/scheduling_engine.py

@@ -0,0 +1,249 @@
+"""
+Scheduling Engine — Deterministic logic for availability checking,
+overlap prevention, and provider ranking.
+
+This module contains NO LLM calls. All logic is pure Python.
+"""
+from datetime import datetime, timedelta
+from zoneinfo import ZoneInfo
+from config import DEFAULT_WORK_HOURS, DEFAULT_LUNCH_BREAK
+from core import settings_manager as settings
+
+
+# --- Time utility helpers ---
+
+def parse_time(time_str: str) -> datetime:
+    """Parse a time string to a datetime (date portion ignored).
+
+    Accepts 'HH:MM', 'H:MM', or 'HHMM' (e.g. '0700').
+    """
+    s = str(time_str).strip()
+    for fmt in ("%H:%M", "%H%M"):
+        try:
+            return datetime.strptime(s, fmt)
+        except ValueError:
+            continue
+    raise ValueError(f"Unrecognized time format: {time_str!r}")
+
+
+def normalize_time_str(time_str: str) -> str | None:
+    """Normalize a user-entered time string to 'HH:MM'. Returns None if invalid."""
+    if time_str is None:
+        return None
+    try:
+        return parse_time(time_str).strftime("%H:%M")
+    except ValueError:
+        return None
+
+def times_overlap(start1: str, end1: str, start2: str, end2: str) -> bool:
+    """Check if two time ranges overlap. All args in 'HH:MM' format."""
+    s1, e1 = parse_time(start1), parse_time(end1)
+    s2, e2 = parse_time(start2), parse_time(end2)
+    return s1 < e2 and s2 < e1
+
+def add_minutes(time_str: str, minutes: int) -> str:
+    """Add minutes to a time string. Returns 'HH:MM'."""
+    result = parse_time(time_str) + timedelta(minutes=minutes)
+    return result.strftime("%H:%M")
+
+
+# --- Visit duration helpers ---
+
+def get_visit_duration(visit_level: int | str) -> int:
+    """Return the duration in minutes for a given visit level."""
+    return settings.get_visit_levels()[visit_level]["duration_minutes"]
+
+def get_total_block_duration(visit_level: int | str) -> int:
+    """Return visit duration + buffer in minutes."""
+    return get_visit_duration(visit_level) + settings.get_buffer_minutes()
+
+
+# --- Availability checks ---
+
+def is_within_work_hours(provider: dict, start_time: str, end_time: str) -> bool:
+    """Check if a proposed time slot falls within the provider's work hours.
+
+    Args:
+        provider: Provider dict with 'work_hours' field
+        start_time: "HH:MM" format
+        end_time: "HH:MM" format
+    """
+    work = provider.get("work_hours", DEFAULT_WORK_HOURS)
+    return (
+        parse_time(start_time) >= parse_time(work["start"])
+        and parse_time(end_time) <= parse_time(work["end"])
+    )
+
+def conflicts_with_lunch(provider: dict, start_time: str, end_time: str) -> bool:
+    """Check if a proposed time slot overlaps with the provider's lunch break.
+
+    An empty or missing lunch break (e.g. {"start": "", "end": ""}) is treated
+    as "no lunch break" — returns False.
+    """
+    lunch = provider.get("lunch_break") or DEFAULT_LUNCH_BREAK
+    lunch_start = normalize_time_str(lunch.get("start"))
+    lunch_end = normalize_time_str(lunch.get("end"))
+    if not lunch_start or not lunch_end:
+        return False
+    return times_overlap(start_time, end_time, lunch_start, lunch_end)
+
+def has_overlap(existing_appointments: list[dict], proposed_start: str, proposed_end: str, travel_time_to: int = 0, travel_time_from: int = 0) -> bool:
+    """Check if a proposed slot overlaps with any existing appointment, accounting for buffer and travel times.
+
+    For each existing appointment, the blocked window is:
+        [appt_start - travel_time_to, appt_end + BUFFER_MINUTES + travel_time_from]
+
+    Args:
+        existing_appointments: List of appointment dicts for the provider on that date
+        proposed_start: "HH:MM" format
+        proposed_end: "HH:MM" format
+        travel_time_to: Minutes of travel to the existing appointment
+        travel_time_from: Minutes of travel from the existing appointment
+    """
+    buffer = settings.get_buffer_minutes()
+    for appt in existing_appointments:
+        blocked_start = add_minutes(appt["start_time"], -travel_time_to)
+        blocked_end = add_minutes(appt["end_time"], buffer + travel_time_from)
+        if times_overlap(proposed_start, proposed_end, blocked_start, blocked_end):
+            return True
+    return False
+
+def is_oncall_for_slot(provider: dict, date: str, start_time: str, end_time: str) -> bool:
+    """Return True if the slot [date+start_time, date+end_time] falls within one of
+    the provider's 24-hour on-call windows (07:00 of an on-call date → 07:00 the next day)."""
+    on_call_dates = provider.get("on_call", []) or []
+    if not on_call_dates:
+        return False
+    try:
+        slot_start = datetime.strptime(f"{date} {start_time}", "%Y-%m-%d %H:%M")
+        slot_end = datetime.strptime(f"{date} {end_time}", "%Y-%m-%d %H:%M")
+    except ValueError:
+        return False
+    on_call_start_hour = settings.get_on_call_start_hour()
+    for d in on_call_dates:
+        try:
+            window_start = datetime.strptime(f"{d} {on_call_start_hour}", "%Y-%m-%d %H:%M")
+        except ValueError:
+            continue
+        window_end = window_start + timedelta(hours=24)
+        if slot_start >= window_start and slot_end <= window_end:
+            return True
+    return False
+
+
+def is_provider_available(provider: dict, date: str, start_time: str, visit_level: int | str, existing_appointments: list[dict]) -> bool:
+    """Master check: is this provider available for a visit at the given date/time?
+
+    Checks:
+        1. Provider is active
+        2. Date is not in provider's days_off
+        3. Date's weekday is not in provider's recurring_days_off
+        4. Provider supports the visit_level
+        5. Slot is within work hours
+        6. Slot doesn't conflict with lunch
+        7. No overlap with existing appointments (including buffer)
+        8. Meets 24-hour lead time requirement
+
+    Returns True if all checks pass.
+    """
+    # 1. Active
+    if not provider.get("active", True):
+        return False
+
+    duration = get_visit_duration(visit_level)
+    end_time = add_minutes(start_time, duration)
+
+    # On-call window supersedes days off, recurring days off, work hours,
+    # and lunch break — but NOT the lead-time rule, which always applies.
+    on_call = is_oncall_for_slot(provider, date, start_time, end_time)
+
+    if not on_call:
+        # 2. Specific date/time off
+        for off in provider.get("days_off", []):
+            if isinstance(off, str):
+                # Legacy format: plain date string = all day off
+                if date == off:
+                    return False
+            elif isinstance(off, dict) and off.get("date") == date:
+                if off.get("all_day", True):
+                    return False
+                # Specific time block off — check overlap
+                off_start = off.get("start_time")
+                off_end = off.get("end_time")
+                if off_start and off_end and times_overlap(start_time, end_time, off_start, off_end):
+                    return False
+
+        # 3. Recurring day off (e.g., every Friday)
+        weekday = datetime.strptime(date, "%Y-%m-%d").strftime("%A")
+        if weekday in provider.get("recurring_days_off", []):
+            return False
+
+    # 4. Supports the requested visit level
+    if visit_level not in provider.get("service_levels", []):
+        return False
+
+    if not on_call:
+        # 5. Within work hours
+        if not is_within_work_hours(provider, start_time, end_time):
+            return False
+
+        # 6. No lunch conflict
+        if conflicts_with_lunch(provider, start_time, end_time):
+            return False
+
+    # 7. No overlap with existing appointments
+    if has_overlap(existing_appointments, start_time, end_time):
+        return False
+
+    # 8. Lead-time rule — always applies, even for on-call providers.
+    # Compare in the configured timezone so a UTC server doesn't mis-evaluate local times.
+    proposed_dt = datetime.strptime(f"{date} {start_time}", "%Y-%m-%d %H:%M")
+    now_local = datetime.now(ZoneInfo(settings.get_timezone())).replace(tzinfo=None)
+    if proposed_dt < now_local + timedelta(hours=settings.get_min_lead_time_hours()):
+        return False
+
+    return True
+
+def get_available_providers(all_providers: list[dict], date: str, start_time: str, visit_level: int | str, appointments_by_provider: dict[str, list[dict]]) -> list[dict]:
+    """Filter all providers down to those available for the proposed visit.
+
+    Args:
+        all_providers: List of all provider dicts
+        date: "YYYY-MM-DD"
+        start_time: "HH:MM"
+        visit_level: Visit level (1, 2, 3, or "Nurse")
+        appointments_by_provider: Dict mapping provider_id -> list of their appointments on that date
+
+    Returns:
+        List of available provider dicts
+    """
+    available = []
+    for provider in all_providers:
+        existing = appointments_by_provider.get(provider["id"], [])
+        if is_provider_available(provider, date, start_time, visit_level, existing):
+            available.append(provider)
+    return available
+
+def rank_providers_by_travel(providers_with_travel: list[dict]) -> list[dict]:
+    """Sort providers by travel time (ascending). Boost providers who already have visits in the same area.
+
+    Each dict in the input list should have:
+        - All standard provider fields
+        - 'travel_time_minutes': int (travel time to the patient)
+        - 'has_nearby_visits': bool (True if provider has other visits nearby that day)
+
+    Ranking logic:
+        - Primary sort: is_oncall (True first — travel time is ignored)
+        - Secondary sort: has_nearby_visits (True first)
+        - Tertiary sort: travel_time_minutes (ascending)
+
+    Returns the sorted list.
+    """
+    return sorted(
+        providers_with_travel,
+        key=lambda p: (
+            not p.get("is_oncall", False),
+            not p.get("has_nearby_visits", False),
+            p.get("travel_time_minutes", 0),
+        ),
+    )

core/settings_manager.py

@@ -0,0 +1,169 @@
+"""
+Settings Manager — runtime-configurable values persisted in a "Settings" worksheet.
+
+Each setting is a (key, value) row. Complex values (e.g. visit_levels) are JSON-encoded.
+Reads are cached for a short TTL to avoid hammering the Google Sheets API. Defaults
+fall back to the constants in `config.py`.
+"""
+import json
+import time
+import threading
+from typing import Any
+
+import config
+from core import data_manager
+
+
+_SETTINGS_WORKSHEET = "Settings"
+_CACHE_TTL_SECONDS = 30
+
+_lock = threading.RLock()
+_cache: dict = {"timestamp": 0.0, "values": {}}
+
+
+# Schema:
+#   key -> (default_value, json_encoded?, type_hint)
+# type_hint is used to coerce the string-cell value back to the right Python type.
+_SCHEMA: dict[str, tuple] = {
+    "min_lead_time_hours":  (config.MIN_LEAD_TIME_HOURS, False, int),
+    "buffer_minutes":       (config.BUFFER_MINUTES,      False, int),
+    "visit_levels":         (config.VISIT_LEVELS,        True,  "visit_levels"),
+    "on_call_start_hour":   ("07:00",                    False, str),
+    "region_name":          (config.REGION_NAME,         False, str),
+    "timezone":             (config.TIMEZONE,            False, str),
+    "service_area":         (config.SERVICE_AREA,        False, str),
+    "openai_model":         (config.OPENAI_MODEL,        False, str),
+}
+
+
+def _ensure_settings_worksheet() -> None:
+    """Create the Settings worksheet on first use if it doesn't exist."""
+    try:
+        data_manager._get_worksheet(_SETTINGS_WORKSHEET)
+        data_manager._ensure_columns(_SETTINGS_WORKSHEET, ["key", "value"])
+    except Exception:
+        # Worksheet doesn't exist — create it.
+        ss = data_manager._get_spreadsheet()
+        ws = ss.add_worksheet(title=_SETTINGS_WORKSHEET, rows=100, cols=2)
+        ws.update(values=[["key", "value"]], range_name="A1:B1", value_input_option="RAW")
+        # Bust caches so subsequent reads see the new worksheet.
+        with data_manager._lock:
+            data_manager._state["worksheets"].pop(_SETTINGS_WORKSHEET, None)
+            data_manager._state["headers"].pop(_SETTINGS_WORKSHEET, None)
+            data_manager._state["read_cache"].pop(_SETTINGS_WORKSHEET, None)
+
+
+def _read_all_settings() -> dict[str, str]:
+    """Return {key: raw_string_value} for everything in the Settings sheet.
+    Returns {} if the sheet doesn't exist yet (callers fall back to defaults).
+    """
+    try:
+        rows = data_manager._read_all(_SETTINGS_WORKSHEET)
+        return {str(r.get("key", "")): str(r.get("value", "")) for r in rows if r.get("key")}
+    except Exception:
+        return {}
+
+
+def _refresh_cache_if_stale() -> None:
+    with _lock:
+        if (time.time() - _cache["timestamp"]) < _CACHE_TTL_SECONDS:
+            return
+        _cache["values"] = _read_all_settings()
+        _cache["timestamp"] = time.time()
+
+
+def _coerce(raw: str, schema_entry: tuple) -> Any:
+    default, is_json, type_hint = schema_entry
+    if raw is None or raw == "":
+        return default
+    if is_json:
+        try:
+            parsed = json.loads(raw)
+        except Exception:
+            return default
+        if type_hint == "visit_levels" and isinstance(parsed, dict):
+            # JSON keys are always strings; rebuild int keys for visit levels.
+            return {
+                (int(k) if isinstance(k, str) and k.isdigit() else k): v
+                for k, v in parsed.items()
+            }
+        return parsed
+    if type_hint is int:
+        try:
+            return int(raw)
+        except Exception:
+            return default
+    if type_hint is float:
+        try:
+            return float(raw)
+        except Exception:
+            return default
+    return raw
+
+
+def get_setting(key: str, default: Any = None) -> Any:
+    """Return the current value for `key`. Falls back to schema default or `default`."""
+    schema = _SCHEMA.get(key)
+    if schema is None:
+        return default
+    _refresh_cache_if_stale()
+    raw = _cache["values"].get(key)
+    if raw is None or raw == "":
+        return schema[0] if default is None else default
+    return _coerce(raw, schema)
+
+
+def get_all_settings() -> dict[str, Any]:
+    """Return every known setting with its current effective value."""
+    return {k: get_setting(k) for k in _SCHEMA.keys()}
+
+
+def set_setting(key: str, value: Any) -> Any:
+    """Persist `value` for `key`. Returns the parsed-back value (after round-trip)."""
+    if key not in _SCHEMA:
+        raise KeyError(f"Unknown setting: {key}")
+    schema = _SCHEMA[key]
+    _, is_json, _ = schema
+
+    _ensure_settings_worksheet()
+
+    if is_json:
+        # Normalize: for visit_levels, ensure int durations stay int.
+        serialized = json.dumps(value)
+    elif value is None:
+        serialized = ""
+    elif isinstance(value, bool):
+        serialized = str(value)
+    else:
+        serialized = str(value)
+
+    row_idx = data_manager._find_row_index(_SETTINGS_WORKSHEET, "key", key)
+    payload = {"key": key, "value": serialized}
+    if row_idx:
+        data_manager._update_row(_SETTINGS_WORKSHEET, row_idx, payload)
+    else:
+        data_manager._append_row(_SETTINGS_WORKSHEET, payload)
+
+    # Invalidate cache so the next read sees the new value.
+    with _lock:
+        _cache["timestamp"] = 0.0
+
+    return get_setting(key)
+
+
+def get_schema_defaults() -> dict[str, Any]:
+    """Return the original config.py defaults for every setting (for "reset to default" UIs)."""
+    return {k: v[0] for k, v in _SCHEMA.items()}
+
+
+# --- Convenience accessors ---
+# These let consumers write `settings.get_min_lead_time_hours()` instead of magic strings.
+
+def get_min_lead_time_hours() -> int:    return get_setting("min_lead_time_hours")
+def get_buffer_minutes() -> int:         return get_setting("buffer_minutes")
+def get_visit_levels() -> dict:          return get_setting("visit_levels")
+def get_on_call_start_hour() -> str:     return get_setting("on_call_start_hour")
+def get_region_name() -> str:            return get_setting("region_name")
+def get_timezone() -> str:               return get_setting("timezone")
+def get_service_area() -> str:           return get_setting("service_area")
+def get_openai_model() -> str:           return get_setting("openai_model")

main.py

@@ -0,0 +1,55 @@
+"""
+SOS Care Now — Medical Scheduling Agent (HTML / FastAPI version).
+Single-page modern dashboard served from FastAPI.
+Run locally:   uvicorn main:app --host 0.0.0.0 --port 7860 --reload
+In Docker:     CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]
+"""
+from pathlib import Path
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.exceptions import HTTPException
+
+from api import auth as auth_routes
+from api import providers as providers_routes
+from api import patients as patients_routes
+from api import appointments as appointments_routes
+from api import schedule as schedule_routes
+from api import calendar as calendar_routes
+from api import audit as audit_routes
+from api import settings as settings_routes
+
+
+BASE_DIR = Path(__file__).resolve().parent
+
+app = FastAPI(title="SOS Care Now — Scheduling")
+
+
+@app.exception_handler(HTTPException)
+async def http_exception_handler(request: Request, exc: HTTPException):
+    return JSONResponse(status_code=exc.status_code, content={"detail": exc.detail})
+
+
+# API routers
+app.include_router(auth_routes.router)
+app.include_router(providers_routes.router)
+app.include_router(patients_routes.router)
+app.include_router(appointments_routes.router)
+app.include_router(schedule_routes.router)
+app.include_router(calendar_routes.router)
+app.include_router(audit_routes.router)
+app.include_router(settings_routes.router)
+
+
+# Static assets
+app.mount("/static", StaticFiles(directory=str(BASE_DIR / "static")), name="static")
+
+
+@app.get("/")
+def root():
+    return FileResponse(str(BASE_DIR / "templates" / "index.html"))
+
+
+@app.get("/healthz")
+def healthz():
+    return {"ok": True}

requirements.txt

@@ -0,0 +1,15 @@
+fastapi>=0.115.0
+uvicorn[standard]>=0.30.0
+pydantic>=2.0.0
+itsdangerous>=2.1.0
+python-multipart>=0.0.9
+langgraph>=0.2.0
+langchain>=0.3.0
+langchain-openai>=0.2.0
+google-api-python-client>=2.100.0
+google-auth>=2.23.0
+googlemaps>=4.10.0
+python-dateutil>=2.8.0
+gspread>=6.0.0
+google-auth-oauthlib>=1.2.0
+jinja2>=3.1.0

static/css/app.css

@@ -0,0 +1,275 @@
+/* SOS Care Now — Custom styles layered on top of Tailwind */
+
+:root {
+    --brand-50:  #eff6ff;
+    --brand-100: #dbeafe;
+    --brand-500: #3b82f6;
+    --brand-600: #2563eb;
+    --brand-700: #1d4ed8;
+    --brand-900: #1e3a8a;
+}
+
+html, body {
+    height: 100%;
+    background-color: #f8fafc;
+    font-family: 'Inter', system-ui, -apple-system, sans-serif;
+    color: #0f172a;
+}
+
+/* Sidebar */
+.sidebar {
+    background: linear-gradient(180deg, #0f172a 0%, #1e293b 100%);
+}
+
+.sidebar-link {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.625rem 1rem;
+    border-radius: 0.5rem;
+    color: #cbd5e1;
+    font-weight: 500;
+    transition: all 0.15s ease;
+    cursor: pointer;
+}
+.sidebar-link:hover {
+    background-color: rgba(255, 255, 255, 0.06);
+    color: #fff;
+}
+.sidebar-link.active {
+    background-color: var(--brand-600);
+    color: #fff;
+    box-shadow: 0 4px 14px -2px rgba(37, 99, 235, 0.6);
+}
+
+/* Cards */
+.card {
+    background: #fff;
+    border: 1px solid #e2e8f0;
+    border-radius: 1rem;
+    box-shadow: 0 1px 3px rgba(15, 23, 42, 0.04);
+}
+
+/* Inputs */
+.input, .select, textarea.input {
+    width: 100%;
+    padding: 0.5rem 0.75rem;
+    border: 1px solid #cbd5e1;
+    border-radius: 0.5rem;
+    background-color: #fff;
+    font-size: 0.875rem;
+    transition: border-color 0.15s ease, box-shadow 0.15s ease;
+}
+.input:focus, .select:focus, textarea.input:focus {
+    outline: none;
+    border-color: var(--brand-500);
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
+}
+
+/* Buttons */
+.btn {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: 0.5rem;
+    padding: 0.5rem 1rem;
+    border-radius: 0.5rem;
+    font-weight: 500;
+    font-size: 0.875rem;
+    transition: all 0.15s ease;
+    cursor: pointer;
+    border: 1px solid transparent;
+    white-space: nowrap;
+}
+.btn-primary {
+    background-color: var(--brand-600);
+    color: #fff;
+    box-shadow: 0 1px 2px rgba(15, 23, 42, 0.1);
+}
+.btn-primary:hover { background-color: var(--brand-700); }
+.btn-primary:disabled { background-color: #cbd5e1; cursor: not-allowed; }
+.btn-secondary {
+    background-color: #fff;
+    color: #0f172a;
+    border-color: #cbd5e1;
+}
+.btn-secondary:hover { background-color: #f1f5f9; }
+.btn-danger {
+    background-color: #dc2626;
+    color: #fff;
+}
+.btn-danger:hover { background-color: #b91c1c; }
+.btn-ghost {
+    background-color: transparent;
+    color: #64748b;
+}
+.btn-ghost:hover { background-color: #f1f5f9; color: #0f172a; }
+.btn-sm { padding: 0.25rem 0.625rem; font-size: 0.8125rem; }
+
+/* Tables */
+.table-wrap {
+    overflow-x: auto;
+    border-radius: 0.75rem;
+}
+.table {
+    width: 100%;
+    border-collapse: collapse;
+}
+.table th {
+    text-align: left;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    color: #64748b;
+    padding: 0.75rem 1rem;
+    background-color: #f8fafc;
+    border-bottom: 1px solid #e2e8f0;
+}
+.table td {
+    padding: 0.75rem 1rem;
+    font-size: 0.875rem;
+    border-bottom: 1px solid #f1f5f9;
+}
+.table tr:last-child td { border-bottom: none; }
+.table tbody tr:hover { background-color: #fafbfc; }
+
+/* Badges */
+.badge {
+    display: inline-flex;
+    align-items: center;
+    padding: 0.125rem 0.625rem;
+    border-radius: 9999px;
+    font-size: 0.75rem;
+    font-weight: 600;
+}
+.badge-green { background-color: #dcfce7; color: #166534; }
+.badge-blue { background-color: #dbeafe; color: #1d4ed8; }
+.badge-red { background-color: #fee2e2; color: #991b1b; }
+.badge-amber { background-color: #fef3c7; color: #92400e; }
+.badge-slate { background-color: #e2e8f0; color: #334155; }
+.badge-emerald { background-color: #d1fae5; color: #065f46; }
+
+/* Toggle (on-call switch) */
+.toggle {
+    position: relative;
+    width: 44px;
+    height: 24px;
+    background-color: #cbd5e1;
+    border-radius: 9999px;
+    cursor: pointer;
+    transition: background-color 0.2s ease;
+    flex-shrink: 0;
+}
+.toggle::after {
+    content: "";
+    position: absolute;
+    top: 2px;
+    left: 2px;
+    width: 20px;
+    height: 20px;
+    background-color: #fff;
+    border-radius: 9999px;
+    box-shadow: 0 1px 2px rgba(0, 0, 0, 0.2);
+    transition: transform 0.2s ease;
+}
+.toggle.on {
+    background-color: #10b981;
+}
+.toggle.on::after {
+    transform: translateX(20px);
+}
+
+/* Modal */
+.modal-backdrop {
+    position: fixed;
+    inset: 0;
+    background-color: rgba(15, 23, 42, 0.5);
+    backdrop-filter: blur(2px);
+    z-index: 50;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 1rem;
+}
+.modal {
+    background-color: #fff;
+    border-radius: 1rem;
+    max-width: 720px;
+    width: 100%;
+    max-height: 90vh;
+    overflow-y: auto;
+    box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+}
+
+/* Stat tile */
+.stat {
+    padding: 1.25rem;
+    background: #fff;
+    border: 1px solid #e2e8f0;
+    border-radius: 1rem;
+}
+.stat-label { font-size: 0.75rem; font-weight: 600; color: #64748b; text-transform: uppercase; letter-spacing: 0.05em; }
+.stat-value { font-size: 1.875rem; font-weight: 700; color: #0f172a; margin-top: 0.25rem; }
+
+/* Calendar custom event styles */
+.fc-event { cursor: pointer; }
+.event-travel { opacity: 0.55; }
+.event-completed { opacity: 0.65; }
+.event-completed .fc-event-title { text-decoration: line-through; }
+
+/* Match card */
+.match-card {
+    border: 1px solid #e2e8f0;
+    border-radius: 0.75rem;
+    padding: 1rem;
+    background: #fff;
+    transition: all 0.15s ease;
+    cursor: pointer;
+}
+.match-card:hover {
+    border-color: var(--brand-500);
+    box-shadow: 0 4px 12px -2px rgba(59, 130, 246, 0.15);
+}
+.match-card.selected {
+    border-color: var(--brand-600);
+    background: linear-gradient(180deg, #eff6ff 0%, #fff 30%);
+    box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.15);
+}
+
+/* Toast */
+.toast {
+    position: fixed;
+    bottom: 1.5rem;
+    right: 1.5rem;
+    z-index: 100;
+    padding: 0.875rem 1.25rem;
+    border-radius: 0.75rem;
+    color: #fff;
+    box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
+    font-weight: 500;
+    font-size: 0.875rem;
+    max-width: 420px;
+}
+.toast-success { background-color: #16a34a; }
+.toast-error { background-color: #dc2626; }
+.toast-info { background-color: #0f172a; }
+
+/* Loader */
+.spinner {
+    width: 1.25rem;
+    height: 1.25rem;
+    border: 2px solid #e2e8f0;
+    border-top-color: var(--brand-600);
+    border-radius: 50%;
+    animation: spin 0.6s linear infinite;
+    display: inline-block;
+}
+@keyframes spin { to { transform: rotate(360deg); } }
+
+[x-cloak] { display: none !important; }
+
+/* Login */
+.login-bg {
+    background: linear-gradient(135deg, #1e3a8a 0%, #3b82f6 50%, #06b6d4 100%);
+}

static/js/api.js

@@ -0,0 +1,60 @@
+// Thin wrapper around fetch — JSON in, JSON out. Throws on non-2xx.
+async function api(method, url, body) {
+    const opts = {
+        method,
+        headers: { "Content-Type": "application/json" },
+        credentials: "same-origin",
+    };
+    if (body !== undefined) opts.body = JSON.stringify(body);
+    const r = await fetch(url, opts);
+    let payload = null;
+    try { payload = await r.json(); } catch (_) { /* no body */ }
+    if (!r.ok) {
+        const msg = payload && payload.detail ? payload.detail : `Request failed (${r.status})`;
+        throw new Error(msg);
+    }
+    return payload;
+}
+
+window.API = {
+    get:    (u)    => api("GET", u),
+    post:   (u, b) => api("POST", u, b),
+    put:    (u, b) => api("PUT", u, b),
+    del:    (u)    => api("DELETE", u),
+};
+
+// Time/date helpers
+window.fmt = {
+    time(t) {
+        if (!t) return "";
+        const [h, m] = t.split(":").map(Number);
+        const period = h >= 12 ? "PM" : "AM";
+        const h12 = h % 12 === 0 ? 12 : h % 12;
+        return `${h12}:${String(m).padStart(2, "0")} ${period}`;
+    },
+    date(d) {
+        if (!d) return "";
+        const dt = new Date(d + "T00:00:00");
+        return dt.toLocaleDateString(undefined, { weekday: "long", year: "numeric", month: "long", day: "numeric" });
+    },
+    dateShort(d) {
+        if (!d) return "";
+        const dt = new Date(d + "T00:00:00");
+        return dt.toLocaleDateString(undefined, { month: "short", day: "numeric", year: "numeric" });
+    },
+    today() {
+        const d = new Date();
+        const y = d.getFullYear();
+        const m = String(d.getMonth() + 1).padStart(2, "0");
+        const day = String(d.getDate()).padStart(2, "0");
+        return `${y}-${m}-${day}`;
+    },
+    tomorrow() {
+        const d = new Date();
+        d.setDate(d.getDate() + 1);
+        const y = d.getFullYear();
+        const m = String(d.getMonth() + 1).padStart(2, "0");
+        const day = String(d.getDate()).padStart(2, "0");
+        return `${y}-${m}-${day}`;
+    },
+};

static/js/app.js

@@ -0,0 +1,1180 @@
+// Main Alpine app state for the SOS Care Now dashboard.
+
+const WEEKDAYS = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+
+// Major US IANA timezones offered in the Settings dropdown.
+const US_TIMEZONES = [
+    { key: "America/New_York",     label: "Eastern — New York" },
+    { key: "America/Chicago",      label: "Central — Chicago" },
+    { key: "America/Denver",       label: "Mountain — Denver" },
+    { key: "America/Phoenix",      label: "Arizona (no DST) — Phoenix" },
+    { key: "America/Los_Angeles",  label: "Pacific — Los Angeles" },
+    { key: "America/Anchorage",    label: "Alaska — Anchorage" },
+    { key: "Pacific/Honolulu",     label: "Hawaii — Honolulu" },
+];
+
+const VISIT_LEVELS_FALLBACK = [
+    { key: 1, label: "Level 1", duration_minutes: 45 },
+    { key: 2, label: "Level 2", duration_minutes: 60 },
+    { key: 3, label: "Level 3", duration_minutes: 90 },
+    { key: "Nurse", label: "Nurse Visit", duration_minutes: 60 },
+];
+
+function generateTimeOptions() {
+    // 08:00 → 23:45 in 15-minute steps. Late slots exist for on-call coverage.
+    const out = [];
+    for (let h = 8; h < 24; h++) {
+        for (let m = 0; m < 60; m += 15) {
+            out.push(`${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`);
+        }
+    }
+    return out;
+}
+
+// Return {year, month, day, hour, minute} for an instant, projected into `tz` (IANA name).
+// Falls back to browser local if tz is missing or invalid.
+function wallClockIn(instant, tz) {
+    try {
+        const parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            year: "numeric", month: "2-digit", day: "2-digit",
+            hour: "2-digit", minute: "2-digit", hour12: false,
+        }).formatToParts(instant);
+        const get = (t) => Number(parts.find(p => p.type === t).value);
+        let hour = get("hour");
+        if (hour === 24) hour = 0; // Intl quirk: hour12:false sometimes yields "24"
+        return { year: get("year"), month: get("month"), day: get("day"), hour, minute: get("minute") };
+    } catch (_) {
+        return {
+            year: instant.getFullYear(), month: instant.getMonth() + 1, day: instant.getDate(),
+            hour: instant.getHours(), minute: instant.getMinutes(),
+        };
+    }
+}
+
+// Earliest valid "HH:MM" on `dateStr` that satisfies the configured lead time,
+// computed in the platform timezone (so an Eastern user booking Chicago appointments
+// sees the floor in Central time, not their browser's local time).
+// Returns null if no time on that date works (caller should treat as "no valid options").
+function minValidTimeForDate(dateStr, leadHours = 24, tz = null) {
+    if (!dateStr) return "08:00";
+    const minInstant = new Date(Date.now() + leadHours * 60 * 60 * 1000);
+    const wc = wallClockIn(minInstant, tz);
+    const [ty, tmo, td] = dateStr.split("-").map(Number);
+    // Compare Y/M/D in the platform tz.
+    const cmp = (ty - wc.year) || (tmo - wc.month) || (td - wc.day);
+    if (cmp > 0) return "08:00";       // target date is after the min-lead day
+    if (cmp < 0) return null;          // target date is before the min-lead day
+    // Same day in the platform tz: round UP to next 15-minute slot.
+    let h = wc.hour, m = wc.minute;
+    const rem = m % 15;
+    if (rem !== 0) m += 15 - rem;
+    if (m === 60) { m = 0; h += 1; }
+    if (h >= 24) return null; // past end-of-day window
+    if (h < 8) { h = 8; m = 0; } // floor at 08:00
+    return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}`;
+}
+
+function appState() {
+    return {
+        // --- Auth ---
+        authenticated: false,
+        userRole: null,         // "admin" | "provider"
+        currentUser: "",
+        providerId: null,
+        loginMode: "admin",     // "admin" | "provider"
+        loginForm: { username: "", password: "" },
+        providerLoginForm: { name: "", password: "" },
+        providerOptions: [],
+        minLeadTimeHours: 24,   // overwritten by /api/schedule/config on init
+        platformTimezone: null, // IANA tz (e.g. "America/Chicago") — overwritten by /api/schedule/config
+        loginError: "",
+        loginBusy: false,
+
+        // --- Navigation ---
+        view: "schedule", // schedule | providers | patients | appointments | calendar | audit | portal
+
+        // --- Loading + toast ---
+        toast: null,
+        loading: false,
+
+        // --- Data caches ---
+        providers: [],
+        patients: [],
+        appointments: [],
+        visitLevels: VISIT_LEVELS_FALLBACK,
+
+        // --- Schedule view ---
+        sched: {
+            phase: "form", // form | matches | booked | error
+            patientId: "",
+            visitLevel: "1",
+            address: "",
+            preferredDate: "",
+            timeStart: "09:00",
+            timeEnd: "12:00",
+            timeOptions: generateTimeOptions(),
+            error: "",
+            threadId: "",
+            matches: [],
+            selectedIdx: null,
+            bookedAppt: null,
+            notificationsSent: false,
+        },
+
+        // --- Cancel tab ---
+        cancel: {
+            patientFilter: "All",
+            providerFilter: "All",
+            selectedId: "",
+        },
+        scheduleTab: "new", // new | cancel
+
+        // --- Appointments view (admin) ---
+        apptView: {
+            statusFilter: "All",     // All | scheduled | completed | cancelled
+            patientFilter: "All",
+            providerFilter: "All",
+            list: [],
+        },
+
+        // --- Providers view ---
+        prov: {
+            showAdd: false,
+            editingId: null,
+            expandedId: null,           // id of the provider whose availability editor is open
+            form: this ? null : null,   // placeholder
+            confirmDelete: null,
+            newOnCallDate: "",
+            newBlockType: "All Day",
+            newBlock: { title: "", date: "", start_time: "08:00", end_time: "12:00" },
+        },
+        provForm: {
+            name: "", email: "", password: "", address: "", category: "provider",
+            work_hours: { start: "08:00", end: "17:00" },
+            lunch_break: { start: "12:00", end: "13:00" },
+            service_levels: [1, 2, 3],
+        },
+
+        // --- Patients view ---
+        pat: {
+            showAdd: false,
+            editingId: null,
+            confirmDelete: null,
+        },
+        patForm: { name: "", email: "", address: "", notes: "" },
+
+        // --- Calendar view ---
+        cal: {
+            selectedProviderIds: [],
+            showUnavailable: true,
+            showTravel: true,
+            showOnCall: true,
+            providerLegend: [],
+            instance: null,
+            selectedEvent: null,
+        },
+
+        // --- Audit log ---
+        audit: { search: "", action: "All", entries: [], actionTypes: [] },
+
+        // --- Settings ---
+        sett: {
+            current: null,
+            defaults: null,
+            form: null,
+            saving: false,
+        },
+
+        // --- Provider portal ---
+        portal: {
+            self: null,
+            tab: "availability", // availability | schedule
+            editForm: { email: "", address: "", work_hours: { start: "08:00", end: "17:00" }, lunch_break: { start: "12:00", end: "13:00" }, recurring_days_off: [] },
+            newBlockType: "All Day",
+            newBlock: { title: "", date: "", start_time: "08:00", end_time: "12:00" },
+            newOnCallDate: "",
+            calendar: null,
+            selectedEvent: null,
+        },
+
+        // ============================================================
+        // INIT
+        // ============================================================
+        async init() {
+            this.sched.preferredDate = fmt.tomorrow();
+            this.prov.newBlock.date = fmt.tomorrow();
+            this.prov.newOnCallDate = fmt.today();
+            this.portal.newBlock.date = fmt.tomorrow();
+            this.portal.newOnCallDate = fmt.today();
+
+            await this.loadSchedulingConfig();
+            await this.refreshAuth();
+            if (!this.authenticated) {
+                await this.loadProviderOptions();
+            } else {
+                await this.afterLogin();
+            }
+
+            this.$watch("view", (v) => this.onViewChange(v));
+            this.$watch("sched.preferredDate", () => this.enforceLeadTime());
+            // Snap to first valid slot on the initial (tomorrow) default.
+            this.enforceLeadTime();
+        },
+
+        // Restrict sched.timeStart/timeEnd to slots that respect the configured lead time.
+        // Called on init and whenever the preferred date changes.
+        get validStartTimes() {
+            const minT = minValidTimeForDate(this.sched.preferredDate, this.minLeadTimeHours, this.platformTimezone);
+            if (!minT) return [];
+            return this.sched.timeOptions.filter(t => t >= minT);
+        },
+        // Earliest selectable date given the current lead time. Tries today first, then tomorrow.
+        get minSelectableDate() {
+            const today = fmt.today();
+            if (minValidTimeForDate(today, this.minLeadTimeHours, this.platformTimezone)) return today;
+            return fmt.tomorrow();
+        },
+        // Latest Start is NOT constrained by lead time — just must be >= timeStart.
+        // This lets users widen the window into the evening (on-call still respects lead time per-slot).
+        get validEndTimes() {
+            const start = this.sched.timeStart;
+            if (!start) return [];
+            return this.sched.timeOptions.filter(t => t >= start);
+        },
+        // Friendly label for the platform timezone, e.g. "Central — Chicago" for "America/Chicago".
+        // Falls back to the raw IANA name if not in the known list.
+        get platformTimezoneLabel() {
+            if (!this.platformTimezone) return "";
+            const match = US_TIMEZONES.find(t => t.key === this.platformTimezone);
+            return match ? match.label : this.platformTimezone;
+        },
+        // "Now" represented as a Date whose local-time fields equal the current wall-clock
+        // in the platform timezone. FullCalendar (with default timeZone:"local") then places
+        // the now-indicator at the correct slot for an Eastern user viewing Chicago times.
+        platformNow() {
+            const tz = this.platformTimezone;
+            if (!tz) return new Date();
+            const wc = wallClockIn(new Date(), tz);
+            return new Date(wc.year, wc.month - 1, wc.day, wc.hour, wc.minute);
+        },
+        enforceLeadTime() {
+            const valid = this.validStartTimes;
+            if (valid.length === 0) {
+                this.sched.timeStart = "";
+                this.sched.timeEnd = "";
+                return;
+            }
+            if (!valid.includes(this.sched.timeStart)) this.sched.timeStart = valid[0];
+            const endValid = this.sched.timeOptions.filter(t => t >= this.sched.timeStart);
+            if (!endValid.includes(this.sched.timeEnd) || this.sched.timeEnd < this.sched.timeStart) {
+                // Default end = 3 hours after start (12 slots) or last available
+                const endIdx = Math.min(12, endValid.length - 1);
+                this.sched.timeEnd = endValid[endIdx];
+            }
+        },
+
+        async refreshAuth() {
+            try {
+                const me = await API.get("/api/auth/me");
+                if (me.authenticated) {
+                    this.authenticated = true;
+                    this.userRole = me.user_role;
+                    this.currentUser = me.current_user;
+                    this.providerId = me.provider_id || null;
+                }
+            } catch (e) { /* not logged in */ }
+        },
+
+        async loadProviderOptions() {
+            try { this.providerOptions = await API.get("/api/auth/provider-names"); }
+            catch (e) { this.providerOptions = []; }
+        },
+
+        async loadSchedulingConfig() {
+            try {
+                const cfg = await API.get("/api/schedule/config");
+                if (cfg && typeof cfg.min_lead_time_hours === "number") {
+                    this.minLeadTimeHours = cfg.min_lead_time_hours;
+                }
+                if (cfg && typeof cfg.timezone === "string" && cfg.timezone) {
+                    this.platformTimezone = cfg.timezone;
+                }
+            } catch (e) { /* keep defaults */ }
+        },
+
+        async afterLogin() {
+            // Pick a default view per role
+            if (this.userRole === "provider") {
+                this.view = "portal";
+                await this.loadPortal();
+            } else {
+                this.view = "schedule";
+                await this.loadVisitLevels();
+                await this.loadPatients();
+            }
+        },
+
+        // ============================================================
+        // LOGIN
+        // ============================================================
+        async submitLogin() {
+            this.loginError = "";
+            this.loginBusy = true;
+            try {
+                if (this.loginMode === "admin") {
+                    const res = await API.post("/api/auth/login", this.loginForm);
+                    this.authenticated = true;
+                    this.userRole = res.user_role;
+                    this.currentUser = res.current_user;
+                    this.providerId = null;
+                } else {
+                    const res = await API.post("/api/auth/provider-login", this.providerLoginForm);
+                    this.authenticated = true;
+                    this.userRole = res.user_role;
+                    this.currentUser = res.current_user;
+                    this.providerId = res.provider_id;
+                }
+                await this.afterLogin();
+            } catch (e) {
+                this.loginError = e.message || "Login failed";
+            } finally {
+                this.loginBusy = false;
+            }
+        },
+
+        async logout() {
+            try { await API.post("/api/auth/logout"); } catch (e) {}
+            this.authenticated = false;
+            this.userRole = null;
+            this.currentUser = "";
+            this.providerId = null;
+            this.loginForm = { username: "", password: "" };
+            this.providerLoginForm = { name: "", password: "" };
+            await this.loadProviderOptions();
+        },
+
+        // ============================================================
+        // VIEW NAVIGATION
+        // ============================================================
+        async onViewChange(v) {
+            // Destroy any existing calendar instance
+            if (this.cal.instance) { this.cal.instance.destroy(); this.cal.instance = null; }
+            if (this.portal.calendar) { this.portal.calendar.destroy(); this.portal.calendar = null; }
+
+            if (v === "schedule")  { await this.loadVisitLevels(); await this.loadPatients(); }
+            if (v === "providers") { await this.loadProviders(); }
+            if (v === "patients")  { await this.loadPatients(); }
+            if (v === "appointments") { await this.loadAppointmentsList(); await this.loadProviders(); await this.loadPatients(); }
+            if (v === "calendar")  { await this.loadProviders(); await this.$nextTick(); this.mountCalendar(); }
+            if (v === "audit")     { await this.loadAudit(); }
+            if (v === "portal")    { await this.loadPortal(); }
+            if (v === "settings")  { await this.loadSettings(); }
+        },
+
+        // ============================================================
+        // SETTINGS
+        // ============================================================
+        async loadSettings() {
+            try {
+                const res = await API.get("/api/settings");
+                this.sett.current = res.current;
+                this.sett.defaults = res.defaults;
+                // Build editable form (deep-copy to avoid mutating .current until save)
+                this.sett.form = JSON.parse(JSON.stringify(res.current));
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        get timezoneOptions() {
+            // Surface the saved value even if it's not in the standard US list.
+            const current = this.sett.form && this.sett.form.timezone;
+            const standardKeys = US_TIMEZONES.map(t => t.key);
+            if (current && !standardKeys.includes(current)) {
+                return [{ key: current, label: `${current} (current)` }, ...US_TIMEZONES];
+            }
+            return US_TIMEZONES;
+        },
+
+        get visitLevelEntries() {
+            // Return [{key, label, duration_minutes}, ...] for stable iteration in the template.
+            if (!this.sett.form || !this.sett.form.visit_levels) return [];
+            return Object.entries(this.sett.form.visit_levels).map(([k, v]) => ({
+                key: k,
+                label: v.label || k,
+                duration_minutes: v.duration_minutes,
+            }));
+        },
+
+        updateVisitLevelDuration(key, value) {
+            const n = parseInt(value);
+            if (isNaN(n)) return;
+            this.sett.form.visit_levels[key].duration_minutes = n;
+        },
+
+        async saveSettings() {
+            if (this.sett.saving) return;
+            this.sett.saving = true;
+            try {
+                const res = await API.put("/api/settings", this.sett.form);
+                this.sett.current = res.current;
+                this.sett.form = JSON.parse(JSON.stringify(res.current));
+                // Refresh the schedule view's visit-level dropdown so changes are visible immediately.
+                this.visitLevels = Object.entries(res.current.visit_levels).map(([k, v]) => ({
+                    key: (isNaN(parseInt(k)) ? k : parseInt(k)),
+                    label: v.label,
+                    duration_minutes: v.duration_minutes,
+                }));
+                if (typeof res.current.min_lead_time_hours === "number") {
+                    this.minLeadTimeHours = res.current.min_lead_time_hours;
+                    this.enforceLeadTime();
+                }
+                if (res.changes.length === 0) {
+                    this.showToast("No changes to save.", "info");
+                } else {
+                    this.showToast(`Saved ${res.changes.length} change(s).`, "success");
+                }
+            } catch (e) {
+                this.showToast(e.message, "error");
+            } finally {
+                this.sett.saving = false;
+            }
+        },
+
+        async resetSettings() {
+            if (!confirm("Reset ALL settings to defaults? This cannot be undone.")) return;
+            try {
+                const res = await API.post("/api/settings/reset");
+                this.sett.current = res.current;
+                this.sett.form = JSON.parse(JSON.stringify(res.current));
+                this.showToast("Settings reset to defaults.", "success");
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        // ============================================================
+        // TOAST
+        // ============================================================
+        showToast(msg, type = "info") {
+            this.toast = { msg, type };
+            setTimeout(() => { if (this.toast && this.toast.msg === msg) this.toast = null; }, 3500);
+        },
+
+        // ============================================================
+        // DATA LOADERS
+        // ============================================================
+        async loadVisitLevels() {
+            try { this.visitLevels = await API.get("/api/schedule/visit-levels"); }
+            catch (e) { /* keep fallback */ }
+        },
+
+        async loadProviders() {
+            try { this.providers = await API.get("/api/providers?active_only=false"); }
+            catch (e) { this.showToast(e.message, "error"); }
+        },
+
+        async loadPatients() {
+            try { this.patients = await API.get("/api/patients"); }
+            catch (e) { this.showToast(e.message, "error"); }
+        },
+
+        // ============================================================
+        // SCHEDULE — find matches & book
+        // ============================================================
+        get selectedPatient() {
+            return this.patients.find(p => p.id === this.sched.patientId);
+        },
+
+        onPatientChange() {
+            const p = this.selectedPatient;
+            if (p) this.sched.address = p.address || "";
+        },
+
+        async findMatches() {
+            if (!this.sched.patientId) { this.showToast("Select a patient", "error"); return; }
+            if (!this.sched.address) { this.showToast("Address required", "error"); return; }
+            if (!this.sched.timeStart || !this.sched.timeEnd) {
+                this.showToast(`No appointment times on this date meet the ${this.minLeadTimeHours}-hour lead time. Pick a later date.`, "error");
+                return;
+            }
+            this.loading = true;
+            this.sched.error = "";
+            try {
+                const vl = isNaN(parseInt(this.sched.visitLevel)) ? this.sched.visitLevel : parseInt(this.sched.visitLevel);
+                const res = await API.post("/api/schedule/find-matches", {
+                    patient_id: this.sched.patientId,
+                    visit_level: vl,
+                    visit_address: this.sched.address,
+                    preferred_dates: [this.sched.preferredDate],
+                    preferred_time_window: { start: this.sched.timeStart, end: this.sched.timeEnd },
+                });
+                if (res.error) {
+                    this.sched.error = res.error;
+                    this.sched.phase = "error";
+                } else if ((res.ranked_matches || []).length === 0) {
+                    this.sched.error = "No matches found. Try different dates or times.";
+                    this.sched.phase = "error";
+                } else {
+                    this.sched.threadId = res.thread_id;
+                    this.sched.matches = res.ranked_matches;
+                    this.sched.selectedIdx = null;
+                    this.sched.phase = "matches";
+                }
+            } catch (e) {
+                this.sched.error = e.message;
+                this.sched.phase = "error";
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        get groupedMatches() {
+            // Group ranked matches by provider, preserving rank order.
+            const groups = [];
+            const seen = {};
+            this.sched.matches.forEach((m, idx) => {
+                if (!(m.provider_id in seen)) {
+                    seen[m.provider_id] = { provider_id: m.provider_id, name: m.provider_name, min_travel: m.travel_time_minutes, is_oncall: !!m.is_oncall, slots: [] };
+                    groups.push(seen[m.provider_id]);
+                } else {
+                    seen[m.provider_id].is_oncall = seen[m.provider_id].is_oncall || !!m.is_oncall;
+                }
+                seen[m.provider_id].slots.push({ idx, ...m });
+            });
+            return groups;
+        },
+
+        selectSlot(idx) {
+            this.sched.selectedIdx = idx;
+        },
+
+        async bookAppointment() {
+            if (this.sched.selectedIdx === null) return;
+            this.loading = true;
+            try {
+                const res = await API.post("/api/schedule/book", {
+                    thread_id: this.sched.threadId,
+                    selection_index: this.sched.selectedIdx,
+                });
+                if (res.error) {
+                    this.sched.error = res.error;
+                    this.sched.phase = "error";
+                } else {
+                    this.sched.bookedAppt = res.booked_appointment;
+                    this.sched.notificationsSent = res.notifications_sent;
+                    this.sched.phase = "booked";
+                }
+            } catch (e) {
+                this.sched.error = e.message;
+                this.sched.phase = "error";
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        startOver() {
+            this.sched.phase = "form";
+            this.sched.error = "";
+            this.sched.matches = [];
+            this.sched.selectedIdx = null;
+            this.sched.bookedAppt = null;
+        },
+
+        // Like startOver(), but keeps the form inputs so the user can tweak and re-submit.
+        backToForm() {
+            this.sched.phase = "form";
+            this.sched.error = "";
+            this.sched.matches = [];
+            this.sched.selectedIdx = null;
+        },
+
+        get matchesCount() {
+            return this.sched.matches.length;
+        },
+
+        // ============================================================
+        // CANCEL APPOINTMENT (admin)
+        // ============================================================
+        async loadFutureAppointments() {
+            const all = await API.get("/api/appointments?status=scheduled");
+            const today = fmt.today();
+            this.appointments = all.filter(a => a.date >= today);
+        },
+
+        async openCancelTab() {
+            this.scheduleTab = "cancel";
+            await this.loadFutureAppointments();
+            await this.loadProviders();
+            await this.loadPatients();
+        },
+
+        get filteredCancelAppts() {
+            let list = [...this.appointments];
+            if (this.cancel.patientFilter !== "All") {
+                const pid = (this.patients.find(p => p.name === this.cancel.patientFilter) || {}).id;
+                if (pid) list = list.filter(a => a.patient_id === pid);
+            }
+            if (this.cancel.providerFilter !== "All") {
+                const pid = (this.providers.find(p => p.name === this.cancel.providerFilter) || {}).id;
+                if (pid) list = list.filter(a => a.provider_id === pid);
+            }
+            return list;
+        },
+
+        async cancelAppointment() {
+            if (!this.cancel.selectedId) { this.showToast("Select an appointment", "error"); return; }
+            if (!confirm("Cancel this appointment? Calendar event and notifications will be sent.")) return;
+            this.loading = true;
+            try {
+                await API.del(`/api/appointments/${this.cancel.selectedId}`);
+                this.showToast("Appointment cancelled", "success");
+                this.cancel.selectedId = "";
+                await this.loadFutureAppointments();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        // ============================================================
+        // APPOINTMENTS view (admin)
+        // ============================================================
+        async loadAppointmentsList() {
+            this.apptView.list = await API.get("/api/appointments");
+        },
+
+        get filteredAppointmentsList() {
+            let list = [...this.apptView.list];
+            if (this.apptView.statusFilter !== "All") {
+                list = list.filter(a => (a.status || "scheduled") === this.apptView.statusFilter);
+            }
+            if (this.apptView.patientFilter !== "All") {
+                const pid = (this.patients.find(p => p.name === this.apptView.patientFilter) || {}).id;
+                if (pid) list = list.filter(a => a.patient_id === pid);
+            }
+            if (this.apptView.providerFilter !== "All") {
+                const pid = (this.providers.find(p => p.name === this.apptView.providerFilter) || {}).id;
+                if (pid) list = list.filter(a => a.provider_id === pid);
+            }
+            // Sort: upcoming first (date+time ascending), then completed/cancelled at the bottom.
+            const today = fmt.today();
+            list.sort((a, b) => {
+                const akey = (a.date || "") + "T" + (a.start_time || "");
+                const bkey = (b.date || "") + "T" + (b.start_time || "");
+                const aFuture = (a.date || "") >= today && (a.status || "scheduled") === "scheduled";
+                const bFuture = (b.date || "") >= today && (b.status || "scheduled") === "scheduled";
+                if (aFuture !== bFuture) return aFuture ? -1 : 1;
+                return akey.localeCompare(bkey);
+            });
+            return list;
+        },
+
+        statusBadgeClass(status) {
+            const s = status || "scheduled";
+            if (s === "completed") return "badge badge-emerald";
+            if (s === "cancelled") return "badge badge-red";
+            return "badge badge-blue";
+        },
+
+        // True when the appointment's start time has passed in the platform timezone.
+        // Used to enable/disable the "Mark Complete" button for providers.
+        canCompleteAppointment(a) {
+            if (!a || (a.status && a.status !== "scheduled")) return false;
+            if (!a.date || !a.start_time) return false;
+            const now = this.platformNow();
+            const [y, mo, d] = a.date.split("-").map(Number);
+            const [h, mi] = a.start_time.split(":").map(Number);
+            const startLocal = new Date(y, mo - 1, d, h, mi);
+            return now >= startLocal;
+        },
+
+        async markAppointmentComplete(appointmentId) {
+            if (!appointmentId) return;
+            this.loading = true;
+            try {
+                await API.post(`/api/appointments/${appointmentId}/complete`, {});
+                this.showToast("Marked complete", "success");
+                // Refresh whichever view we're on
+                if (this.view === "portal" && this.portal.calendar) this.portal.calendar.refetchEvents();
+                if (this.view === "appointments") await this.loadAppointmentsList();
+                this.portal.selectedEvent = null;
+            } catch (e) {
+                this.showToast(e.message, "error");
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        // ============================================================
+        // PROVIDERS view
+        // ============================================================
+        openAddProvider() {
+            this.prov.editingId = null;
+            this.provForm = {
+                name: "", email: "", password: "", address: "", category: "provider",
+                work_hours: { start: "08:00", end: "17:00" },
+                lunch_break: { start: "12:00", end: "13:00" },
+                service_levels: [1, 2, 3],
+            };
+            this.prov.showAdd = true;
+        },
+
+        openEditProvider(p) {
+            this.prov.editingId = p.id;
+            this.provForm = {
+                name: p.name || "",
+                email: p.email || "",
+                password: p.password || "",
+                address: p.address || "",
+                category: p.category || "provider",
+                work_hours: { ...(p.work_hours || { start: "08:00", end: "17:00" }) },
+                lunch_break: { ...(p.lunch_break || { start: "12:00", end: "13:00" }) },
+                service_levels: [...(p.service_levels || [])],
+            };
+            this.prov.showAdd = true;
+        },
+
+        toggleServiceLevel(level) {
+            const idx = this.provForm.service_levels.findIndex(x => x == level);
+            if (idx >= 0) this.provForm.service_levels.splice(idx, 1);
+            else this.provForm.service_levels.push(level);
+        },
+
+        async saveProvider() {
+            this.loading = true;
+            try {
+                if (this.prov.editingId) {
+                    await API.put(`/api/providers/${this.prov.editingId}`, this.provForm);
+                    this.showToast("Provider updated", "success");
+                } else {
+                    await API.post("/api/providers", this.provForm);
+                    this.showToast("Provider added", "success");
+                }
+                this.prov.showAdd = false;
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        async deleteProvider(id) {
+            try {
+                await API.del(`/api/providers/${id}`);
+                this.showToast("Provider deleted", "success");
+                this.prov.confirmDelete = null;
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async saveRecurringDaysOff(provider) {
+            try {
+                await API.put(`/api/providers/${provider.id}/recurring-days-off`, { recurring_days_off: provider.recurring_days_off || [] });
+                this.showToast("Standing days off updated", "success");
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        toggleRecurringDay(provider, day) {
+            const list = provider.recurring_days_off || [];
+            const idx = list.indexOf(day);
+            if (idx >= 0) list.splice(idx, 1);
+            else list.push(day);
+            provider.recurring_days_off = list;
+        },
+
+        async addBlock(provider) {
+            const b = this.prov.newBlock;
+            const payload = {
+                date: b.date,
+                all_day: this.prov.newBlockType === "All Day",
+                start_time: this.prov.newBlockType === "Specific Time" ? b.start_time : null,
+                end_time: this.prov.newBlockType === "Specific Time" ? b.end_time : null,
+                title: b.title || "Unavailable",
+            };
+            try {
+                await API.post(`/api/providers/${provider.id}/days-off`, payload);
+                this.showToast("Unavailable block added", "success");
+                this.prov.newBlock = { title: "", date: b.date, start_time: "08:00", end_time: "12:00" };
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async removeBlock(providerId, index) {
+            try {
+                await API.del(`/api/providers/${providerId}/days-off/${index}`);
+                this.showToast("Block removed", "success");
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async addOnCall(provider) {
+            if (!this.prov.newOnCallDate) return;
+            try {
+                await API.post(`/api/providers/${provider.id}/on-call`, { date: this.prov.newOnCallDate });
+                this.showToast("On-call day added", "success");
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async toggleOnCallDate(provider, date) {
+            const isOn = (provider.on_call || []).includes(date);
+            try {
+                await API.post(`/api/providers/${provider.id}/on-call/toggle`, { date, on_call: !isOn });
+                this.showToast(isOn ? "On-call removed" : "On-call set", "success");
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async removeOnCall(providerId, date) {
+            try {
+                await API.del(`/api/providers/${providerId}/on-call/${date}`);
+                this.showToast("On-call day removed", "success");
+                await this.loadProviders();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        formatBlock(off) {
+            if (typeof off === "string") return `${off} — All Day`;
+            if (off.all_day) return `${off.date} — All Day — ${off.title || "Unavailable"}`;
+            return `${off.date} ${off.start_time}–${off.end_time} — ${off.title || "Unavailable"}`;
+        },
+
+        // Compact summary like "May 30" (all day) or "May 30 9:00 AM–12:00 PM".
+        formatBlockShort(off) {
+            if (typeof off === "string") return fmt.dateShort(off);
+            const d = fmt.dateShort(off.date);
+            if (off.all_day) return d;
+            return `${d} ${fmt.time(off.start_time)}–${fmt.time(off.end_time)}`;
+        },
+
+        // Returns {block, originalIndex} pairs for blocks whose date is today or later.
+        // Preserves original index so removeBlock still targets the right sheet row.
+        upcomingBlocks(provider) {
+            const today = fmt.today();
+            const out = [];
+            (provider.days_off || []).forEach((off, i) => {
+                const d = typeof off === "string" ? off : off?.date;
+                if (d && d >= today) out.push({ block: off, originalIndex: i });
+            });
+            return out;
+        },
+
+        // ============================================================
+        // PATIENTS view
+        // ============================================================
+        openAddPatient() {
+            this.pat.editingId = null;
+            this.patForm = { name: "", email: "", address: "", notes: "" };
+            this.pat.showAdd = true;
+        },
+
+        openEditPatient(p) {
+            this.pat.editingId = p.id;
+            this.patForm = { name: p.name || "", email: p.email || "", address: p.address || "", notes: p.notes || "" };
+            this.pat.showAdd = true;
+        },
+
+        async savePatient() {
+            this.loading = true;
+            try {
+                if (this.pat.editingId) {
+                    await API.put(`/api/patients/${this.pat.editingId}`, this.patForm);
+                    this.showToast("Patient updated", "success");
+                } else {
+                    await API.post("/api/patients", this.patForm);
+                    this.showToast("Patient added", "success");
+                }
+                this.pat.showAdd = false;
+                await this.loadPatients();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            } finally {
+                this.loading = false;
+            }
+        },
+
+        async deletePatient(id) {
+            try {
+                await API.del(`/api/patients/${id}`);
+                this.showToast("Patient deleted", "success");
+                this.pat.confirmDelete = null;
+                await this.loadPatients();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        // ============================================================
+        // CALENDAR view
+        // ============================================================
+        async mountCalendar() {
+            const el = document.getElementById("calendar-root");
+            if (!el || typeof FullCalendar === "undefined") return;
+            this.cal.providerLegend = this.providers.map(p => ({ id: p.id, name: p.name }));
+            if (this.cal.selectedProviderIds.length === 0) {
+                this.cal.selectedProviderIds = this.providers.map(p => p.id);
+            }
+            this.cal.instance = new FullCalendar.Calendar(el, {
+                initialView: "timeGridWeek",
+                headerToolbar: { left: "prev,next today", center: "title", right: "dayGridMonth,timeGridWeek,timeGridDay,listWeek" },
+                height: 720,
+                slotMinTime: "00:00:00",
+                slotMaxTime: "24:00:00",
+                scrollTime: "07:00:00",
+                nowIndicator: true,
+                now: () => this.platformNow(),
+                events: (info, success, failure) => this.fetchCalEvents(info, success, failure),
+                eventClick: (info) => {
+                    const p = info.event.extendedProps;
+                    if (p.type === "appointment" || p.type === "days_off" || p.type === "on_call") {
+                        this.cal.selectedEvent = { ...p, eventStart: info.event.start, eventEnd: info.event.end, title: info.event.title };
+                    }
+                },
+            });
+            this.cal.instance.render();
+        },
+
+        async fetchCalEvents(info, success, failure) {
+            try {
+                const params = new URLSearchParams({
+                    start: info.startStr,
+                    end: info.endStr,
+                    show_unavailable: this.cal.showUnavailable ? "true" : "false",
+                    show_travel: this.cal.showTravel ? "true" : "false",
+                    show_oncall: this.cal.showOnCall ? "true" : "false",
+                });
+                if (this.cal.selectedProviderIds.length) params.set("provider_ids", this.cal.selectedProviderIds.join(","));
+                const res = await API.get(`/api/calendar/events?${params.toString()}`);
+                this.cal.providerLegend = res.providers || [];
+                success(res.events || []);
+            } catch (e) {
+                failure(e);
+                this.showToast(e.message, "error");
+            }
+        },
+
+        toggleCalProvider(id) {
+            const i = this.cal.selectedProviderIds.indexOf(id);
+            if (i >= 0) this.cal.selectedProviderIds.splice(i, 1);
+            else this.cal.selectedProviderIds.push(id);
+            if (this.cal.instance) this.cal.instance.refetchEvents();
+        },
+
+        toggleAllProviders() {
+            if (this.cal.selectedProviderIds.length === this.providers.length) {
+                this.cal.selectedProviderIds = [];
+            } else {
+                this.cal.selectedProviderIds = this.providers.map(p => p.id);
+            }
+            if (this.cal.instance) this.cal.instance.refetchEvents();
+        },
+
+        refetchCalendar() {
+            if (this.cal.instance) this.cal.instance.refetchEvents();
+        },
+
+        // ============================================================
+        // AUDIT
+        // ============================================================
+        async loadAudit() {
+            try {
+                this.audit.actionTypes = await API.get("/api/audit/actions");
+            } catch (e) {}
+            await this.refreshAudit();
+        },
+
+        async refreshAudit() {
+            try {
+                const params = new URLSearchParams();
+                if (this.audit.search) params.set("search", this.audit.search);
+                if (this.audit.action && this.audit.action !== "All") params.set("action", this.audit.action);
+                this.audit.entries = await API.get(`/api/audit?${params.toString()}`);
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        // ============================================================
+        // PROVIDER PORTAL
+        // ============================================================
+        async loadPortal() {
+            if (!this.providerId) return;
+            try {
+                this.portal.self = await API.get(`/api/providers/${this.providerId}`);
+                this.portal.editForm = {
+                    email: this.portal.self.email || "",
+                    address: this.portal.self.address || "",
+                    work_hours: { ...(this.portal.self.work_hours || { start: "08:00", end: "17:00" }) },
+                    lunch_break: { ...(this.portal.self.lunch_break || { start: "12:00", end: "13:00" }) },
+                    recurring_days_off: [...(this.portal.self.recurring_days_off || [])],
+                };
+                if (this.portal.tab === "schedule") {
+                    await this.$nextTick();
+                    this.mountPortalCalendar();
+                }
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async savePortalProfile() {
+            if (!this.providerId) return;
+            try {
+                await API.put(`/api/providers/${this.providerId}`, {
+                    email: this.portal.editForm.email,
+                    address: this.portal.editForm.address,
+                    work_hours: this.portal.editForm.work_hours,
+                    lunch_break: this.portal.editForm.lunch_break,
+                });
+                this.showToast("Profile updated", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        togglePortalRecurringDay(day) {
+            const list = this.portal.editForm.recurring_days_off;
+            const i = list.indexOf(day);
+            if (i >= 0) list.splice(i, 1);
+            else list.push(day);
+        },
+
+        async savePortalRecurring() {
+            try {
+                await API.put(`/api/providers/${this.providerId}/recurring-days-off`, { recurring_days_off: this.portal.editForm.recurring_days_off });
+                this.showToast("Standing days off updated", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async addPortalBlock() {
+            const b = this.portal.newBlock;
+            const payload = {
+                date: b.date,
+                all_day: this.portal.newBlockType === "All Day",
+                start_time: this.portal.newBlockType === "Specific Time" ? b.start_time : null,
+                end_time: this.portal.newBlockType === "Specific Time" ? b.end_time : null,
+                title: b.title || "Unavailable",
+            };
+            try {
+                await API.post(`/api/providers/${this.providerId}/days-off`, payload);
+                this.showToast("Block added", "success");
+                this.portal.newBlock = { title: "", date: b.date, start_time: "08:00", end_time: "12:00" };
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async removePortalBlock(index) {
+            try {
+                await API.del(`/api/providers/${this.providerId}/days-off/${index}`);
+                this.showToast("Block removed", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async addPortalOnCall() {
+            if (!this.portal.newOnCallDate) return;
+            try {
+                await API.post(`/api/providers/${this.providerId}/on-call`, { date: this.portal.newOnCallDate });
+                this.showToast("On-call day added", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async togglePortalOnCall(date) {
+            const isOn = (this.portal.self?.on_call || []).includes(date);
+            try {
+                await API.post(`/api/providers/${this.providerId}/on-call/toggle`, { date, on_call: !isOn });
+                this.showToast(isOn ? "On-call removed" : "On-call set", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async removePortalOnCall(date) {
+            try {
+                await API.del(`/api/providers/${this.providerId}/on-call/${date}`);
+                this.showToast("Removed", "success");
+                await this.loadPortal();
+            } catch (e) {
+                this.showToast(e.message, "error");
+            }
+        },
+
+        async switchPortalTab(tab) {
+            this.portal.tab = tab;
+            if (this.portal.calendar) { this.portal.calendar.destroy(); this.portal.calendar = null; }
+            if (tab === "schedule") {
+                await this.$nextTick();
+                this.mountPortalCalendar();
+            }
+        },
+
+        mountPortalCalendar() {
+            const el = document.getElementById("portal-calendar-root");
+            if (!el || typeof FullCalendar === "undefined") return;
+            this.portal.calendar = new FullCalendar.Calendar(el, {
+                initialView: "timeGridWeek",
+                headerToolbar: { left: "prev,next today", center: "title", right: "dayGridMonth,timeGridWeek,timeGridDay,listWeek" },
+                height: 720,
+                slotMinTime: "00:00:00",
+                slotMaxTime: "24:00:00",
+                scrollTime: "07:00:00",
+                nowIndicator: true,
+                now: () => this.platformNow(),
+                events: async (info, success, failure) => {
+                    try {
+                        const params = new URLSearchParams({ start: info.startStr, end: info.endStr, show_unavailable: "true", show_travel: "true" });
+                        const res = await API.get(`/api/calendar/events?${params.toString()}`);
+                        success(res.events || []);
+                    } catch (e) { failure(e); }
+                },
+                eventClick: (info) => {
+                    const p = info.event.extendedProps;
+                    this.portal.selectedEvent = { ...p, eventStart: info.event.start, eventEnd: info.event.end, title: info.event.title };
+                },
+            });
+            this.portal.calendar.render();
+        },
+
+        formatTime: (t) => fmt.time(t),
+        formatDate: (d) => fmt.date(d),
+        formatDateShort: (d) => fmt.dateShort(d),
+        formatTs(ts) {
+            if (!ts) return "";
+            const d = new Date(ts);
+            return d.toLocaleString();
+        },
+    };
+}
+
+window.appState = appState;

templates/index.html

@@ -0,0 +1,1268 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>SOS Care Now — Scheduling</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet" />
+    <link href="https://cdn.jsdelivr.net/npm/fullcalendar@6.1.10/index.global.min.css" rel="stylesheet" />
+    <link rel="stylesheet" href="/static/css/app.css" />
+    <script src="https://cdn.jsdelivr.net/npm/fullcalendar@6.1.10/index.global.min.js"></script>
+    <script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"></script>
+    <script src="/static/js/api.js?v=5"></script>
+    <script src="/static/js/app.js?v=5"></script>
+</head>
+<body x-data="appState()" x-init="init()" x-cloak>
+
+<!-- ============================================================ -->
+<!-- LOGIN  -->
+<!-- ============================================================ -->
+<template x-if="!authenticated">
+    <div class="login-bg min-h-screen flex items-center justify-center p-6">
+        <div class="card w-full max-w-md p-8">
+            <div class="text-center mb-6">
+                <div class="inline-flex items-center justify-center w-14 h-14 rounded-2xl bg-blue-600 text-white text-2xl font-bold mb-3">SOS</div>
+                <h1 class="text-2xl font-bold">SOS Care Now</h1>
+                <p class="text-sm text-slate-500">Medical Scheduling Agent</p>
+            </div>
+
+            <div class="flex bg-slate-100 rounded-lg p-1 mb-5 text-sm">
+                <button
+                    @click="loginMode = 'admin'; loginError = ''"
+                    :class="loginMode === 'admin' ? 'bg-white shadow-sm font-semibold text-slate-900' : 'text-slate-500'"
+                    class="flex-1 py-2 rounded-md transition-all">Admin</button>
+                <button
+                    @click="loginMode = 'provider'; loginError = ''"
+                    :class="loginMode === 'provider' ? 'bg-white shadow-sm font-semibold text-slate-900' : 'text-slate-500'"
+                    class="flex-1 py-2 rounded-md transition-all">Provider</button>
+            </div>
+
+            <form @submit.prevent="submitLogin()" class="space-y-4">
+                <template x-if="loginMode === 'admin'">
+                    <div class="space-y-3">
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Username</label>
+                            <input type="text" x-model="loginForm.username" class="input mt-1" required autofocus />
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Password</label>
+                            <input type="password" x-model="loginForm.password" class="input mt-1" required />
+                        </div>
+                    </div>
+                </template>
+                <template x-if="loginMode === 'provider'">
+                    <div class="space-y-3">
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Provider</label>
+                            <select x-model="providerLoginForm.name" class="select mt-1" required>
+                                <option value="" disabled>Select your name</option>
+                                <template x-for="p in providerOptions" :key="p.id">
+                                    <option :value="p.name" x-text="p.name"></option>
+                                </template>
+                            </select>
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Password</label>
+                            <input type="password" x-model="providerLoginForm.password" class="input mt-1" required />
+                        </div>
+                    </div>
+                </template>
+
+                <template x-if="loginError">
+                    <div class="text-sm text-red-600 bg-red-50 border border-red-200 rounded-lg px-3 py-2" x-text="loginError"></div>
+                </template>
+
+                <button type="submit" class="btn btn-primary w-full" :disabled="loginBusy">
+                    <span x-show="!loginBusy">Sign In</span>
+                    <span x-show="loginBusy" class="spinner"></span>
+                </button>
+            </form>
+        </div>
+    </div>
+</template>
+
+<!-- ============================================================ -->
+<!-- DASHBOARD SHELL -->
+<!-- ============================================================ -->
+<template x-if="authenticated">
+<div class="flex min-h-screen">
+    <!-- Sidebar -->
+    <aside class="sidebar w-64 flex-shrink-0 hidden md:flex flex-col text-slate-300">
+        <div class="px-6 py-6 border-b border-white/10">
+            <div class="flex items-center gap-3">
+                <div class="w-10 h-10 rounded-xl bg-blue-600 text-white flex items-center justify-center font-bold">SOS</div>
+                <div>
+                    <div class="text-white font-semibold">SOS Care Now</div>
+                    <div class="text-xs text-slate-400">Scheduling</div>
+                </div>
+            </div>
+        </div>
+        <nav class="flex-1 px-3 py-4 space-y-1">
+            <template x-if="userRole === 'admin'">
+                <div>
+                    <div class="sidebar-link" :class="view === 'schedule' && 'active'" @click="view = 'schedule'">
+                        <span>📅</span><span>Schedule Visit</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'providers' && 'active'" @click="view = 'providers'">
+                        <span>🩺</span><span>Providers</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'patients' && 'active'" @click="view = 'patients'">
+                        <span>👥</span><span>Patients</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'appointments' && 'active'" @click="view = 'appointments'">
+                        <span>📋</span><span>Appointments</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'calendar' && 'active'" @click="view = 'calendar'">
+                        <span>🗓️</span><span>Calendar</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'audit' && 'active'" @click="view = 'audit'">
+                        <span>📜</span><span>Audit Log</span>
+                    </div>
+                    <div class="sidebar-link" :class="view === 'settings' && 'active'" @click="view = 'settings'">
+                        <span>⚙️</span><span>Settings</span>
+                    </div>
+                </div>
+            </template>
+            <template x-if="userRole === 'provider'">
+                <div>
+                    <div class="sidebar-link" :class="view === 'portal' && 'active'" @click="view = 'portal'">
+                        <span>👤</span><span>My Portal</span>
+                    </div>
+                </div>
+            </template>
+        </nav>
+        <div class="px-4 py-4 border-t border-white/10">
+            <div class="text-xs text-slate-400 mb-2">Logged in as</div>
+            <div class="text-white font-medium text-sm mb-3" x-text="currentUser"></div>
+            <button class="btn btn-secondary w-full" @click="logout()">Logout</button>
+        </div>
+    </aside>
+
+    <!-- Mobile top bar -->
+    <div class="md:hidden fixed top-0 left-0 right-0 z-40 bg-slate-900 text-white px-4 py-3 flex justify-between items-center">
+        <div class="font-semibold">SOS Care Now</div>
+        <div class="flex items-center gap-3">
+            <span class="text-xs text-slate-300" x-text="currentUser"></span>
+            <button class="text-xs underline" @click="logout()">Logout</button>
+        </div>
+    </div>
+
+    <!-- Main -->
+    <main class="flex-1 px-4 md:px-8 py-6 md:py-8 overflow-x-hidden mt-12 md:mt-0">
+
+        <!-- Mobile nav tabs -->
+        <div class="md:hidden mb-4 flex gap-2 overflow-x-auto pb-2" x-show="userRole === 'admin'">
+            <button class="btn btn-sm" :class="view === 'schedule' ? 'btn-primary' : 'btn-secondary'" @click="view='schedule'">Schedule</button>
+            <button class="btn btn-sm" :class="view === 'providers' ? 'btn-primary' : 'btn-secondary'" @click="view='providers'">Providers</button>
+            <button class="btn btn-sm" :class="view === 'patients' ? 'btn-primary' : 'btn-secondary'" @click="view='patients'">Patients</button>
+            <button class="btn btn-sm" :class="view === 'appointments' ? 'btn-primary' : 'btn-secondary'" @click="view='appointments'">Appointments</button>
+            <button class="btn btn-sm" :class="view === 'calendar' ? 'btn-primary' : 'btn-secondary'" @click="view='calendar'">Calendar</button>
+            <button class="btn btn-sm" :class="view === 'audit' ? 'btn-primary' : 'btn-secondary'" @click="view='audit'">Audit</button>
+            <button class="btn btn-sm" :class="view === 'settings' ? 'btn-primary' : 'btn-secondary'" @click="view='settings'">Settings</button>
+        </div>
+
+        <!-- ====================== SCHEDULE VIEW ====================== -->
+        <div x-show="view === 'schedule'" x-cloak>
+            <header class="mb-6 flex justify-between items-end flex-wrap gap-3">
+                <div>
+                    <h1 class="text-2xl font-bold">Schedule Visit</h1>
+                    <p class="text-sm text-slate-500">Match a patient to an available provider using the scheduling agent.</p>
+                </div>
+                <div class="flex gap-2">
+                    <button class="btn" :class="scheduleTab === 'new' ? 'btn-primary' : 'btn-secondary'" @click="scheduleTab = 'new'; startOver()">Schedule New Visit</button>
+                    <button class="btn" :class="scheduleTab === 'cancel' ? 'btn-primary' : 'btn-secondary'" @click="openCancelTab()">Cancel Visit</button>
+                </div>
+            </header>
+
+            <!-- NEW visit -->
+            <div x-show="scheduleTab === 'new'">
+                <!-- FORM phase -->
+                <div x-show="sched.phase === 'form'" class="card p-6">
+                    <h2 class="text-lg font-semibold mb-4">Visit Details</h2>
+                    <div class="grid md:grid-cols-2 gap-4">
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Patient</label>
+                            <select x-model="sched.patientId" @change="onPatientChange()" class="select mt-1">
+                                <option value="" disabled>Select a patient</option>
+                                <template x-for="p in patients" :key="p.id">
+                                    <option :value="p.id" x-text="p.name"></option>
+                                </template>
+                            </select>
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Visit Address</label>
+                            <input type="text" x-model="sched.address" class="input mt-1" />
+                        </div>
+                        <template x-if="selectedPatient && selectedPatient.notes">
+                            <div class="md:col-span-2">
+                                <label class="text-sm font-medium text-slate-700">Patient Notes</label>
+                                <div class="mt-1 text-sm text-slate-700 bg-amber-50 border border-amber-200 rounded-lg px-3 py-2 whitespace-pre-wrap" x-text="selectedPatient.notes"></div>
+                            </div>
+                        </template>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Visit Level</label>
+                            <select x-model="sched.visitLevel" class="select mt-1">
+                                <template x-for="v in visitLevels" :key="v.key">
+                                    <option :value="String(v.key)" x-text="`${v.label} — ${v.duration_minutes} min`"></option>
+                                </template>
+                            </select>
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Preferred Date</label>
+                            <input type="date" x-model="sched.preferredDate" :min="minSelectableDate" class="input mt-1" />
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Earliest Start</label>
+                            <select x-model="sched.timeStart" class="select mt-1">
+                                <template x-for="t in validStartTimes" :key="t">
+                                    <option :value="t" x-text="formatTime(t)"></option>
+                                </template>
+                            </select>
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Latest Start</label>
+                            <select x-model="sched.timeEnd" class="select mt-1">
+                                <template x-for="t in validEndTimes" :key="t">
+                                    <option :value="t" x-text="formatTime(t)"></option>
+                                </template>
+                            </select>
+                        </div>
+                        <template x-if="platformTimezone">
+                            <div class="md:col-span-2 text-xs text-slate-500">
+                                <span x-text="`All times shown are in ${platformTimezoneLabel} time.`"></span>
+                            </div>
+                        </template>
+                        <template x-if="validStartTimes.length === 0">
+                            <div class="md:col-span-2 text-sm text-amber-700 bg-amber-50 border border-amber-200 rounded-lg px-3 py-2">
+                                <span x-text="`No appointment times on this date meet the ${minLeadTimeHours}-hour lead time requirement. Pick a later date.`"></span>
+                            </div>
+                        </template>
+                    </div>
+                    <div class="mt-6 flex justify-end">
+                        <button class="btn btn-primary" @click="findMatches()" :disabled="loading">
+                            <span x-show="!loading">Find Matches</span>
+                            <span x-show="loading" class="spinner"></span>
+                        </button>
+                    </div>
+                </div>
+
+                <!-- MATCHES phase -->
+                <div x-show="sched.phase === 'matches'" class="card p-6">
+                    <div class="flex justify-between items-center mb-4">
+                        <h2 class="text-lg font-semibold">Available Matches <span class="text-slate-400 font-normal text-sm" x-text="`(${matchesCount} found)`"></span></h2>
+                        <div class="flex gap-2">
+                            <button class="btn btn-ghost btn-sm" @click="backToForm()">← Back</button>
+                            <button class="btn btn-ghost btn-sm" @click="startOver()">Start Over</button>
+                        </div>
+                    </div>
+
+                    <div class="space-y-3">
+                        <template x-for="group in groupedMatches" :key="group.provider_id">
+                            <div class="border border-slate-200 rounded-xl overflow-hidden">
+                                <div class="px-4 py-3 bg-slate-50 flex justify-between items-center">
+                                    <div class="flex items-center gap-2">
+                                        <template x-if="group.is_oncall"><span class="badge badge-emerald">🟢 ON CALL</span></template>
+                                        <span class="font-semibold" x-text="group.name"></span>
+                                    </div>
+                                    <span class="text-sm text-slate-500" x-text="`${group.min_travel} min travel`"></span>
+                                </div>
+                                <div class="p-3 grid sm:grid-cols-2 gap-3">
+                                    <template x-for="slot in group.slots" :key="slot.idx">
+                                        <div class="match-card" :class="sched.selectedIdx === slot.idx && 'selected'" @click="selectSlot(slot.idx)">
+                                            <div class="font-semibold" x-text="`${formatTime(slot.start_time)} – ${formatTime(slot.end_time)}`"></div>
+                                            <div class="text-xs text-slate-500 mt-1" x-text="formatDate(slot.date)"></div>
+                                            <div class="text-xs text-slate-500 mt-1">
+                                                <span x-text="`${slot.travel_time_minutes} min travel`"></span>
+                                                <template x-if="slot.recommended_departure_time">
+                                                    <span> · depart by <span x-text="formatTime(slot.recommended_departure_time)"></span></span>
+                                                </template>
+                                                <template x-if="slot.has_nearby_visits"><span class="ml-1 badge badge-blue">nearby visits</span></template>
+                                            </div>
+                                        </div>
+                                    </template>
+                                </div>
+                            </div>
+                        </template>
+                    </div>
+
+                    <div class="mt-6 flex justify-between items-center">
+                        <div class="text-sm text-slate-600">
+                            <template x-if="sched.selectedIdx !== null">
+                                <span>Selected: <strong x-text="sched.matches[sched.selectedIdx]?.provider_name"></strong> on <span x-text="formatDate(sched.matches[sched.selectedIdx]?.date)"></span> at <span x-text="formatTime(sched.matches[sched.selectedIdx]?.start_time)"></span></span>
+                            </template>
+                            <template x-if="sched.selectedIdx === null">
+                                <span class="text-slate-400">Select a slot to continue</span>
+                            </template>
+                        </div>
+                        <button class="btn btn-primary" :disabled="sched.selectedIdx === null || loading" @click="bookAppointment()">
+                            <span x-show="!loading">Book Appointment</span>
+                            <span x-show="loading" class="spinner"></span>
+                        </button>
+                    </div>
+                </div>
+
+                <!-- BOOKED phase -->
+                <div x-show="sched.phase === 'booked'" class="card p-8 text-center">
+                    <div class="w-16 h-16 mx-auto rounded-full bg-green-100 text-green-600 flex items-center justify-center text-3xl mb-4">✓</div>
+                    <h2 class="text-xl font-semibold mb-2">Appointment booked!</h2>
+                    <p class="text-slate-600 mb-4">
+                        <strong x-text="sched.bookedAppt?.provider_name"></strong> will visit
+                        <strong x-text="sched.bookedAppt?.patient_name"></strong> on
+                        <span x-text="formatDate(sched.bookedAppt?.date)"></span> at
+                        <span x-text="formatTime(sched.bookedAppt?.start_time)"></span>.
+                    </p>
+                    <template x-if="sched.bookedAppt?.recommended_departure_time">
+                        <p class="text-sm text-slate-500">Recommended departure: <span x-text="formatTime(sched.bookedAppt?.recommended_departure_time)"></span></p>
+                    </template>
+                    <template x-if="sched.notificationsSent">
+                        <p class="text-sm text-blue-600 mt-2">Confirmation emails sent.</p>
+                    </template>
+                    <div class="mt-6">
+                        <button class="btn btn-primary" @click="startOver()">Schedule Another Visit</button>
+                    </div>
+                </div>
+
+                <!-- ERROR phase -->
+                <div x-show="sched.phase === 'error'" class="card p-8 text-center">
+                    <div class="w-16 h-16 mx-auto rounded-full bg-red-100 text-red-600 flex items-center justify-center text-3xl mb-4">!</div>
+                    <h2 class="text-xl font-semibold mb-2">Could not schedule</h2>
+                    <p class="text-slate-600" x-text="sched.error"></p>
+                    <div class="mt-6 flex justify-center gap-2">
+                        <button class="btn btn-ghost" @click="backToForm()">← Back</button>
+                        <button class="btn btn-primary" @click="startOver()">Start Over</button>
+                    </div>
+                </div>
+            </div>
+
+            <!-- CANCEL visit tab -->
+            <div x-show="scheduleTab === 'cancel'" class="card p-6">
+                <h2 class="text-lg font-semibold mb-4">Cancel an Appointment</h2>
+                <template x-if="appointments.length === 0">
+                    <p class="text-sm text-slate-500">No future scheduled appointments.</p>
+                </template>
+
+                <div x-show="appointments.length > 0">
+                    <div class="grid md:grid-cols-2 gap-4 mb-4">
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Filter by Patient</label>
+                            <select x-model="cancel.patientFilter" class="select mt-1">
+                                <option value="All">All</option>
+                                <template x-for="p in patients" :key="p.id"><option :value="p.name" x-text="p.name"></option></template>
+                            </select>
+                        </div>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">Filter by Provider</label>
+                            <select x-model="cancel.providerFilter" class="select mt-1">
+                                <option value="All">All</option>
+                                <template x-for="p in providers" :key="p.id"><option :value="p.name" x-text="p.name"></option></template>
+                            </select>
+                        </div>
+                    </div>
+
+                    <div class="table-wrap border border-slate-200 mb-4">
+                        <table class="table">
+                            <thead>
+                                <tr><th></th><th>Date</th><th>Time</th><th>Patient</th><th>Provider</th><th>Level</th></tr>
+                            </thead>
+                            <tbody>
+                                <template x-for="a in filteredCancelAppts" :key="a.id">
+                                    <tr :class="cancel.selectedId === a.id && 'bg-blue-50'" class="cursor-pointer" @click="cancel.selectedId = a.id">
+                                        <td><input type="radio" :checked="cancel.selectedId === a.id" /></td>
+                                        <td x-text="formatDateShort(a.date)"></td>
+                                        <td x-text="`${formatTime(a.start_time)} – ${formatTime(a.end_time)}`"></td>
+                                        <td x-text="a.patient_name"></td>
+                                        <td x-text="a.provider_name"></td>
+                                        <td x-text="a.visit_level"></td>
+                                    </tr>
+                                </template>
+                            </tbody>
+                        </table>
+                    </div>
+
+                    <div class="flex justify-end">
+                        <button class="btn btn-danger" @click="cancelAppointment()" :disabled="!cancel.selectedId || loading">
+                            <span x-show="!loading">Cancel Appointment</span>
+                            <span x-show="loading" class="spinner"></span>
+                        </button>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        <!-- ====================== PROVIDERS VIEW ====================== -->
+        <div x-show="view === 'providers'" x-cloak>
+            <header class="mb-6 flex justify-between items-end flex-wrap gap-3">
+                <div>
+                    <h1 class="text-2xl font-bold">Provider Management</h1>
+                    <p class="text-sm text-slate-500">Manage providers, availability, and on-call assignments.</p>
+                </div>
+                <button class="btn btn-primary" @click="openAddProvider()">+ Add Provider</button>
+            </header>
+
+            <!-- One unified card per provider. Click "Edit Availability" to expand the editor. -->
+            <template x-for="p in providers" :key="p.id">
+                <div class="card p-6 mb-4">
+                    <!-- Header: name + category + actions -->
+                    <div class="flex justify-between items-start gap-4 mb-4 flex-wrap">
+                        <div>
+                            <div class="flex items-center gap-2 mb-1">
+                                <h3 class="text-lg font-semibold" x-text="p.name"></h3>
+                                <span class="badge" :class="p.category === 'nurse' ? 'badge-blue' : 'badge-slate'" x-text="p.category"></span>
+                            </div>
+                            <p class="text-sm text-slate-500" x-text="p.email || '—'"></p>
+                        </div>
+                        <div class="flex gap-1 flex-wrap">
+                            <button class="btn btn-ghost btn-sm" @click="openEditProvider(p)">Edit Details</button>
+                            <button class="btn btn-secondary btn-sm" @click="prov.expandedId = (prov.expandedId === p.id ? null : p.id)">
+                                <span x-text="prov.expandedId === p.id ? 'Hide Availability' : 'Edit Availability'"></span>
+                            </button>
+                            <button class="btn btn-ghost btn-sm text-red-600" @click="prov.confirmDelete = p.id">Delete</button>
+                        </div>
+                    </div>
+
+                    <!-- Summary (always visible) -->
+                    <div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-5 gap-4 text-sm">
+                        <div>
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">Hours</div>
+                            <div x-text="`${p.work_hours?.start || '—'}–${p.work_hours?.end || ''}`"></div>
+                        </div>
+                        <div>
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">Lunch</div>
+                            <div x-text="`${p.lunch_break?.start || '—'}–${p.lunch_break?.end || ''}`"></div>
+                        </div>
+                        <div>
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">Levels</div>
+                            <div x-text="(p.service_levels || []).join(', ') || '—'"></div>
+                        </div>
+                        <div>
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">Standing Off</div>
+                            <div x-text="(p.recurring_days_off || []).join(', ') || '—'"></div>
+                        </div>
+                        <div>
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">On-Call</div>
+                            <template x-if="(p.on_call || []).length">
+                                <div class="flex flex-wrap gap-1">
+                                    <template x-for="d in (p.on_call || [])" :key="d">
+                                        <span class="badge badge-emerald" x-text="fmt.dateShort(d)"></span>
+                                    </template>
+                                </div>
+                            </template>
+                            <template x-if="!(p.on_call || []).length"><span class="text-slate-400">—</span></template>
+                        </div>
+                        <div class="col-span-2 md:col-span-3 lg:col-span-5">
+                            <div class="text-xs uppercase tracking-wide text-slate-500 mb-1">Unavailable Blocks</div>
+                            <template x-if="!upcomingBlocks(p).length"><span class="text-slate-400">—</span></template>
+                            <template x-if="upcomingBlocks(p).length">
+                                <div class="flex flex-wrap gap-1">
+                                    <template x-for="entry in upcomingBlocks(p)" :key="entry.originalIndex">
+                                        <span class="badge badge-slate" x-text="formatBlockShort(entry.block)"></span>
+                                    </template>
+                                </div>
+                            </template>
+                        </div>
+                    </div>
+
+                    <!-- Availability editor (only when expanded) -->
+                    <template x-if="prov.expandedId === p.id">
+                        <div class="mt-6 pt-6 border-t border-slate-200">
+                            <!-- Standing days off -->
+                            <div class="mb-5">
+                                <div class="text-sm font-semibold mb-2">Standing days off (every week)</div>
+                                <div class="flex flex-wrap gap-2">
+                                    <template x-for="d in ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday']" :key="d">
+                                        <button
+                                            class="btn btn-sm"
+                                            :class="(p.recurring_days_off || []).includes(d) ? 'btn-primary' : 'btn-secondary'"
+                                            @click="toggleRecurringDay(p, d)" x-text="d">
+                                        </button>
+                                    </template>
+                                    <button class="btn btn-sm btn-secondary ml-auto" @click="saveRecurringDaysOff(p)">Save</button>
+                                </div>
+                            </div>
+
+                            <!-- Unavailable blocks (upcoming only) -->
+                            <div class="mb-5">
+                                <div class="text-sm font-semibold mb-2">Unavailable Blocks</div>
+                                <div class="space-y-1 mb-3">
+                                    <template x-if="!upcomingBlocks(p).length"><p class="text-xs text-slate-400">None scheduled.</p></template>
+                                    <template x-for="entry in upcomingBlocks(p)" :key="entry.originalIndex">
+                                        <div class="flex items-center justify-between text-sm bg-slate-50 px-3 py-2 rounded-lg">
+                                            <span x-text="formatBlock(entry.block)"></span>
+                                            <button class="btn btn-ghost btn-sm text-red-600" @click="removeBlock(p.id, entry.originalIndex)">Remove</button>
+                                        </div>
+                                    </template>
+                                </div>
+                                <div class="bg-slate-50 rounded-lg p-3 grid sm:grid-cols-4 gap-2 items-end">
+                                    <div>
+                                        <label class="text-xs text-slate-600">Type</label>
+                                        <select x-model="prov.newBlockType" class="select"><option>All Day</option><option>Specific Time</option></select>
+                                    </div>
+                                    <div>
+                                        <label class="text-xs text-slate-600">Date</label>
+                                        <input type="date" x-model="prov.newBlock.date" class="input" />
+                                    </div>
+                                    <div>
+                                        <label class="text-xs text-slate-600">Reason</label>
+                                        <input type="text" x-model="prov.newBlock.title" class="input" placeholder="Unavailable" />
+                                    </div>
+                                    <div>
+                                        <button class="btn btn-secondary w-full" @click="addBlock(p)">Add Block</button>
+                                    </div>
+                                    <template x-if="prov.newBlockType === 'Specific Time'">
+                                        <div class="sm:col-span-4 grid grid-cols-2 gap-2">
+                                            <div>
+                                                <label class="text-xs text-slate-600">Start</label>
+                                                <input type="time" x-model="prov.newBlock.start_time" class="input" />
+                                            </div>
+                                            <div>
+                                                <label class="text-xs text-slate-600">End</label>
+                                                <input type="time" x-model="prov.newBlock.end_time" class="input" />
+                                            </div>
+                                        </div>
+                                    </template>
+                                </div>
+                            </div>
+
+                            <!-- On-Call -->
+                            <div>
+                                <div class="text-sm font-semibold mb-1">On-Call</div>
+                                <p class="text-xs text-slate-500 mb-2">24-hour window from 07:00 to next day 07:00. Within this window, the provider supersedes all blocks and is ranked first.</p>
+                                <div class="space-y-1 mb-3">
+                                    <template x-if="!(p.on_call || []).length"><p class="text-xs text-slate-400">No on-call days scheduled.</p></template>
+                                    <template x-for="d in (p.on_call || [])" :key="d">
+                                        <div class="flex items-center justify-between bg-emerald-50 px-3 py-2 rounded-lg">
+                                            <div class="flex items-center gap-3">
+                                                <div class="toggle on" @click="toggleOnCallDate(p, d)"></div>
+                                                <span class="text-sm font-medium" x-text="`${d} — 07:00 → next day 07:00`"></span>
+                                            </div>
+                                            <button class="btn btn-ghost btn-sm text-red-600" @click="removeOnCall(p.id, d)">Remove</button>
+                                        </div>
+                                    </template>
+                                </div>
+                                <div class="flex gap-2 items-end">
+                                    <div class="flex-1">
+                                        <label class="text-xs text-slate-600">Add on-call date</label>
+                                        <input type="date" x-model="prov.newOnCallDate" class="input" />
+                                    </div>
+                                    <button class="btn btn-secondary" @click="addOnCall(p)">Add On-Call Day</button>
+                                </div>
+                            </div>
+                        </div>
+                    </template>
+
+                    <!-- Delete confirm -->
+                    <template x-if="prov.confirmDelete === p.id">
+                        <div class="mt-4 p-4 bg-red-50 border border-red-200 rounded-lg">
+                            <p class="text-sm text-red-800 mb-3">
+                                Delete <strong x-text="p.name"></strong>? Existing appointments will reference a missing provider. Cannot be undone.
+                            </p>
+                            <div class="flex gap-2 justify-end">
+                                <button class="btn btn-secondary btn-sm" @click="prov.confirmDelete = null">Cancel</button>
+                                <button class="btn btn-danger btn-sm" @click="deleteProvider(p.id)">Yes, Delete</button>
+                            </div>
+                        </div>
+                    </template>
+                </div>
+            </template>
+        </div>
+
+        <!-- ====================== PATIENTS VIEW ====================== -->
+        <div x-show="view === 'patients'" x-cloak>
+            <header class="mb-6 flex justify-between items-end flex-wrap gap-3">
+                <div>
+                    <h1 class="text-2xl font-bold">Patients</h1>
+                    <p class="text-sm text-slate-500">Manage patient records. Addresses are geocoded on save.</p>
+                </div>
+                <button class="btn btn-primary" @click="openAddPatient()">+ Add Patient</button>
+            </header>
+
+            <div class="card overflow-hidden">
+                <div class="table-wrap">
+                    <table class="table">
+                        <thead>
+                            <tr><th>Name</th><th>Email</th><th>Address</th><th>Notes</th><th></th></tr>
+                        </thead>
+                        <tbody>
+                            <template x-for="p in patients" :key="p.id">
+                                <tr>
+                                    <td class="font-medium" x-text="p.name"></td>
+                                    <td class="text-slate-500" x-text="p.email"></td>
+                                    <td x-text="p.address"></td>
+                                    <td class="text-slate-500 max-w-xs truncate" x-text="p.notes"></td>
+                                    <td>
+                                        <div class="flex gap-1">
+                                            <button class="btn btn-ghost btn-sm" @click="openEditPatient(p)">Edit</button>
+                                            <button class="btn btn-ghost btn-sm text-red-600" @click="pat.confirmDelete = p.id">Delete</button>
+                                        </div>
+                                    </td>
+                                </tr>
+                            </template>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+
+            <!-- Delete confirm -->
+            <template x-if="pat.confirmDelete">
+                <div class="modal-backdrop" @click.self="pat.confirmDelete = null">
+                    <div class="modal p-6">
+                        <h3 class="font-semibold mb-2">Delete patient?</h3>
+                        <p class="text-sm text-slate-600 mb-4">This cannot be undone. Existing appointments will reference a missing patient.</p>
+                        <div class="flex gap-2 justify-end">
+                            <button class="btn btn-secondary" @click="pat.confirmDelete = null">Cancel</button>
+                            <button class="btn btn-danger" @click="deletePatient(pat.confirmDelete)">Delete</button>
+                        </div>
+                    </div>
+                </div>
+            </template>
+        </div>
+
+        <!-- ====================== APPOINTMENTS VIEW ====================== -->
+        <div x-show="view === 'appointments'" x-cloak>
+            <header class="mb-6">
+                <h1 class="text-2xl font-bold">Appointments</h1>
+                <p class="text-sm text-slate-500">All scheduled, completed, and cancelled visits.</p>
+            </header>
+            <div class="card p-6">
+                <div class="grid md:grid-cols-3 gap-4 mb-4">
+                    <div>
+                        <label class="text-sm font-medium text-slate-700">Status</label>
+                        <select x-model="apptView.statusFilter" class="select mt-1">
+                            <option value="All">All</option>
+                            <option value="scheduled">Scheduled</option>
+                            <option value="completed">Completed</option>
+                            <option value="cancelled">Cancelled</option>
+                        </select>
+                    </div>
+                    <div>
+                        <label class="text-sm font-medium text-slate-700">Patient</label>
+                        <select x-model="apptView.patientFilter" class="select mt-1">
+                            <option value="All">All</option>
+                            <template x-for="p in patients" :key="p.id"><option :value="p.name" x-text="p.name"></option></template>
+                        </select>
+                    </div>
+                    <div>
+                        <label class="text-sm font-medium text-slate-700">Provider</label>
+                        <select x-model="apptView.providerFilter" class="select mt-1">
+                            <option value="All">All</option>
+                            <template x-for="p in providers" :key="p.id"><option :value="p.name" x-text="p.name"></option></template>
+                        </select>
+                    </div>
+                </div>
+
+                <template x-if="platformTimezone">
+                    <div class="text-xs text-slate-500 mb-2">
+                        <span x-text="`All times shown are in ${platformTimezoneLabel} time.`"></span>
+                    </div>
+                </template>
+
+                <template x-if="filteredAppointmentsList.length === 0">
+                    <p class="text-sm text-slate-500">No appointments match these filters.</p>
+                </template>
+
+                <div x-show="filteredAppointmentsList.length > 0" class="table-wrap border border-slate-200">
+                    <table class="table">
+                        <thead>
+                            <tr>
+                                <th>Status</th>
+                                <th>Date</th>
+                                <th>Time</th>
+                                <th>Patient</th>
+                                <th>Provider</th>
+                                <th>Level</th>
+                                <th>Address</th>
+                            </tr>
+                        </thead>
+                        <tbody>
+                            <template x-for="a in filteredAppointmentsList" :key="a.id">
+                                <tr>
+                                    <td><span :class="statusBadgeClass(a.status)" x-text="(a.status || 'scheduled')"></span></td>
+                                    <td x-text="formatDateShort(a.date)"></td>
+                                    <td x-text="`${formatTime(a.start_time)} – ${formatTime(a.end_time)}`"></td>
+                                    <td x-text="a.patient_name"></td>
+                                    <td x-text="a.provider_name"></td>
+                                    <td x-text="a.visit_level"></td>
+                                    <td class="text-xs text-slate-500" x-text="a.visit_address"></td>
+                                </tr>
+                            </template>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+
+        <!-- ====================== CALENDAR VIEW ====================== -->
+        <div x-show="view === 'calendar'" x-cloak>
+            <header class="mb-6">
+                <h1 class="text-2xl font-bold">Calendar</h1>
+                <p class="text-sm text-slate-500">All scheduled visits and unavailability across providers.</p>
+            </header>
+
+            <div class="grid lg:grid-cols-[260px_1fr] gap-6">
+                <div class="card p-4 h-fit">
+                    <h3 class="font-semibold mb-3 text-sm">Providers</h3>
+                    <button class="btn btn-secondary btn-sm w-full mb-3" @click="toggleAllProviders()">
+                        <span x-show="cal.selectedProviderIds.length === providers.length">Deselect All</span>
+                        <span x-show="cal.selectedProviderIds.length !== providers.length">Select All</span>
+                    </button>
+                    <div class="space-y-2 mb-4">
+                        <template x-for="p in providers" :key="p.id">
+                            <label class="flex items-center gap-2 text-sm cursor-pointer">
+                                <input type="checkbox" :checked="cal.selectedProviderIds.includes(p.id)" @change="toggleCalProvider(p.id)" />
+                                <span class="w-3 h-3 rounded-full" :style="`background-color: ${(cal.providerLegend.find(x => x.id === p.id) || {}).color || '#94a3b8'}`"></span>
+                                <span x-text="p.name"></span>
+                            </label>
+                        </template>
+                    </div>
+                    <hr class="my-3 border-slate-200" />
+                    <label class="flex items-center gap-2 text-sm cursor-pointer mb-2">
+                        <input type="checkbox" x-model="cal.showUnavailable" @change="refetchCalendar()" />
+                        <span>Show unavailable blocks</span>
+                    </label>
+                    <label class="flex items-center gap-2 text-sm cursor-pointer mb-2">
+                        <input type="checkbox" x-model="cal.showTravel" @change="refetchCalendar()" />
+                        <span>Show travel time</span>
+                    </label>
+                    <label class="flex items-center gap-2 text-sm cursor-pointer">
+                        <input type="checkbox" x-model="cal.showOnCall" @change="refetchCalendar()" />
+                        <span>Show on-call</span>
+                    </label>
+                </div>
+
+                <div class="card p-4">
+                    <template x-if="platformTimezone">
+                        <div class="text-xs text-slate-500 mb-2">
+                            <span x-text="`All times shown are in ${platformTimezoneLabel} time.`"></span>
+                        </div>
+                    </template>
+                    <div id="calendar-root"></div>
+                </div>
+            </div>
+
+            <!-- Event detail modal -->
+            <template x-if="cal.selectedEvent">
+                <div class="modal-backdrop" @click.self="cal.selectedEvent = null">
+                    <div class="modal p-6">
+                        <div class="flex justify-between items-start mb-4">
+                            <div>
+                                <h3 class="font-semibold" x-text="cal.selectedEvent.title"></h3>
+                                <p class="text-xs text-slate-500" x-text="cal.selectedEvent.type"></p>
+                            </div>
+                            <button class="btn btn-ghost btn-sm" @click="cal.selectedEvent = null">✕</button>
+                        </div>
+                        <template x-if="cal.selectedEvent.type === 'appointment'">
+                            <div class="space-y-2 text-sm">
+                                <div><span class="text-slate-500">Patient:</span> <strong x-text="cal.selectedEvent.patient_name"></strong></div>
+                                <div><span class="text-slate-500">Provider:</span> <strong x-text="cal.selectedEvent.provider_name"></strong></div>
+                                <div><span class="text-slate-500">Date:</span> <span x-text="formatDate(cal.selectedEvent.date)"></span></div>
+                                <div><span class="text-slate-500">Time:</span> <span x-text="`${formatTime(cal.selectedEvent.start_time)} – ${formatTime(cal.selectedEvent.end_time)}`"></span></div>
+                                <div><span class="text-slate-500">Level:</span> <span x-text="cal.selectedEvent.visit_level"></span></div>
+                                <div><span class="text-slate-500">Address:</span> <span x-text="cal.selectedEvent.visit_address"></span></div>
+                                <template x-if="cal.selectedEvent.recommended_departure_time">
+                                    <div><span class="text-slate-500">Depart by:</span> <span x-text="formatTime(cal.selectedEvent.recommended_departure_time)"></span></div>
+                                </template>
+                            </div>
+                        </template>
+                        <template x-if="cal.selectedEvent.type === 'days_off'">
+                            <div class="text-sm">
+                                <div><span class="text-slate-500">Provider:</span> <strong x-text="cal.selectedEvent.provider_name"></strong></div>
+                                <div><span class="text-slate-500">Reason:</span> <span x-text="cal.selectedEvent.title"></span></div>
+                            </div>
+                        </template>
+                        <template x-if="cal.selectedEvent.type === 'on_call'">
+                            <div class="text-sm">
+                                <p>Provider is on-call for this 24-hour window.</p>
+                            </div>
+                        </template>
+                    </div>
+                </div>
+            </template>
+        </div>
+
+        <!-- ====================== AUDIT LOG VIEW ====================== -->
+        <div x-show="view === 'audit'" x-cloak>
+            <header class="mb-6">
+                <h1 class="text-2xl font-bold">Audit Log</h1>
+                <p class="text-sm text-slate-500">All system actions, newest first.</p>
+            </header>
+
+            <div class="card p-4 mb-4">
+                <div class="grid md:grid-cols-3 gap-3">
+                    <div>
+                        <label class="text-sm font-medium text-slate-700">Search</label>
+                        <input type="text" x-model.debounce.300ms="audit.search" @input="refreshAudit()" class="input mt-1" placeholder="Search details, user, action..." />
+                    </div>
+                    <div>
+                        <label class="text-sm font-medium text-slate-700">Action Type</label>
+                        <select x-model="audit.action" @change="refreshAudit()" class="select mt-1">
+                            <option>All</option>
+                            <template x-for="a in audit.actionTypes" :key="a"><option :value="a" x-text="a"></option></template>
+                        </select>
+                    </div>
+                    <div class="flex items-end">
+                        <button class="btn btn-secondary w-full" @click="refreshAudit()">Refresh</button>
+                    </div>
+                </div>
+            </div>
+
+            <div class="card overflow-hidden">
+                <div class="table-wrap">
+                    <table class="table">
+                        <thead>
+                            <tr><th>Timestamp</th><th>User</th><th>Action</th><th>Details</th></tr>
+                        </thead>
+                        <tbody>
+                            <template x-for="(e, i) in audit.entries" :key="i">
+                                <tr>
+                                    <td class="text-slate-500" x-text="formatTs(e.timestamp)"></td>
+                                    <td x-text="e.user"></td>
+                                    <td><span class="badge badge-slate" x-text="e.action"></span></td>
+                                    <td x-text="e.details"></td>
+                                </tr>
+                            </template>
+                            <template x-if="audit.entries.length === 0">
+                                <tr><td colspan="4" class="text-center text-slate-400">No entries.</td></tr>
+                            </template>
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+        </div>
+
+        <!-- ====================== SETTINGS VIEW ====================== -->
+        <div x-show="view === 'settings'" x-cloak>
+            <header class="mb-6">
+                <h1 class="text-2xl font-bold">Settings</h1>
+                <p class="text-sm text-slate-500">Tune scheduling behavior. Changes apply to the next scheduling action.</p>
+            </header>
+
+            <template x-if="!sett.form">
+                <div class="card p-6 text-slate-400 text-sm">Loading settings…</div>
+            </template>
+
+            <template x-if="sett.form">
+                <div class="space-y-4">
+                    <!-- Scheduling rules -->
+                    <div class="card p-6">
+                        <h3 class="font-semibold mb-1">Scheduling rules</h3>
+                        <p class="text-xs text-slate-500 mb-4">Used by the agent to determine when and how appointments can be booked.</p>
+                        <div class="grid md:grid-cols-2 gap-4">
+                            <div>
+                                <label class="text-sm font-medium text-slate-700">Minimum lead time (hours)</label>
+                                <input type="number" min="0" max="168" step="1" x-model.number="sett.form.min_lead_time_hours" class="input mt-1" />
+                                <p class="text-xs text-slate-500 mt-1">Earliest an appointment can be scheduled relative to now.</p>
+                            </div>
+                            <div>
+                                <label class="text-sm font-medium text-slate-700">Buffer between visits (minutes)</label>
+                                <input type="number" min="0" max="120" step="5" x-model.number="sett.form.buffer_minutes" class="input mt-1" />
+                                <p class="text-xs text-slate-500 mt-1">Extra time blocked after every visit, on top of travel time.</p>
+                            </div>
+                            <div class="md:col-span-2">
+                                <label class="text-sm font-medium text-slate-700">On-call window start hour (HH:MM)</label>
+                                <input type="text" x-model="sett.form.on_call_start_hour" placeholder="07:00" class="input mt-1" />
+                                <p class="text-xs text-slate-500 mt-1">Start of the 24-hour on-call window. Default 07:00 (07:00 → next day 07:00).</p>
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Visit levels -->
+                    <div class="card p-6">
+                        <h3 class="font-semibold mb-1">Visit level durations</h3>
+                        <p class="text-xs text-slate-500 mb-4">Edit the duration in minutes for each visit level. Labels stay fixed.</p>
+                        <div class="space-y-3">
+                            <template x-for="lvl in visitLevelEntries" :key="lvl.key">
+                                <div class="flex items-center gap-4">
+                                    <div class="w-32">
+                                        <div class="font-medium" x-text="lvl.label"></div>
+                                        <div class="text-xs text-slate-400" x-text="`key: ${lvl.key}`"></div>
+                                    </div>
+                                    <div class="flex-1 max-w-xs">
+                                        <div class="flex items-center gap-2">
+                                            <input
+                                                type="number" min="5" max="480" step="5"
+                                                :value="lvl.duration_minutes"
+                                                @input="updateVisitLevelDuration(lvl.key, $event.target.value)"
+                                                class="input" />
+                                            <span class="text-sm text-slate-500">minutes</span>
+                                        </div>
+                                    </div>
+                                </div>
+                            </template>
+                        </div>
+                    </div>
+
+                    <!-- Regional / locale -->
+                    <div class="card p-6">
+                        <h3 class="font-semibold mb-1">Region & locale</h3>
+                        <p class="text-xs text-slate-500 mb-4">⚠️ Changing the timezone affects how appointment times are interpreted by Google Calendar and email .ics invites going forward. Existing appointment records keep their original times.</p>
+                        <div class="grid md:grid-cols-3 gap-4">
+                            <div>
+                                <label class="text-sm font-medium text-slate-700">Region name</label>
+                                <input type="text" x-model="sett.form.region_name" class="input mt-1" />
+                            </div>
+                            <div>
+                                <label class="text-sm font-medium text-slate-700">Timezone</label>
+                                <select x-model="sett.form.timezone" class="select mt-1">
+                                    <template x-for="tz in timezoneOptions" :key="tz.key">
+                                        <option :value="tz.key" x-text="tz.label"></option>
+                                    </template>
+                                </select>
+                            </div>
+                            <div>
+                                <label class="text-sm font-medium text-slate-700">Service area</label>
+                                <input type="text" x-model="sett.form.service_area" class="input mt-1" />
+                            </div>
+                        </div>
+                    </div>
+
+                    <!-- Agent model -->
+                    <div class="card p-6">
+                        <h3 class="font-semibold mb-1">Agent model</h3>
+                        <p class="text-xs text-slate-500 mb-4">Used by the no-match suggestion node. Server restart required for the LLM client to pick up the change.</p>
+                        <div>
+                            <label class="text-sm font-medium text-slate-700">OpenAI model name</label>
+                            <input type="text" x-model="sett.form.openai_model" class="input mt-1" />
+                        </div>
+                    </div>
+
+                    <!-- Actions -->
+                    <div class="flex justify-end gap-2">
+                        <button class="btn btn-secondary" @click="resetSettings()">Reset to Defaults</button>
+                        <button class="btn btn-primary" @click="saveSettings()" :disabled="sett.saving">
+                            <span x-show="!sett.saving">Save Settings</span>
+                            <span x-show="sett.saving" class="spinner"></span>
+                        </button>
+                    </div>
+
+                    <!-- Reference table -->
+                    <details class="card p-4">
+                        <summary class="cursor-pointer text-sm font-medium text-slate-600">Current effective values</summary>
+                        <div class="table-wrap mt-3">
+                            <table class="table">
+                                <thead><tr><th>Setting</th><th>Current</th><th>Default</th></tr></thead>
+                                <tbody>
+                                    <template x-for="key in Object.keys(sett.current || {})" :key="key">
+                                        <tr>
+                                            <td class="font-mono text-xs" x-text="key"></td>
+                                            <td x-text="typeof sett.current[key] === 'object' ? JSON.stringify(sett.current[key]) : sett.current[key]"></td>
+                                            <td class="text-slate-500" x-text="typeof sett.defaults[key] === 'object' ? JSON.stringify(sett.defaults[key]) : sett.defaults[key]"></td>
+                                        </tr>
+                                    </template>
+                                </tbody>
+                            </table>
+                        </div>
+                    </details>
+                </div>
+            </template>
+        </div>
+
+        <!-- ====================== PROVIDER PORTAL ====================== -->
+        <div x-show="view === 'portal'" x-cloak>
+            <header class="mb-6 flex justify-between items-end">
+                <div>
+                    <h1 class="text-2xl font-bold">Provider Portal</h1>
+                    <template x-if="portal.self">
+                        <p class="text-sm text-slate-500" x-text="`${portal.self.name} · ${portal.self.category}`"></p>
+                    </template>
+                </div>
+                <div class="flex gap-2">
+                    <button class="btn" :class="portal.tab === 'availability' ? 'btn-primary' : 'btn-secondary'" @click="switchPortalTab('availability')">My Availability</button>
+                    <button class="btn" :class="portal.tab === 'schedule' ? 'btn-primary' : 'btn-secondary'" @click="switchPortalTab('schedule')">My Schedule</button>
+                </div>
+            </header>
+
+            <!-- AVAILABILITY tab -->
+            <div x-show="portal.tab === 'availability'" x-cloak>
+                <template x-if="portal.self">
+                    <div class="space-y-4">
+                        <div class="card p-6">
+                            <h3 class="font-semibold mb-4">Profile</h3>
+                            <div class="grid md:grid-cols-2 gap-4">
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Email</label>
+                                    <input type="email" x-model="portal.editForm.email" class="input mt-1" />
+                                </div>
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Home Address</label>
+                                    <input type="text" x-model="portal.editForm.address" class="input mt-1" />
+                                </div>
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Work Hours Start</label>
+                                    <input type="text" x-model="portal.editForm.work_hours.start" placeholder="HH:MM" class="input mt-1" />
+                                </div>
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Work Hours End</label>
+                                    <input type="text" x-model="portal.editForm.work_hours.end" placeholder="HH:MM" class="input mt-1" />
+                                </div>
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Lunch Start</label>
+                                    <input type="text" x-model="portal.editForm.lunch_break.start" placeholder="HH:MM" class="input mt-1" />
+                                </div>
+                                <div>
+                                    <label class="text-sm font-medium text-slate-700">Lunch End</label>
+                                    <input type="text" x-model="portal.editForm.lunch_break.end" placeholder="HH:MM" class="input mt-1" />
+                                </div>
+                            </div>
+                            <div class="mt-4 flex justify-end">
+                                <button class="btn btn-primary" @click="savePortalProfile()">Save Profile</button>
+                            </div>
+                        </div>
+
+                        <div class="card p-6">
+                            <h3 class="font-semibold mb-1">Standing Days Off</h3>
+                            <p class="text-xs text-slate-500 mb-3">Recurring weekly days you are not available.</p>
+                            <div class="flex flex-wrap gap-2 mb-3">
+                                <template x-for="d in ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday']" :key="d">
+                                    <button
+                                        class="btn btn-sm"
+                                        :class="portal.editForm.recurring_days_off.includes(d) ? 'btn-primary' : 'btn-secondary'"
+                                        @click="togglePortalRecurringDay(d)" x-text="d">
+                                    </button>
+                                </template>
+                            </div>
+                            <div class="flex justify-end">
+                                <button class="btn btn-secondary btn-sm" @click="savePortalRecurring()">Save Standing Days</button>
+                            </div>
+                        </div>
+
+                        <div class="card p-6">
+                            <h3 class="font-semibold mb-3">Unavailable Blocks</h3>
+                            <div class="space-y-1 mb-3">
+                                <template x-if="!upcomingBlocks(portal.self).length"><p class="text-xs text-slate-400">None scheduled.</p></template>
+                                <template x-for="entry in upcomingBlocks(portal.self)" :key="entry.originalIndex">
+                                    <div class="flex items-center justify-between text-sm bg-slate-50 px-3 py-2 rounded-lg">
+                                        <span x-text="formatBlock(entry.block)"></span>
+                                        <button class="btn btn-ghost btn-sm text-red-600" @click="removePortalBlock(entry.originalIndex)">Remove</button>
+                                    </div>
+                                </template>
+                            </div>
+                            <div class="bg-slate-50 rounded-lg p-3 grid sm:grid-cols-4 gap-2 items-end">
+                                <div>
+                                    <label class="text-xs text-slate-600">Type</label>
+                                    <select x-model="portal.newBlockType" class="select"><option>All Day</option><option>Specific Time</option></select>
+                                </div>
+                                <div>
+                                    <label class="text-xs text-slate-600">Date</label>
+                                    <input type="date" x-model="portal.newBlock.date" class="input" />
+                                </div>
+                                <div>
+                                    <label class="text-xs text-slate-600">Reason</label>
+                                    <input type="text" x-model="portal.newBlock.title" class="input" placeholder="Unavailable" />
+                                </div>
+                                <button class="btn btn-secondary" @click="addPortalBlock()">Add Block</button>
+                                <template x-if="portal.newBlockType === 'Specific Time'">
+                                    <div class="sm:col-span-4 grid grid-cols-2 gap-2">
+                                        <div>
+                                            <label class="text-xs text-slate-600">Start</label>
+                                            <input type="time" x-model="portal.newBlock.start_time" class="input" />
+                                        </div>
+                                        <div>
+                                            <label class="text-xs text-slate-600">End</label>
+                                            <input type="time" x-model="portal.newBlock.end_time" class="input" />
+                                        </div>
+                                    </div>
+                                </template>
+                            </div>
+                        </div>
+
+                        <div class="card p-6">
+                            <h3 class="font-semibold mb-1">On-Call</h3>
+                            <p class="text-xs text-slate-500 mb-3">24-hour window from 07:00 of the date to 07:00 the next day.</p>
+                            <div class="space-y-1 mb-3">
+                                <template x-if="!(portal.self.on_call || []).length"><p class="text-xs text-slate-400">No on-call days scheduled.</p></template>
+                                <template x-for="d in (portal.self.on_call || [])" :key="d">
+                                    <div class="flex items-center justify-between bg-emerald-50 px-3 py-2 rounded-lg">
+                                        <div class="flex items-center gap-3">
+                                            <div class="toggle on" @click="togglePortalOnCall(d)"></div>
+                                            <span class="text-sm font-medium" x-text="`${d} — 07:00 → next day 07:00`"></span>
+                                        </div>
+                                        <button class="btn btn-ghost btn-sm text-red-600" @click="removePortalOnCall(d)">Remove</button>
+                                    </div>
+                                </template>
+                            </div>
+                            <div class="flex gap-2 items-end">
+                                <div class="flex-1">
+                                    <label class="text-xs text-slate-600">Add on-call date</label>
+                                    <input type="date" x-model="portal.newOnCallDate" class="input" />
+                                </div>
+                                <button class="btn btn-secondary" @click="addPortalOnCall()">Add</button>
+                            </div>
+                        </div>
+                    </div>
+                </template>
+            </div>
+
+            <!-- SCHEDULE tab -->
+            <div x-show="portal.tab === 'schedule'" x-cloak>
+                <div class="card p-4">
+                    <template x-if="platformTimezone">
+                        <div class="text-xs text-slate-500 mb-2">
+                            <span x-text="`All times shown are in ${platformTimezoneLabel} time.`"></span>
+                        </div>
+                    </template>
+                    <div id="portal-calendar-root"></div>
+                </div>
+                <template x-if="portal.selectedEvent">
+                    <div class="modal-backdrop" @click.self="portal.selectedEvent = null">
+                        <div class="modal p-6">
+                            <div class="flex justify-between items-start mb-4">
+                                <h3 class="font-semibold" x-text="portal.selectedEvent.title"></h3>
+                                <button class="btn btn-ghost btn-sm" @click="portal.selectedEvent = null">✕</button>
+                            </div>
+                            <template x-if="portal.selectedEvent.type === 'appointment'">
+                                <div class="space-y-2 text-sm">
+                                    <div>
+                                        <span class="text-slate-500">Status:</span>
+                                        <span :class="statusBadgeClass(portal.selectedEvent.status)" x-text="portal.selectedEvent.status || 'scheduled'"></span>
+                                    </div>
+                                    <div><span class="text-slate-500">Date:</span> <span x-text="formatDate(portal.selectedEvent.date)"></span></div>
+                                    <div><span class="text-slate-500">Time:</span> <span x-text="`${formatTime(portal.selectedEvent.start_time)} – ${formatTime(portal.selectedEvent.end_time)}`"></span></div>
+                                    <div><span class="text-slate-500">Level:</span> <span x-text="portal.selectedEvent.visit_level"></span></div>
+                                    <div><span class="text-slate-500">Address:</span> <span x-text="portal.selectedEvent.visit_address"></span></div>
+                                    <template x-if="portal.selectedEvent.recommended_departure_time">
+                                        <div><span class="text-slate-500">Depart by:</span> <span x-text="formatTime(portal.selectedEvent.recommended_departure_time)"></span></div>
+                                    </template>
+                                    <div class="mt-4 flex justify-end">
+                                        <template x-if="(portal.selectedEvent.status || 'scheduled') === 'scheduled'">
+                                            <button
+                                                class="btn btn-primary"
+                                                :disabled="!canCompleteAppointment(portal.selectedEvent) || loading"
+                                                :title="canCompleteAppointment(portal.selectedEvent) ? '' : 'Available once the appointment start time has passed.'"
+                                                @click="markAppointmentComplete(portal.selectedEvent.appointment_id)"
+                                            >
+                                                <span x-show="!loading">Mark Complete</span>
+                                                <span x-show="loading" class="spinner"></span>
+                                            </button>
+                                        </template>
+                                        <template x-if="(portal.selectedEvent.status || 'scheduled') === 'completed'">
+                                            <span class="text-xs text-slate-500">Completed<span x-show="portal.selectedEvent.completed_at" x-text="` · ${portal.selectedEvent.completed_at}`"></span></span>
+                                        </template>
+                                    </div>
+                                </div>
+                            </template>
+                        </div>
+                    </div>
+                </template>
+            </div>
+        </div>
+
+    </main>
+</div>
+</template>
+
+<!-- ============================================================ -->
+<!-- PROVIDER MODAL (add/edit) -->
+<!-- ============================================================ -->
+<template x-if="prov.showAdd">
+    <div class="modal-backdrop" @click.self="prov.showAdd = false">
+        <div class="modal p-6">
+            <div class="flex justify-between items-center mb-4">
+                <h3 class="font-semibold text-lg" x-text="prov.editingId ? 'Edit Provider' : 'Add Provider'"></h3>
+                <button class="btn btn-ghost btn-sm" @click="prov.showAdd = false">✕</button>
+            </div>
+            <div class="grid md:grid-cols-2 gap-4">
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Name</label>
+                    <input type="text" x-model="provForm.name" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Email</label>
+                    <input type="email" x-model="provForm.email" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Portal Password</label>
+                    <input type="text" x-model="provForm.password" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Category</label>
+                    <select x-model="provForm.category" class="select mt-1"><option>provider</option><option>nurse</option></select>
+                </div>
+                <div class="md:col-span-2">
+                    <label class="text-sm font-medium text-slate-700">Home Address</label>
+                    <input type="text" x-model="provForm.address" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Work Hours Start</label>
+                    <input type="text" x-model="provForm.work_hours.start" placeholder="HH:MM" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Work Hours End</label>
+                    <input type="text" x-model="provForm.work_hours.end" placeholder="HH:MM" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Lunch Start</label>
+                    <input type="text" x-model="provForm.lunch_break.start" placeholder="HH:MM" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Lunch End</label>
+                    <input type="text" x-model="provForm.lunch_break.end" placeholder="HH:MM" class="input mt-1" />
+                </div>
+                <div class="md:col-span-2">
+                    <label class="text-sm font-medium text-slate-700">Service Levels</label>
+                    <div class="flex flex-wrap gap-2 mt-1">
+                        <template x-for="lvl in [1,2,3,'Nurse']" :key="lvl">
+                            <button class="btn btn-sm" :class="provForm.service_levels.some(x => x == lvl) ? 'btn-primary' : 'btn-secondary'" @click="toggleServiceLevel(lvl)" x-text="lvl"></button>
+                        </template>
+                    </div>
+                </div>
+            </div>
+            <div class="mt-6 flex justify-end gap-2">
+                <button class="btn btn-secondary" @click="prov.showAdd = false">Cancel</button>
+                <button class="btn btn-primary" @click="saveProvider()" :disabled="loading">
+                    <span x-show="!loading" x-text="prov.editingId ? 'Save Changes' : 'Add Provider'"></span>
+                    <span x-show="loading" class="spinner"></span>
+                </button>
+            </div>
+        </div>
+    </div>
+</template>
+
+<!-- ============================================================ -->
+<!-- PATIENT MODAL (add/edit) -->
+<!-- ============================================================ -->
+<template x-if="pat.showAdd">
+    <div class="modal-backdrop" @click.self="pat.showAdd = false">
+        <div class="modal p-6">
+            <div class="flex justify-between items-center mb-4">
+                <h3 class="font-semibold text-lg" x-text="pat.editingId ? 'Edit Patient' : 'Add Patient'"></h3>
+                <button class="btn btn-ghost btn-sm" @click="pat.showAdd = false">✕</button>
+            </div>
+            <div class="grid md:grid-cols-2 gap-4">
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Name</label>
+                    <input type="text" x-model="patForm.name" class="input mt-1" />
+                </div>
+                <div>
+                    <label class="text-sm font-medium text-slate-700">Email</label>
+                    <input type="email" x-model="patForm.email" class="input mt-1" />
+                </div>
+                <div class="md:col-span-2">
+                    <label class="text-sm font-medium text-slate-700">Address</label>
+                    <input type="text" x-model="patForm.address" class="input mt-1" />
+                </div>
+                <div class="md:col-span-2">
+                    <label class="text-sm font-medium text-slate-700">Notes</label>
+                    <textarea x-model="patForm.notes" class="input mt-1" rows="3"></textarea>
+                </div>
+            </div>
+            <div class="mt-6 flex justify-end gap-2">
+                <button class="btn btn-secondary" @click="pat.showAdd = false">Cancel</button>
+                <button class="btn btn-primary" @click="savePatient()" :disabled="loading">
+                    <span x-show="!loading" x-text="pat.editingId ? 'Save Changes' : 'Add Patient'"></span>
+                    <span x-show="loading" class="spinner"></span>
+                </button>
+            </div>
+        </div>
+    </div>
+</template>
+
+<!-- ============================================================ -->
+<!-- TOAST -->
+<!-- ============================================================ -->
+<template x-if="toast">
+    <div class="toast" :class="`toast-${toast.type}`" x-text="toast.msg" @click="toast = null"></div>
+</template>
+
+</body>
+</html>

utils/__init__.py

@@ -0,0 +1 @@
+"""utils package."""

utils/auth.py

@@ -0,0 +1,55 @@
+"""
+Authentication helpers — session-cookie-based for FastAPI.
+Supports admin and provider login. Sessions stored in-memory keyed by token.
+"""
+import os
+import secrets
+import threading
+from core import data_manager
+
+
+def get_secret(key: str) -> str:
+    return os.environ.get(key)
+
+
+# In-memory session store: token -> session dict
+_lock = threading.Lock()
+_sessions: dict[str, dict] = {}
+
+
+def check_credentials(username: str, password: str) -> bool:
+    admin_user = get_secret("ADMIN_USERNAME")
+    admin_pass = get_secret("ADMIN_PASSWORD")
+    return bool(admin_user) and bool(admin_pass) and username == admin_user and password == admin_pass
+
+
+def check_provider_credentials(name: str, password: str) -> dict | None:
+    provider = data_manager.get_provider_by_name(name)
+    if provider and provider.get("password") == password:
+        return provider
+    return None
+
+
+def create_session(user_role: str, current_user: str, provider_id: str | None = None) -> str:
+    token = secrets.token_urlsafe(32)
+    with _lock:
+        _sessions[token] = {
+            "user_role": user_role,
+            "current_user": current_user,
+            "provider_id": provider_id,
+        }
+    return token
+
+
+def get_session(token: str | None) -> dict | None:
+    if not token:
+        return None
+    with _lock:
+        return _sessions.get(token)
+
+
+def destroy_session(token: str | None) -> None:
+    if not token:
+        return
+    with _lock:
+        _sessions.pop(token, None)

utils/helpers.py

@@ -0,0 +1,59 @@
+"""
+Shared utility functions — time formatting, address formatting, etc.
+"""
+from datetime import datetime, timedelta
+from core import settings_manager as settings
+
+
+def format_time(time_str: str) -> str:
+    """Convert 'HH:MM' (24h) to '2:30 PM' (12h) format for display."""
+    t = datetime.strptime(time_str, "%H:%M")
+    return t.strftime("%I:%M %p") #previously %-I
+
+
+def format_date(date_str: str) -> str:
+    """Convert 'YYYY-MM-DD' to 'Friday, March 20, 2026' for display."""
+    d = datetime.strptime(date_str, "%Y-%m-%d")
+    return d.strftime("%A, %B %d, %Y") #previously %-d
+
+
+def is_future_date(date_str: str, min_hours_ahead: int = 24) -> bool:
+    """Check if a date string is at least min_hours_ahead in the future."""
+    target = datetime.strptime(date_str, "%Y-%m-%d")
+    cutoff = datetime.now() + timedelta(hours=min_hours_ahead)
+    return target >= cutoff
+
+
+def build_event_title(visit_level: int | str, patient_name: str, provider_name: str) -> str:
+    """Build a Google Calendar event title.
+
+    Format: '[Level X] PatientName — ProviderName'
+    """
+    level_info = settings.get_visit_levels().get(visit_level, {})
+    label = level_info.get("label", f"Level {visit_level}")
+    return f"[{label}] {patient_name} — {provider_name}"
+
+
+def build_event_description(patient: dict, provider: dict, visit_address: str) -> str:
+    """Build a Google Calendar event description with contact info and address."""
+    lines = [
+        f"Patient: {patient.get('name', 'N/A')}",
+        f"Patient Email: {patient.get('email', 'N/A')}",
+        f"Provider: {provider.get('name', 'N/A')}",
+        f"Provider Email: {provider.get('email', 'N/A')}",
+        f"Visit Address: {visit_address}",
+    ]
+    if patient.get("notes"):
+        lines.append(f"Notes: {patient['notes']}")
+    return "\n".join(lines)
+
+
+def minutes_to_display(minutes: int) -> str:
+    """Convert minutes to a readable string: '1h 15m' or '45m'."""
+    if minutes < 60:
+        return f"{minutes}m"
+    hours = minutes // 60
+    remaining = minutes % 60
+    if remaining == 0:
+        return f"{hours}h"
+    return f"{hours}h {remaining}m"