README.md

---
title: SOS Care Now Scheduling
emoji: 🩺
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 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.