Skip to content

raphaelDuff/dr-ozzy

BranchesTags

Repository files navigation

Dr Ozzy - Medical Prescription Safety Copilot

A web application that helps doctors transform patient conversation transcripts into structured, validated prescriptions with safety alerts.

What is Dr Ozzy?

Dr Ozzy is an AI-powered medical assistant designed for healthcare professionals. Doctors paste transcripts of their patient conversations, and the application automatically:

  1. Identifies speakers - Distinguishes between doctor and patient dialogue
  2. Extracts prescriptions - Pulls structured medication data (drug, dosage, frequency, duration)
  3. Validates safety - Checks for dangerous dosages, drug interactions, and contraindications
  4. Suggests clarifications - Prompts for missing critical information (allergies, current medications, etc.)

The goal is to reduce medical errors, save time on documentation, and ensure prescriptions meet safety standards before they reach the pharmacy.

You can use the Sample Transcripts to test the app.

Product Preview

Chat Interface - Transcript Analysis

Prescription Cards with Safety Alerts

Table of Contents

Features

Core MVP Features

  • Chat-like Interface - Familiar conversational UI similar to ChatGPT
  • Transcript Analysis - Paste medical conversations and get structured data
  • Speaker Role Detection - Automatic identification of doctor vs patient
  • Prescription Extraction - Structured output with drug name, dosage, form, frequency, duration, route
  • Safety Validation - Real-time alerts for dosage limits and potential issues
  • OAuth2 Authentication - Secure login via Auth0/Okta

Safety Alerts

The system validates prescriptions against known safety rules:

Alert Type Description
dosage_limit Dosage exceeds maximum recommended amount
interaction Potential drug-drug interaction detected
contraindication Drug is contraindicated for patient's condition
warning General safety warnings

Tech Stack

Backend

Technology Purpose
FastAPI Async web framework
SQLModel ORM with Pydantic integration
PostgreSQL Relational database
Alembic Database migrations
Anthropic Claude LLM for transcript analysis
Python 3.13+ Modern async/await syntax

Frontend

Technology Purpose
React 19 UI component library
TypeScript Type-safe JavaScript
Vite Fast build tool
Tailwind CSS Utility-first styling
React Router Client-side routing

DevOps

Technology Purpose
Docker Containerization
AWS ECS Fargate Serverless container hosting
AWS RDS Managed PostgreSQL
AWS CloudFront + S3 Frontend CDN hosting
Auth0 OAuth2/OIDC authentication

Architecture

Why Domain-Driven Design?

This project implements Clean Architecture with Domain-Driven Design (DDD) principles for several reasons:

  1. Separation of Concerns - Business logic is isolated from frameworks and infrastructure
  2. Testability - Domain and application layers can be tested without databases or HTTP
  3. Maintainability - Clear boundaries make the codebase easier to navigate and modify
  4. Flexibility - Swapping databases, frameworks, or external services requires minimal changes

The architecture follows the principles outlined in:

Clean Architecture with Python - Published by Packt

Layer Structure

app/
|-- domain/                 # Enterprise Business Rules
|   +-- entities/          # Core business objects (User, Prescription, ChatSession)
|
|-- application/           # Application Business Rules
|   |-- use_cases/        # Application-specific workflows
|   |-- dtos/             # Data Transfer Objects
|   |-- repositories/     # Repository interfaces (abstractions)
|   +-- services/         # Service interfaces (LLM, Safety)
|
|-- interfaces/           # Interface Adapters
|   |-- controllers/      # Orchestrate use cases
|   |-- presenters/       # Format output to view models
|   +-- view_models/      # API request/response contracts
|
+-- infrastructure/       # Frameworks & Drivers
    |-- persistence/      # SQLModel repository implementations
    |-- services/         # Claude LLM, Safety validation implementations
    |-- web/              # FastAPI routes & dependencies
    +-- auth/             # OAuth2/JWT security

Request Flow

HTTP Request -> Route -> View Model Validation -> DTO -> Controller -> Use Case -> Repository -> Entity

Response Flow

Entity -> Repository (DTO) -> Use Case (Result[DTO]) -> Controller -> Presenter -> View Model -> JSON

AI Usage Declaration

I used AI assistance throughout this project. Here's a breakdown:

Product Requirements (PRP)

After creating the initial user domain repository, I used a PRP Metaprompt to refine the product requirements document. This involved iterative questioning to clarify:

  • Target users and pain points
  • User journey and flow
  • Core features vs future enhancements
  • Tech stack recommendations

Backend Development

For the backend implementation, I used the following prompt pattern:

"Now I want to create just the BACKEND for this MVP. Before starting code, read the architecture.md to understand the rules for my Domain-Driven Design, and strictly follow it using ReAct pattern after you finish each task (divide the implementation in tasks). Use the pattern of development that I used for user domain, application, interfaces, infrastructure, and web. Use the Product Requirements document as reference."

This ensured the AI followed the established architectural patterns consistently.

Frontend Development

I created react-rules.md as a coding standards document for the AI to follow when implementing the React frontend. This included:

  • Vite configuration best practices
  • React component architecture (functional components, hooks)
  • Tailwind CSS utility-first patterns
  • TypeScript type safety requirements

Code Quality

Used AI to:

  • Standardize docstrings across the codebase
  • Ensure consistent error handling patterns
  • Generate TypeScript interfaces matching backend DTOs

LLM & RAG Implementation

Language Model

The application uses Claude Sonnet (claude-sonnet-4-20250514) from Anthropic for:

  • Medical transcript analysis
  • Prescription extraction with confidence scores
  • Speaker role identification
  • Clarifying question generation

Implementation: claude_llm_service.py

Safety Validation (Embedded Knowledge)

Currently, the safety validation uses a rule-based approach with hardcoded drug data:

# From basic_safety_validation_service.py
DOSAGE_LIMITS = {
    "amoxicillin": (1000, 3000),   # Max 1000mg per dose, 3000mg per day
    "ibuprofen": (800, 3200),      # Max 800mg per dose, 3200mg per day
    "metformin": (1000, 2550),     # Max 1000mg per dose, 2550mg per day
    "acetaminophen": (1000, 4000), # Max 1000mg per dose, 4000mg per day
    "lisinopril": (40, 40),        # Max 40mg per dose and per day
}

INTERACTIONS = {
    "metformin": ["alcohol"],
    "ibuprofen": ["aspirin", "warfarin"],
    "lisinopril": ["potassium supplements"],
}

Implementation: basic_safety_validation_service.py

Future: Vector Database for RAG

The project could be significantly enhanced with a proper RAG (Retrieval-Augmented Generation) implementation:

  1. Vector Database (Weaviate) - Store drug package inserts (bulas), clinical guidelines, and interaction databases
  2. AI Agent - Use an autonomous agent to query the vector database before validating prescriptions
  3. Real-time Updates - Keep drug safety information current without code changes
  4. Expanded Coverage - Support thousands of drugs instead of a handful

This would transform the hardcoded rules into a dynamic, always-up-to-date safety system.

Infrastructure

Architecture Diagram

                 +------------------+
                 |    Route 53      |
                 |   labsxv.com     |
                 +--------+---------+
                          |
         +----------------+----------------+
         |                                 |
         v                                 v
+----------------+                +------------------+
|   CloudFront   |                |       ALB        |
|   labsxv.com   |                | api.labsxv.com   |
+-------+--------+                +--------+---------+
        |                                  |
        v                                  v
+----------------+                +------------------+
|   S3 Bucket    |                |   ECS Fargate    |
|  (React SPA)   |                |    (FastAPI)     |
+----------------+                +--------+---------+
                                           |
                                           v
                                  +------------------+
                                  | RDS PostgreSQL   |
                                  +------------------+

Components

Frontend Hosting

Component Details
S3 Bucket Hosts React SPA static files
CloudFront CDN with custom domain labsxv.com
SSL Certificate ACM certificate in us-east-1

Backend Services

Component Details
ECS Cluster Fargate serverless containers
ECS Service 2 tasks for high availability
ECR Repository Docker image registry
ALB Application Load Balancer with HTTPS

Database

Component Details
RDS PostgreSQL db.t3.micro, 20 GB storage

Networking

Component Details
VPC Custom VPC with CIDR 10.0.0.0/16
Public Subnets 2 subnets for ALB
Private Subnets 2 subnets for Fargate + RDS
NAT Gateway For private subnet internet access

Authentication Flow

+--------+     +-----------+     +----------+     +-----------+
|  User  | --> |  Frontend | --> |  Auth0   | --> |  Backend  |
|        | <-- |  (React)  | <-- | (OAuth2) | <-- | (FastAPI) |
+--------+     +-----------+     +----------+     +-----------+
  1. User clicks "Sign In" on frontend
  2. Frontend redirects to Auth0 Universal Login
  3. User authenticates (Google, email, etc.)
  4. Auth0 redirects to backend callback with authorization code
  5. Backend exchanges code for tokens
  6. Backend redirects to frontend with access token
  7. Frontend stores token for API requests

Getting Started

Prerequisites

  • Python 3.13+
  • Node.js 18+
  • PostgreSQL 16+ (or Docker)
  • uv - Fast Python package manager

1. Clone the Repository

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

2. Backend Setup

# Install Python dependencies
uv sync

# Copy environment file
cp .env.example .env

# Edit .env with your credentials (see Environment Variables section)

# Run database migrations
uv run alembic upgrade head

# Start the backend
uv run python -m app.main

The API will be available at http://localhost:8000

3. Frontend Setup

cd frontend

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Start development server
npm run dev

The frontend will be available at http://localhost:5173

Using Docker

# Start both API and PostgreSQL
docker-compose up -d

# Run migrations
docker-compose exec api uv run alembic upgrade head

Environment Variables

Backend (.env)

# Database
REPOSITORY_TYPE=postgresql
DATABASE_USER=postgres
DATABASE_PW=your_password
DATABASE_NAME=drozzy
DATABASE_IP=localhost
DATABASE_PORT=5432

# API Server
API_HOST=0.0.0.0
API_PORT=8000
ENVIRONMENT=development

# Anthropic (Claude AI)
ANTHROPIC_API_KEY=sk-ant-...

# OAuth2 (Auth0/Okta)
OKTA_ISSUER=https://your-tenant.auth0.com/
OKTA_AUDIENCE=your-api-audience
OKTA_CLIENT_ID=your-client-id
OKTA_CLIENT_SECRET=your-client-secret
OKTA_CALLBACK_URL=http://localhost:8000/auth/callback
FRONTEND_URL=http://localhost:5173

Frontend (.env)

VITE_API_URL=http://localhost:8000
VITE_AUTH0_DOMAIN=your-tenant.auth0.com
VITE_AUTH0_CLIENT_ID=your-client-id

API Endpoints

Authentication

Method Endpoint Description
GET /auth/login Initiate OAuth2 login
GET /auth/callback OAuth2 callback handler
GET /auth/me Get current user info

Chat Sessions

Method Endpoint Description
POST /chat/sessions Create new chat session
GET /chat/sessions List user's sessions
GET /chat/sessions/{id} Get session details
POST /chat/sessions/{id}/messages Add message to session
POST /chat/sessions/{id}/analyze Analyze transcript

Prescriptions

Method Endpoint Description
GET /prescriptions List prescriptions
GET /prescriptions/{id} Get prescription details
PUT /prescriptions/{id}/status Update prescription status

Safety Alerts API

Method Endpoint Description
GET /safety-alerts List safety alerts
PUT /safety-alerts/{id}/acknowledge Acknowledge an alert

Future Improvements

  1. Vector Database Integration - Implement Weaviate for RAG-based drug information retrieval

  2. Explore different chunking techniques - studying about RAG, these methods are a good fit for medical purposes:

    2.1 Recursive text splitter - If the store documents from html, for example, the chunk could use div chars to split the text 2.2 LLM Based Chunking

  3. Multiple AI Agents - One for extract prescriptions, and another for the safety alerts

  4. Audio Input - Support streaming audio transcription

  5. Drug Database Integration - Connect to FDA, DrugBank, or similar authoritative sources

  6. Patient History - Track patient allergies, conditions, and medication history

  7. Multi-language Support - Support transcripts in multiple languages

  8. Export Functionality - Generate PDF prescriptions and reports

  9. Audit Logging - Complete audit trail for compliance

Human Future Improvements

After this journey developing this project, I have some goals for the near future.

  1. Study software architectures and creating projects with them - Knowing the tradeoffs, high quality code, and create good blueprints for AI
  2. Get a AWS developer certificate
  3. Study AI for Medicine - AI for Medicine Specialization

About

AI Generative Chat | RAG

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages