ClinicFlow AI

An AI-powered clinical intake and documentation assistant built with FastAPI and OpenAI.

Patients complete a structured web form before their consultation. The backend pipeline processes the input through an LLM and returns three outputs for the clinician:

• Intake Summary — a concise 2-3 sentence overview of why the patient is presenting
• Structured Patient Information — key fields extracted and organised in a clean format
• Draft SOAP Clinical Note — a pre-filled Subjective section with editable fields for Objective, Assessment, and Plan

⚠️ This is a simulated demo using fake patient data. It is not intended for use in real clinical settings.

---

Tech Stack

• Backend — Python, FastAPI
• Templating — Jinja2
• AI — OpenAI API (gpt-4o-mini)
• Frontend — Plain HTML + CSS (single page)

---

Project Structure

clinicflow-ai/
├── main.py                  # FastAPI app + POST /generate-note endpoint
├── templates/
│   └── index.html           # Intake form and result display
├── .env.example             # Environment variable template
├── requirements.txt
└── README.md

---

Getting Started

1. Clone the repository

git clone https://github.com/your-username/clinicflow-ai.git
cd clinicflow-ai

2. Create a virtual environment

python -m venv venv

# Mac/Linux
source venv/bin/activate

# Windows
venv\Scripts\activate.bat

3. Install dependencies

pip install -r requirements.txt

4. Set up environment variables

cp .env.example .env

Open .env and add your OpenAI API key:

OPENAI_API_KEY=sk-your-key-here

5. Run the app

uvicorn main:app --reload

Open your browser at http://127.0.0.1:8000

---

How It Works

1. Patient fills in the intake form (name, age, symptoms, history, medications, allergies)
2. Form is submitted to POST /generate-note
3. Backend constructs a prompt and calls the OpenAI API
4. LLM returns a structured JSON response
5. The page displays the intake summary, structured info, and a draft SOAP note
6. Clinician can fill in the Objective, Assessment, and Plan fields directly on the page

---

Backend Pipeline

Patient Form Input
       ↓
  Input Validation
       ↓
  Prompt Construction
       ↓
  OpenAI API Call (gpt-4o-mini)
       ↓
  JSON Response Parsing
       ↓
  ┌─────────────────────────────┐
  │  intake_summary             │
  │  structured_info            │
  │  draft_clinical_note (SOAP) │
  └─────────────────────────────┘

---

Sample Output

Given a patient presenting with a persistent headache, the system generates:

Intake Summary

A 45-year-old patient presents with a persistent throbbing headache lasting 3 days, accompanied by nausea and light sensitivity. The patient has a history of hypertension and is currently taking Lisinopril 10mg. An allergy to Penicillin has been noted.

Structured Info

Name, age, presenting complaint, symptoms list, relevant history, medications, allergies — all extracted and formatted.

Draft SOAP Note

Subjective pre-filled from patient data. Objective, Assessment, and Plan left as editable fields for the clinician to complete after consultation.

---

Error Handling

• Missing or invalid form input returns inline validation messages
• OpenAI API failures return a user-facing error message
• Malformed LLM responses are caught and surfaced gracefully

---

Limitations

• No database — results are not saved between sessions
• No authentication or user accounts
• Intended for demonstration purposes only