RxFlow Pharmacy Assistant - Modular UI Architecture¶

This document describes the modular architecture of the RxFlow Pharmacy Assistant UI components.

📁 Project Structure¶

rxflow_pharmacy_assistant/
├── app.py                          # Main Streamlit application entry point
├── pyproject.toml                  # Poetry dependencies & project config
├── docker-compose.yml              # Container orchestration
├── Dockerfile                      # Production Docker configuration
├── Makefile                        # Development commands
├── static/
│   └── css/
│       └── styles.css             # External CSS stylesheet
├── ui/
│   ├── __init__.py                # UI package initialization
│   ├── session_manager.py         # Session state management
│   ├── message_processor.py       # Message processing logic
│   └── components/
│       ├── __init__.py            # Components package initialization
│       ├── styles.py              # CSS loading and styling utilities
│       ├── header.py              # Header components (title, patient context, progress)
│       ├── chat.py                # Chat interface components
│       ├── sidebar.py             # Sidebar components and controls
│       ├── actions.py             # Action buttons and activity components
│       ├── debug.py               # Debug information and monitoring
│       └── data_utils.py          # Data loading and export utilities
├── rxflow/                        # Core application logic
│   ├── __init__.py
│   ├── llm.py                     # LLM integration layer
│   ├── config/                    # Configuration management
│   │   ├── __init__.py
│   │   └── settings.py
│   ├── services/                  # Mock API services
│   │   └── mock_data.py
│   ├── tools/                     # 16+ specialized healthcare tools
│   │   ├── __init__.py
│   │   ├── cost_tools.py
│   │   ├── escalation_tools.py
│   │   ├── order_tools.py
│   │   ├── patient_history_tool.py
│   │   ├── pharmacy_tools.py
│   │   └── rxnorm_tool.py
│   ├── utils/                     # Logging & helper utilities
│   │   ├── __init__.py
│   │   ├── documentation_report_generator.py
│   │   ├── helpers.py
│   │   └── logger.py
│   └── workflow/                  # AI conversation management
│       ├── __init__.py
│       ├── conversation_manager.py
│       ├── state_machine.py
│       ├── state.py
│       └── workflow_types.py
├── data/                          # Mock healthcare data
│   ├── drug_policies.txt
│   ├── mock_drugs.json
│   ├── mock_insurance.json
│   ├── mock_patients.json
│   ├── mock_pharmacies.json
│   └── submitted_orders.json
├── docs/                          # Complete documentation suite
│   ├── about.md
│   ├── index.md
│   ├── COMPREHENSIVE_DOCUMENTATION.md
│   ├── MODULAR_ARCHITECTURE.md
│   ├── api/                       # API documentation
│   ├── deployment/                # Docker & production deployment guides
│   ├── developer-guide/           # Technical implementation details
│   ├── getting-started/           # Installation and setup
│   └── user-guide/               # End-user documentation
├── tests/                         # Comprehensive test suite
│   ├── test_escalation_system.py
│   └── test_integration.py
├── logs/                          # Application logs
└── site/                          # Generated documentation site

🏗️ Architecture Benefits¶

1. Separation of Concerns¶

UI Components: Reusable, focused components for specific UI elements
Business Logic: Core pharmacy logic remains in rxflow/ package
Styling: External CSS file for maintainable styling
State Management: Centralized session management

2. Maintainability¶

Modular Components: Easy to update individual UI elements
Clear Dependencies: Each module has specific responsibilities
Reusable Code: Components can be reused across different views
Easier Testing: Individual components can be tested in isolation

3. Scalability¶

Plugin Architecture: Easy to add new UI components
Theme Management: Centralized styling with CSS variables
Component Library: Foundation for future UI expansions

📦 Component Overview¶

Core Application (`app.py`)¶

Main entry point and application orchestration
Minimal code focused on component coordination
Session initialization and message processing coordination

Static Assets (`static/`)¶

CSS Styles: External stylesheet with healthcare-focused design
Future Assets: Space for images, fonts, and other static resources

UI Package (`ui/`)¶

Session Management (`session_manager.py`)¶

# Key functions:
- initialize_session_state()  # Setup session variables
- reset_conversation()        # Clear and restart session
- add_quick_message()         # Handle quick action messages

Message Processing (`message_processor.py`)¶

# Key functions:
- process_user_input()        # Handle user messages
- process_user_input_async()  # Async conversation processing

Components (`ui/components/`)¶

Styling (`styles.py`)¶

# Key functions:
- load_css()                  # Load external CSS file
- apply_custom_css()          # Apply CSS to Streamlit
- get_page_config()           # Page configuration settings

Header Components (`header.py`)¶

# Key functions:
- render_main_header()        # Application title and subtitle
- render_patient_context()    # Patient information card
- render_progress_indicator() # Workflow progress steps

Chat Components (`chat.py`)¶

# Key functions:
- render_chat_interface()     # Main chat container
- render_chat_message()       # Individual message rendering
- render_empty_chat_state()   # Welcome message display

Sidebar Components (`sidebar.py`)¶

# Key functions:
- render_sidebar()            # Complete sidebar with all sections
- render_quick_links()        # Navigation shortcuts
- render_help_support()       # Help and support options
- render_advanced_options()   # Debug and export controls

Action Components (`actions.py`)¶

# Key functions:
- render_quick_actions()      # Quick action buttons
- render_recent_activity()    # Activity history display

Debug Components (`debug.py`)¶

# Key functions:
- render_debug_tabs()         # Debug information in tabs
- render_state_visualization()# Workflow state display
- render_tool_logs()          # Tool execution logs
- render_cost_savings()       # Cost analysis display

Data Utilities (`data_utils.py`)¶

# Key functions:
- load_demo_data()            # Load mock data from JSON files
- export_session_data()       # Export session for analysis

🎨 Styling Architecture¶

CSS Organization¶

The external CSS file (static/css/styles.css) is organized into logical sections:

/* Global Styles */
- Font imports and base application styling
- Streamlit branding removal

/* Layout Components */
- Header styling
- Patient context cards
- Chat interface styling

/* Interactive Elements */
- Button styling
- Form inputs
- Status indicators

/* Responsive Design */
- Mobile-friendly adjustments
- Flexible layouts

CSS Variables¶

The stylesheet uses consistent color schemes and spacing:

/* Healthcare Color Palette */
- Primary Blue: #3b82f6
- Success Green: #10b981
- Warning Orange: #d97706
- Error Red: #ef4444
- Neutral Gray: #6b7280

/* Spacing System */
- Consistent padding and margin values
- Responsive spacing adjustments

🔄 Data Flow¶

1. Application Startup¶

app.py main() → initialize_session_state() → apply_custom_css() → load_demo_data()

2. User Interface Rendering¶

render_main_header() → render_sidebar() → render_chat_interface() → render_quick_actions()

3. User Interaction¶

User Input → add_quick_message() → process_user_input() → Update Session State → Re-render UI

4. Component Communication¶

Session State ↔ UI Components ↔ Business Logic (rxflow/)

🛠️ Development Guidelines¶

Adding New Components¶

Create component file in ui/components/
Follow naming convention: [feature]_components.py
Import and use in app.py
Add CSS styling to static/css/styles.css

Modifying Existing Components¶

Update component file directly
Maintain function signatures for compatibility
Test with existing integrations
Update documentation as needed

Styling Updates¶

Modify static/css/styles.css
Use existing CSS classes when possible
Follow BEM naming convention for new classes
Test across different screen sizes

📱 Responsive Design¶

Breakpoints¶

Desktop: > 1024px (Default layout)
Tablet: 768px - 1024px (Adjusted spacing)
Mobile: < 768px (Stacked layout)

Adaptive Features¶

Sidebar: Collapsible on small screens
Chat Interface: Full-width on mobile
Action Buttons: Stack vertically on small screens

🔧 Configuration¶

Environment Setup¶

The modular architecture supports different configuration approaches:

# Development
DEBUG_MODE = True
LOAD_EXTERNAL_CSS = False  # Use inline CSS for hot reload

# Production
DEBUG_MODE = False
LOAD_EXTERNAL_CSS = True   # Use optimized external CSS

Feature Flags¶

Components support feature flags for gradual rollouts:

# In session_manager.py
ENABLE_DEBUG_TABS = st.session_state.get('show_debug_info', False)
ENABLE_COST_TRACKING = True
ENABLE_PATIENT_SWITCHING = True

🚀 Future Enhancements¶

Planned Improvements¶

Component Library: Standardized UI component library
Theme System: Multiple color themes and dark mode
Internationalization: Multi-language support
Advanced Layouts: Dashboard and grid-based layouts
Component Testing: Automated testing for UI components

Extension Points¶

Custom Themes: CSS variable system for easy theming
Plugin Components: Dynamic component loading
API Integration: Real-time data binding
State Persistence: Session state backup and restore

This modular architecture provides a solid foundation for maintaining and extending the RxFlow Pharmacy Assistant user interface while keeping the code organized and maintainable.