README.md

Florence Documentation

Florence is a humanistic elder-care navigation agent — Grand Prize winner at AI Healthcare Hack NYC by Arya Health & Twilio (Jul 2026). It guides families through structured intake, recommends care types, matches providers, and submits mock referrals — by web chat or phone.

Devpost	florence-2026
Team	Morrison Chang, Douglas MacKrell, Andrew Lai

This folder is the portfolio and engineering reference for the project.

Start here

Doc	Audience	Purpose
Portfolio overview	Judges, recruiters, collaborators	Problem, solution, demo story, architecture
Quick start	Users & developers	Run locally in 5–15 minutes
Roadmap & status	Everyone	What's done and what's next
Architecture	Engineers	System design, data flow, repo layout

Demo paths

Path	Guide
Web (text + browser voice)	Quick start → User path
Phone (Twilio)	Telephony setup
Terminal replay	./scripts/run-demo.sh

Local URLs: UI → http://127.0.0.1:5173 · API → http://127.0.0.1:8001

Product & domain

Doc	Purpose
Product handoff (full spec)	Original requirements, intake schema, conversation design
Conversation engine	State machine, web vs phone behavior, Ollama layer
Matching & referrals	Care-type recommender, provider scoring, referral flow
Data models	Intake schema, provider catalog, persistence

Engineering

Doc	Purpose
API reference	REST + Twilio endpoints
Development guide	TDD workflow, git branches, hooks, testing
Getting started	Detailed install and troubleshooting
Security	Data handling, local-only LLM, secret scanning

Quick status (Jul 2026)

Hackathon: ✅ Grand Prize — AI Healthcare Hack NYC · Devpost

Milestone	Status
Step Zero — security foundation	✅ Complete
M1 — Web app + backend core	✅ Demo-ready
M2 — Twilio telephony	✅ Demo-ready locally (tunnel + Twilio creds)

See roadmap.md for detail.

Repository

• GitHub: https://github.com/DouglasMacKrell/florence
• Branches: develop (daily work) · main (stable milestones)