# Healthcare RCM AR Follow-Up Engine - Workflow Diagrams

## Table of Contents
1. [System Overview Workflow](#1-system-overview-workflow)
2. [User Authentication Flow](#2-user-authentication-flow)
3. [CSV Data Import Workflow](#3-csv-data-import-workflow)
4. [Smart Claim Prioritization Workflow](#4-smart-claim-prioritization-workflow)
5. [Agent Assignment Workflow](#5-agent-assignment-workflow)
6. [Dashboard Analytics Workflow](#6-dashboard-analytics-workflow)
7. [Claim Management Workflow](#7-claim-management-workflow)
8. [Data Processing Architecture](#8-data-processing-architecture)

---

## 1. System Overview Workflow

```mermaid
graph TB
    A[Healthcare Organization] --> B[AR Follow-Up Engine]
    B --> C{User Authentication}
    C -->|Admin| D[Admin Dashboard]
    C -->|Agent| E[Agent Dashboard]
    C -->|Manager| F[Manager Dashboard]
    
    D --> G[CSV Upload]
    D --> H[User Management]
    D --> I[System Configuration]
    
    E --> J[Assigned Claims]
    E --> K[Claim Updates]
    E --> L[Status Management]
    
    F --> M[Performance Analytics]
    F --> N[Team Overview]
    F --> O[Strategic Planning]
    
    G --> P[Data Processing]
    P --> Q[Claim Categorization]
    Q --> R[Priority Assignment]
    R --> S[Agent Assignment]
    S --> T[Dashboard Updates]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style D fill:#e8f5e8
    style E fill:#fff3e0
    style F fill:#fce4ec
```

---

## 2. User Authentication Flow

```mermaid
sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as Auth API
    participant D as Database
    participant J as JWT Service
    
    U->>F: Enter credentials
    F->>A: POST /api/login
    A->>D: Validate user credentials
    D-->>A: User data + role
    A->>J: Generate JWT token
    J-->>A: Signed token
    A-->>F: Token + user info
    F-->>U: Dashboard access
    
    Note over F: Store token in localStorage
    
    U->>F: Navigate to protected page
    F->>A: Request with Bearer token
    A->>J: Verify token
    J-->>A: Token validation result
    
    alt Token Valid
        A-->>F: Authorized response
        F-->>U: Display content
    else Token Invalid/Expired
        A-->>F: 401 Unauthorized
        F-->>U: Redirect to login
    end
```

---

## 3. CSV Data Import Workflow

```mermaid
flowchart TD
    A[Admin Uploads CSV] --> B{File Validation}
    B -->|Invalid| C[Show Error Message]
    B -->|Valid| D[Parse CSV Headers]
    
    D --> E{Column Mapping}
    E -->|Auto-detected| F[Process Data]
    E -->|Manual mapping needed| G[Show Mapping Interface]
    G --> F
    
    F --> H{Data Validation}
    H -->|Validation Errors| I[Generate Error Report]
    H -->|Valid Data| J[Batch Processing]
    
    J --> K[Create/Update Claims]
    K --> L[Calculate Priority Scores]
    L --> M[Assign Agents]
    M --> N[Update Dashboard]
    
    I --> O{Partial Import?}
    O -->|Yes| P[Import Valid Records]
    O -->|No| Q[Reject All Records]
    
    P --> K
    Q --> C
    
    N --> R[Success Notification]
    C --> S[User Action Required]
    
    style A fill:#e3f2fd
    style F fill:#f3e5f5
    style K fill:#e8f5e8
    style R fill:#e8f5e8
    style C fill:#ffebee
```

---

## 4. Smart Claim Prioritization Workflow

```mermaid
graph TB
    A[New/Updated Claim] --> B[Priority Calculation Engine]
    
    B --> C{Value Factor}
    C -->|>$10,000| C1[+30 points]
    C -->|$5,000-$10,000| C2[+20 points]
    C -->|$1,000-$5,000| C3[+10 points]
    C -->|<$1,000| C4[+5 points]
    
    B --> D{Aging Factor}
    D -->|>120 days| D1[+25 points]
    D -->|91-120 days| D2[+20 points]
    D -->|61-90 days| D3[+15 points]
    D -->|31-60 days| D4[+10 points]
    D -->|0-30 days| D5[+5 points]
    
    B --> E{Payer Difficulty}
    E -->|High Difficulty| E1[+15 points]
    E -->|Medium Difficulty| E2[+10 points]
    E -->|Low Difficulty| E3[+5 points]
    
    B --> F{Status Factor}
    F -->|Denied| F1[+20 points]
    F -->|Under Review| F2[+10 points]
    F -->|Pending| F3[+5 points]
    
    C1 --> G[Calculate Total Score]
    C2 --> G
    C3 --> G
    C4 --> G
    D1 --> G
    D2 --> G
    D3 --> G
    D4 --> G
    D5 --> G
    E1 --> G
    E2 --> G
    E3 --> G
    F1 --> G
    F2 --> G
    F3 --> G
    
    G --> H{Score Classification}
    H -->|70+ points| I[Critical Priority]
    H -->|50-69 points| J[High Priority]
    H -->|30-49 points| K[Medium Priority]
    H -->|<30 points| L[Low Priority]
    
    I --> M[Assign Priority Level]
    J --> M
    K --> M
    L --> M
    
    M --> N[Update Dashboard]
    M --> O[Trigger Agent Assignment]
    
    style I fill:#ffcdd2
    style J fill:#ffe0b2
    style K fill:#e1f5fe
    style L fill:#e8f5e8
```

---

## 5. Agent Assignment Workflow

```mermaid
flowchart TD
    A[Claim Requires Assignment] --> B{Business Rules Engine}
    
    B --> C{Claim Value Check}
    C -->|>$1,000| D[Route to Senior Agent]
    C -->|≤$1,000| E{Aging Check}
    
    E -->|>90 days| F[Route to Escalation Team]
    E -->|≤90 days| G{Payer Type Check}
    
    G -->|Medicare/Medicaid| H[Route to Government Specialist]
    G -->|Commercial| I{Agent Availability}
    
    I --> J{Load Balancing}
    J --> K[Select Available Agent]
    K --> L[Assign Claim]
    
    D --> M{Senior Agent Available?}
    M -->|Yes| N[Assign to Senior Agent]
    M -->|No| O[Queue for Senior Agent]
    
    F --> P{Escalation Team Available?}
    P -->|Yes| Q[Assign to Escalation Team]
    P -->|No| R[Queue for Escalation]
    
    H --> S{Government Specialist Available?}
    S -->|Yes| T[Assign to Specialist]
    S -->|No| U[Queue for Specialist]
    
    L --> V[Update Claim Record]
    N --> V
    Q --> V
    T --> V
    
    O --> W[Add to Senior Queue]
    R --> X[Add to Escalation Queue]
    U --> Y[Add to Specialist Queue]
    
    V --> Z[Notification to Agent]
    Z --> AA[Dashboard Update]
    
    W --> BB[Queue Management]
    X --> BB
    Y --> BB
    BB --> CC[Auto-assign when available]
    
    style D fill:#e8f5e8
    style F fill:#ffe0b2
    style H fill:#e1f5fe
    style K fill:#f3e5f5
```

---

## 6. Dashboard Analytics Workflow

```mermaid
graph LR
    A[User Accesses Dashboard] --> B[Authentication Check]
    B --> C{Role-Based Data Filter}
    
    C -->|Admin| D[All Claims Data]
    C -->|Agent| E[Assigned Claims Only]
    C -->|Manager| F[Team Claims Data]
    
    D --> G[Query Database]
    E --> G
    F --> G
    
    G --> H[Calculate Metrics]
    H --> I[Priority Summary]
    H --> J[Aging Buckets]
    H --> K[Payer Analysis]
    H --> L[Financial Totals]
    
    I --> M[Generate Charts]
    J --> M
    K --> M
    L --> M
    
    M --> N[Render Dashboard]
    N --> O[Real-time Updates]
    
    O --> P{Data Changes?}
    P -->|Yes| Q[Refresh Calculations]
    P -->|No| R[Maintain Current View]
    
    Q --> M
    R --> S[Idle State]
    
    S --> T{User Interaction?}
    T -->|Filter Applied| U[Apply Filters]
    T -->|Priority Click| V[Filter by Priority]
    T -->|No Action| S
    
    U --> G
    V --> G
    
    style I fill:#e3f2fd
    style J fill:#f3e5f5
    style K fill:#e8f5e8
    style L fill:#fff3e0
```

---

## 7. Claim Management Workflow

```mermaid
sequenceDiagram
    participant A as Agent
    participant D as Dashboard
    participant API as Backend API
    participant DB as Database
    participant N as Notification System
    
    A->>D: View assigned claims
    D->>API: GET /api/claims?agent=current
    API->>DB: Query agent's claims
    DB-->>API: Claim data
    API-->>D: Formatted claims list
    D-->>A: Display claims table
    
    A->>D: Click edit claim status
    D->>A: Show status dropdown
    A->>D: Select new status + add remarks
    D->>API: PUT /api/claims/{id}
    
    API->>DB: Update claim record
    API->>DB: Create audit log entry
    DB-->>API: Confirm updates
    
    API->>N: Trigger recalculation
    N->>API: Update priority score
    API->>DB: Update priority if changed
    
    API-->>D: Success response
    D-->>A: Show success notification
    D->>API: Refresh dashboard stats
    API-->>D: Updated metrics
    D-->>A: Real-time dashboard update
    
    Note over A,N: Audit trail maintained for compliance
```

---

## 8. Data Processing Architecture

```mermaid
graph TB
    subgraph "Input Layer"
        A[CSV Upload]
        B[Manual Entry]
        C[API Integration]
    end
    
    subgraph "Validation Layer"
        D[File Format Check]
        E[Data Type Validation]
        F[Business Rule Validation]
        G[Duplicate Detection]
    end
    
    subgraph "Processing Engine"
        H[Data Normalization]
        I[Priority Calculation]
        J[Agent Assignment]
        K[Aging Categorization]
    end
    
    subgraph "Business Logic"
        L[Scoring Algorithm]
        M[Assignment Rules]
        N[SLA Tracking]
        O[Escalation Logic]
    end
    
    subgraph "Data Storage"
        P[(Claims Database)]
        Q[(Audit Log)]
        R[(User Management)]
        S[(Configuration)]
    end
    
    subgraph "Output Layer"
        T[Dashboard Updates]
        U[Notifications]
        V[Reports]
        W[API Responses]
    end
    
    A --> D
    B --> E
    C --> F
    
    D --> H
    E --> H
    F --> H
    G --> H
    
    H --> I
    I --> J
    J --> K
    
    I --> L
    J --> M
    K --> N
    N --> O
    
    L --> P
    M --> P
    N --> Q
    O --> R
    
    P --> T
    Q --> U
    R --> V
    S --> W
    
    style A fill:#e3f2fd
    style H fill:#f3e5f5
    style L fill:#fff3e0
    style P fill:#e8f5e8
    style T fill:#fce4ec
```

---

## 9. System Integration Flow

```mermaid
graph LR
    subgraph "Frontend (SPA)"
        A[HTML Pages]
        B[JavaScript Modules]
        C[CSS Styling]
        D[Chart.js Visualization]
    end
    
    subgraph "API Layer (FastAPI)"
        E[Authentication Routes]
        F[Claims Management]
        G[Dashboard Analytics]
        H[File Upload Handler]
        I[User Management]
    end
    
    subgraph "Business Logic"
        J[Priority Engine]
        K[Assignment Engine]
        L[Validation Engine]
        M[Notification Engine]
    end
    
    subgraph "Data Layer"
        N[(PostgreSQL)]
        O[SQLAlchemy ORM]
        P[Connection Pool]
    end
    
    subgraph "External Systems"
        Q[CSV Files]
        R[Future EMR Integration]
        S[Reporting Tools]
    end
    
    A <--> E
    B <--> F
    C <--> G
    D <--> H
    
    E <--> J
    F <--> K
    G <--> L
    H <--> M
    I <--> J
    
    J <--> O
    K <--> O
    L <--> O
    M <--> O
    
    O <--> P
    P <--> N
    
    Q --> H
    F --> R
    G --> S
    
    style A fill:#e3f2fd
    style E fill:#f3e5f5
    style J fill:#fff3e0
    style N fill:#e8f5e8
```

---

## 10. Security and Compliance Flow

```mermaid
flowchart TD
    A[User Request] --> B{HTTPS Check}
    B -->|No| C[Reject Connection]
    B -->|Yes| D[JWT Validation]
    
    D --> E{Token Valid?}
    E -->|No| F[401 Unauthorized]
    E -->|Yes| G[Role Verification]
    
    G --> H{Authorized?}
    H -->|No| I[403 Forbidden]
    H -->|Yes| J[Input Validation]
    
    J --> K{Valid Input?}
    K -->|No| L[400 Bad Request]
    K -->|Yes| M[SQL Injection Check]
    
    M --> N{Safe Query?}
    N -->|No| O[Block Request]
    N -->|Yes| P[Process Request]
    
    P --> Q[Audit Log Entry]
    Q --> R[Execute Business Logic]
    R --> S[Response Generation]
    
    S --> T[Data Sanitization]
    T --> U[Send Response]
    
    style C fill:#ffcdd2
    style F fill:#ffcdd2
    style I fill:#ffcdd2
    style L fill:#ffcdd2
    style O fill:#ffcdd2
    style U fill:#e8f5e8
```

---

## Summary

These workflow diagrams provide comprehensive visual documentation of the Healthcare RCM AR Follow-Up Engine's core processes:

### **Key Workflows Covered:**
1. **System Overview** - High-level user interaction patterns
2. **Authentication** - Secure user access and session management
3. **Data Import** - CSV processing and validation pipeline
4. **Prioritization** - AI-powered claim scoring algorithm
5. **Agent Assignment** - Business rule-driven claim routing
6. **Dashboard Analytics** - Real-time data visualization
7. **Claim Management** - User interaction and data updates
8. **Data Architecture** - Technical processing layers
9. **System Integration** - Component interaction patterns
10. **Security Flow** - Protection and compliance measures

### **Benefits of These Diagrams:**
- **Developer Onboarding** - Clear technical understanding
- **Stakeholder Communication** - Business process visualization
- **System Documentation** - Comprehensive workflow reference
- **Troubleshooting Guide** - Process flow for debugging
- **Future Enhancement Planning** - Architecture understanding for new features

These diagrams can be used with any Mermaid-compatible documentation system or converted to other formats as needed for presentations and technical documentation.