AI-powered desktop application for clinical therapists to analyze documentation compliance with Medicare and regulatory guidelines.

• Multi-format Support: PDF, DOCX, TXT with OCR capabilities
• AI-Powered Analysis: Local LLM processing for privacy compliance
• Compliance Scoring: Risk-weighted scoring with confidence indicators
• Interactive Reports: HTML reports with source highlighting

• Professional UI: React-based medical-themed design with blue branding
• Responsive Layout: Modern Electron desktop application
• Integrated Chat: AI assistant for compliance questions
• Theme Support: Light/Dark mode with persistent preferences

• Local Processing: All AI operations run locally (HIPAA compliant)
• PHI Protection: Automated detection and scrubbing of sensitive data
• Secure Authentication: JWT-based user management
• Encrypted Storage: Local SQLite database with encryption

• Dashboard: Historical compliance trends and metrics
• Export Options: PDF and HTML report generation
• Rubric Management: Custom compliance rules in TTL format
• Performance Tracking: System monitoring and optimization

• Python 3.11+ (Required for backend)
• Node.js 18+ (Required for frontend)
• 4GB+ RAM (Recommended for AI models)
• 2GB+ Storage (For models and data)

1. Clone the repository

   git clone <repository-url>
   cd therapy-compliance-analyzer

2. Create virtual environment

   python -m venv .venv
   .venv\Scripts\activate  # Windows
   # source .venv/bin/activate  # Linux/Mac

3. Install dependencies

   pip install -r requirements-optimized.txt

4. Install frontend dependencies

   cd frontend/electron-react-app
   npm install

5. Start the desktop application

   # Boots FastAPI backend + Electron renderer
   python start_robust.py

6. Login

   • Username: admin
   • Password: admin123

• Quick Start Guide - Get up and running in 5 minutes
• User Manual - Complete feature documentation
• Testing Guide - How to test all features

• Architecture Overview - System design and components
• Development Guide - Setup and contribution guidelines
• API Documentation - Technical stack and APIs
• Testing Guide - Comprehensive testing procedures

• Workflow Documentation - Complete system workflow
• Feature Checklist - Development progress
• Security Guidelines - Security best practices

+----------------------+    +---------------------+
| Electron + React UI  |    |     FastAPI API     |
|      (Frontend)      |<-->|      (Backend)      |
+----------------------+    +---------------------+
            |                           |
            v                           v
+----------------------+    +---------------------+
|   Local AI / ML      |    |   SQLite Database   |
|   Processing         |    |     (Encrypted)     |
+----------------------+    +---------------------+

• Frontend: Electron + React desktop application with modern UI
• Backend: FastAPI with modular router architecture (Python)
• AI/ML: Local processing with ctransformers, sentence-transformers
• Database: SQLAlchemy ORM with SQLite storage
• Security: JWT authentication, PHI scrubbing, local-only processing

1. Upload Document - Select PDF, DOCX, or TXT file
2. Choose Rubric - Select compliance guidelines (Medicare, Part B, etc.)
3. Set Strictness - Choose analysis level (Lenient, Standard, Strict)
4. Run Analysis - AI processes document for compliance issues
5. Review Results - Interactive report with findings and recommendations
6. Export Report - Generate PDF or HTML for documentation
7. Ask Questions - Use integrated chat for clarification

• Dashboard Analytics - View historical compliance trends
• Custom Rubrics - Create organization-specific rules
• Batch Processing - Analyze multiple documents
• Performance Monitoring - System health and optimization

DATABASE_URL="sqlite:///./compliance.db"
SECRET_KEY="your-super-secret-jwt-key"
ALGORITHM="HS256"
ACCESS_TOKEN_EXPIRE_MINUTES=30

• config.yaml - Main application settings
• .env - Environment variables and secrets
• pytest.ini - Test configuration

# Run all tests
pytest

# Run tests excluding slow ones
pytest -m "not slow"

# Run with coverage
pytest --cov=src

# Code quality checks
ruff check src/
mypy src/

• Startup Time: <5 seconds
• Analysis Time: 30-60 seconds per document
• Memory Usage: <2GB during normal operation
• Storage: ~500MB for AI models (downloaded on first run)

• Caching: LRU cache for frequently accessed data
• Background Processing: Non-blocking UI operations
• Model Optimization: Efficient AI model loading and inference
• Database Optimization: Connection pooling and query optimization

• Local Processing: All AI operations run on your machine
• No External Calls: No data sent to external APIs or services
• PHI Scrubbing: Automatic detection and redaction of sensitive information
• Encrypted Storage: Local database encryption for sensitive data

• JWT Authentication: Secure token-based authentication
• Input Validation: Comprehensive validation of all user inputs
• Rate Limiting: Protection against abuse and overload
• Audit Logging: Activity tracking without PHI exposure

1. Follow installation instructions above
2. Install development dependencies: pip install -r requirements-dev.txt
3. Run tests to ensure everything works: pytest
4. Follow coding standards: ruff check src/

• Linting: Use ruff for code formatting and linting
• Type Checking: Use mypy for static type analysis
• Testing: Write tests for new features using pytest
• Documentation: Update documentation for any changes

• ✅ Blue title color and modern UI improvements
• ✅ Reorganized layout with better scaling
• ✅ Integrated chat bar (removed separate chat tab)
• ✅ Enhanced color contrast and professional styling
• ✅ Comprehensive PDF export functionality
• ✅ Performance optimizations and fast exit

• ✅ Initial release with core functionality
• ✅ Document analysis and compliance scoring
• ✅ Interactive HTML reports
• ✅ Dashboard analytics and user management

1. Documentation: Check the comprehensive docs in .kiro/steering/
2. Testing: Use the testing checklist in .kiro/TESTING_CHECKLIST_NOW.md
3. Troubleshooting: Common issues and solutions documented
4. AI Assistant: Use the integrated chat for compliance questions

• PDF Export: Requires weasyprint for best results (pip install weasyprint)
• OCR: Requires tesseract for scanned document processing
• First Run: AI models download (~500MB) requires internet connection

This project is proprietary software. All rights reserved.

The Therapy Compliance Analyzer is ready to help you improve clinical documentation quality and ensure regulatory compliance.

Start analyzing today! 🏥✨

For technical support or questions, refer to the documentation in .kiro/steering/ or use the integrated AI assistant.

The src/core package contains the application’s analysis and ML services:

• Analysis pipeline (analysis_service.py): orchestrates ingestion → analysis → reporting with progress callbacks.
• Compliance analyzer (compliance_analyzer.py): rule/rubric evaluation and result shaping.
• Retrieval & embeddings (hybrid_retriever.py, vector_store.py): BM25 + dense retrieval, FAISS-backed vector index with graceful fallbacks.
• Guideline/rubric utilities (guideline_service.py, rubric_loader.py).
• NER and NLP (ner.py, Presidio integration) and model selection helpers.
• LLM integration (llm_service.py, report_generator.py, pdf_export_service.py).
• Performance integration (performance_integration.py) and utilities.

1. Generate a strong SECRET_KEY and set it in the environment:

# Generate a secure key
python scripts\generate_secret_key.py
# Set it for the current session
$env:SECRET_KEY = '<paste-generated-key>'

2. Start the API cleanly (frees port 8001, activates venv, sets env vars):

./scripts/start_api_clean.ps1 -ApiHost '127.0.0.1' -ApiPort 8001 -LogLevel 'INFO'

3. Quick end-to-end smoke (token → rubrics → upload → status):

python temp\dev_api_smoke.py

Notes:

• CORS is restricted to localhost by default.
• Mocks are disabled in config.yaml (use_ai_mocks: false). Enable via USE_AI_MOCKS=1 if needed for fast demos.

A GitHub Actions workflow (.github/workflows/ci.yml) runs tests on push/PR with a test secret and mocks enabled for reliability.