🩺 HCP CRM & AI Co-Pilot Portal

Welcome to the HCP CRM & AI Co-Pilot Portal, an intelligent, state-of-the-art solution designed for pharmaceutical field representatives to seamlessly log interaction records, perform real-time regulatory compliance audits, and manage Healthcare Professional (HCP) profiles and follow-ups.

This project is structured as a monorepo containing a high-performance FastAPI backend and a modern, high-fidelity React/TypeScript frontend styled with Tailwind CSS and powered by Redux Toolkit.

---

🏗️ Architectural Overview & Data Flow

The portal leverages an agentic workflow to extract structured medical details and audit communications before saving records:

graph TD
    A[Field Rep Input / Chat] -->|Submit Raw Interaction| B[React Frontend]
    B -->|API POST Request| C[FastAPI Backend Router]
    C -->|Run Agentic Graph| D[LangGraph Coordinator]
    D -->|Step 1: Audit Text| E[Compliance Audit Engine]
    D -->|Step 2: Parse Details| F[Metadata Extraction Engine]
    E -->|If Compliance Passed| F
    E -->|If Compliance Failed| G[Raise Warning / Error]
    F -->|DB Session| H[SQLAlchemy Database Layer]
    H -->|Insert & Commit| I[(SQL DB: Postgres / SQLite)]
    H -->|Return Structured JSON| B
    B -->|Redux Sync & Glow animation| J[HCP Interaction Workspace Form]

Loading

1. Rep Log Entry: The field representative types a raw summary (e.g. "Met Dr. Carter today at 10:15 AM to review Keytruda trial safety data, she seemed very positive...") or selects a mock feed.
2. FastAPI Route: The backend receives the text via the log_interaction agent.
3. Compliance Audit: The text is evaluated by the compliance auditing engine for pharmaceutical guidelines (FDA off-label issues, safety claims, comparative claims, inducements).
4. Metadata Extraction: If clear, the extraction engine parses parameters like HCP Name, Product, Sentiment, Attendees, Materials Shared, and Follow-up Date.
5. Database Transaction: Profiles, interactions, compliance results, and follow-ups are created/updated in the SQL database (Postgres inside Docker, or local SQLite fallback).
6. Dynamic Frontend Sync: The React UI matches the newly created record and triggers Redux-based highlighting with a visual pulse-glow.

---

🌟 Key Features

• 🤖 AI Co-Pilot Panel: A chat interface to log notes, extract details, and receive automated follow-up suggestions in real-time.
• ⚖️ Pharma Compliance Safeguards: Scans every log entry against regulatory rules, warning reps about potential violations before final database submission.
• 📑 Interactive Workspace: A complete data form that highlights fields autocompleted by the AI to ensure visual clarity and allow for quick review/edit.
• 📅 Auto-Follow-ups: Automatically schedules calendar and task-style reminders based on discussions (e.g. "reconnect in 2 weeks").
• 🧪 Ingestion Feeds: Built-in mock transcripts (Oncology Audio, Cardiology Call) to instantly test the AI model's extraction capabilities.

---

📁 Project Directory Structure

hcp-crm/
├── crm_agent.db               # Core SQLite Database File
├── backend/                   # Python FastAPI Backend Project
│   ├── app/
│   │   ├── api/               # API endpoints configuration
│   │   │   └── v1/
│   │   │       ├── endpoints/
│   │   │       │   ├── crm.py     # Main CRM & Agent endpoints
│   │   │       │   └── health.py  # Health-check api
│   │   │       └── api.py         # Main V1 router index
│   │   ├── core/              # Global configuration / Pydantic settings
│   │   ├── models/            # SQLAlchemy DB models definition
│   │   ├── schemas/           # Pydantic validation schemas
│   │   ├── services/          # Core Business logic
│   │   │   ├── agent.py       # LangGraph workspace flow
│   │   │   ├── compliance.py  # Regulatory audit rules & LLM integration
│   │   │   ├── crm_tools.py   # Database query & mutation utils
│   │   │   └── extraction.py  # Structured metadata extractor
│   │   ├── database.py        # SQLAlchemy engine and session setup
│   │   └── main.py            # FastAPI main application entrypoint
│   ├── tests/                 # Unit and integration test suites
│   ├── .env                   # Backend environment configurations
│   ├── requirements.txt       # Python dependencies list
│   └── README.md              # Backend-specific instructions
└── frontend/                  # React + TypeScript + Vite Web Application
    ├── public/                # Static public assets
    ├── src/
    │   ├── assets/            # CSS, images, and logos
    │   ├── components/        # UI components
    │   │   ├── ChatbotPanel.tsx     # AI Co-Pilot chat interface
    │   │   ├── Header.tsx           # Session controls and profile details
    │   │   └── InteractionForm.tsx  # Workspace logger form
    │   ├── services/
    │   │   └── api.ts         # Axios/fetch integration with FastAPI backend
    │   ├── store/             # Redux state store config and slices
    │   ├── App.tsx            # Main application layout structure
    │   ├── index.css          # Design system stylesheet
    │   └── main.tsx           # React entrypoint
    ├── tailwind.config.js     # Tailwind CSS theme configurations
    ├── package.json           # Frontend Node.js dependencies
    └── README.md              # Frontend-specific instructions

---

🚀 Getting Started

Follow these steps to set up and run both the backend and frontend services locally.

Prerequisites

Ensure you have the following installed on your machine:

• Python 3.10+
• Node.js v18+
• Groq API Key (Optional: Uses deterministic local heuristics fallback if not present)

---

📥 1. Backend Setup (FastAPI)

1. Navigate to the backend directory:

   cd backend

2. Create and Activate a Virtual Environment:

   • Windows (PowerShell):

     python -m venv .venv
     .\.venv\Scripts\Activate.ps1

   • Windows (CMD):

     python -m venv .venv
     .\.venv\Scripts\activate.bat

   • macOS / Linux:

     python3 -m venv .venv
     source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure Environment Variables: Create a .env file in the backend/ directory (or edit the existing one):

   DATABASE_URL=sqlite:///./crm_agent.db
   GROQ_API_KEY=your_groq_api_key_here
   GROQ_MODEL=llama-3.3-70b-versatile

   [!NOTE] If GROQ_API_KEY is blank or missing, the system automatically falls back to regex-based heuristic parsing for compliance check and extraction, allowing local-first development without API charges.

5. Run the Uvicorn Dev Server:

   uvicorn app.main:app --reload

   The server will start at: http://127.0.0.1:8000

   • Interactive Swagger Documentation: http://127.0.0.1:8000/docs
   • ReDoc Endpoint Docs: http://127.0.0.1:8000/redoc

---

💻 2. Frontend Setup (React/Vite)

1. Open a new terminal and navigate to the frontend directory:

   cd frontend

2. Install Node packages:

   npm install

3. Run the Vite development server:

   npm run dev

   The frontend portal will launch at: http://localhost:5173

---

🐳 3. Running with Docker & PostgreSQL (Recommended)

You can run the entire stack (PostgreSQL database, FastAPI backend, and React/Vite frontend) in containers using Docker Compose. This handles PostgreSQL database provisioning, linking services, and dependencies automatically.

Prerequisites for Docker Setup

• Docker Desktop installed and running.

Execution:

In the project root directory, run:

docker compose up --build

Once running, the stack is available at:

• Frontend React Portal: http://localhost:5173 (served through Nginx)
• FastAPI Backend Docs: http://localhost:8000/docs
• PostgreSQL DB: Running on port 5432 with connection parameters configured in the root docker-compose.yml. PostgreSQL data is persistent across runs via the pgdata Docker volume.

Stop the containers and remove volumes:

docker compose down -v

---

🧪 Running Tests

To execute backend unit tests for the compliance engine or extractors, activate your backend virtual environment and run:

cd backend
python -m unittest discover tests

---

🛡️ Compliance Rules & Heuristics Triggers

When running in local-fallback mode, the compliance engine checks for key phrases in the interaction log text. Any occurrence of these keywords flags the interaction as high risk:

Key phrase / Trigger	Flagged Violation Message
off-label	Possible off-label promotion language.
unapproved	Possible claim about an unapproved use or indication.
guaranteed cure	Absolute efficacy claim detected.
no side effects	Potentially misleading safety claim detected.
better than	Comparative claim may require substantiation.
free gift	Potential inducement language detected.
kickback	Potential anti-kickback concern detected.

---

🔌 API Routes Reference

The backend exposes the following API routes under the /api/v1 prefix:

🤖 CRM Agent Operations

• POST /api/v1/crm/agent/log: LangGraph agent workflow that processes raw text logs, extracts fields, performs a compliance review, and writes to database.
• POST /api/v1/crm/agent/invoke: Multi-action agent dispatcher supporting log_interaction, edit_interaction, search_hcp_profile, schedule_follow_up, and compliance_check.
• POST /api/v1/crm/compliance/check: Independent endpoint to run a compliance scan on raw text.
• POST /api/v1/crm/follow-ups: Schedules a new calendar/due-date follow-up task.
• GET /api/v1/crm/hcps/{hcp_name}/profile: Queries preferences, status, and recent interactions for a given Healthcare Professional.

📥 Ingestion Feeds

• GET /api/v1/crm/ingestion-feeds: Returns available mock transcripts.
• POST /api/v1/crm/ingestion-feeds/{feed_id}/log: Automatically processes and logs a specific mock transcript.

🩺 System Health

• GET /api/v1/health: Checks system and database connection status.

---

🛠️ Key Code References

For modifications and custom updates, inspect the following key application files:

• Entry Point: backend/app/main.py
• FastAPI Routes: backend/app/api/v1/endpoints/crm.py
• Database Models: backend/app/models/crm.py
• Compliance Rules: backend/app/services/compliance.py
• Chat View component: frontend/src/components/ChatbotPanel.tsx
• Form View component: frontend/src/components/InteractionForm.tsx
• API Integration Client: frontend/src/services/api.ts