|
| 1 | +# VeritaScribe Dashboard |
| 2 | + |
| 3 | +Interactive error management dashboard for VeritaScribe thesis analysis reports. Available in both FastHTML and Panel implementations. |
| 4 | + |
| 5 | +## 🌟 Features |
| 6 | + |
| 7 | +- **📊 Interactive Error Management**: Mark errors as resolved, dismissed, or in progress |
| 8 | +- **🔍 Advanced Filtering**: Filter by status, type, severity, page, confidence score |
| 9 | +- **📈 Visual Analytics**: Charts showing error distribution, progress, and statistics |
| 10 | +- **⚡ Real-time Updates**: HTMX (FastHTML) or reactive widgets (Panel) |
| 11 | +- **📋 Bulk Operations**: Update multiple errors simultaneously |
| 12 | +- **💾 Persistent Storage**: SQLite database for error state management |
| 13 | +- **📁 Import/Export**: Load VeritaScribe JSON reports and export results |
| 14 | + |
| 15 | +## 🚀 Quick Start |
| 16 | + |
| 17 | +### 1. Install Dependencies |
| 18 | + |
| 19 | +```bash |
| 20 | +cd dashboard |
| 21 | +pip install -r requirements.txt |
| 22 | +``` |
| 23 | + |
| 24 | +### 2. Choose Your Framework |
| 25 | + |
| 26 | +**Option A: FastHTML (Web-native, HTMX-powered)** |
| 27 | +```bash |
| 28 | +python launch_fasthtml.py |
| 29 | +# Opens at http://localhost:8000 |
| 30 | +``` |
| 31 | + |
| 32 | +**Option B: Panel (Scientific computing focus)** |
| 33 | +```bash |
| 34 | +python launch_panel.py |
| 35 | +# Opens at http://localhost:5007 |
| 36 | +``` |
| 37 | + |
| 38 | +### 3. Import Your Data |
| 39 | + |
| 40 | +1. Click "Import" in the navigation |
| 41 | +2. Upload your VeritaScribe JSON report |
| 42 | +3. Start managing errors! |
| 43 | + |
| 44 | +## 📁 Architecture |
| 45 | + |
| 46 | +Both implementations share 85% of their codebase: |
| 47 | + |
| 48 | +``` |
| 49 | +dashboard/ |
| 50 | +├── core/ # 🔄 SHARED COMPONENTS |
| 51 | +│ ├── models.py # Enhanced data models with error management |
| 52 | +│ ├── error_manager.py # SQLite database and business logic |
| 53 | +│ ├── data_processor.py # JSON loading/conversion utilities |
| 54 | +│ ├── visualizations.py # Plotly charts (works in both frameworks) |
| 55 | +│ └── __init__.py |
| 56 | +├── fasthtml_app/ # 🚀 FastHTML Implementation |
| 57 | +│ ├── app.py # Main FastHTML application |
| 58 | +│ ├── components.py # HTML components and templates |
| 59 | +│ └── __init__.py |
| 60 | +├── panel_app/ # 📊 Panel Implementation |
| 61 | +│ ├── app.py # Main Panel application |
| 62 | +│ └── __init__.py |
| 63 | +├── tests/ # 🧪 Test Suite |
| 64 | +│ └── test_dashboard.py # Comprehensive tests |
| 65 | +├── requirements.txt # Dependencies |
| 66 | +├── launch_fasthtml.py # FastHTML launcher |
| 67 | +├── launch_panel.py # Panel launcher |
| 68 | +└── README.md |
| 69 | +``` |
| 70 | + |
| 71 | +## 🎯 Error Management Workflow |
| 72 | + |
| 73 | +### Status Tracking |
| 74 | +- **🔴 Pending**: Newly detected errors |
| 75 | +- **🟡 In Progress**: Being worked on (assigned) |
| 76 | +- **🟢 Resolved**: Fixed and verified |
| 77 | +- **⚪ Dismissed**: Intentionally ignored |
| 78 | +- **🔵 Needs Review**: Requires second opinion |
| 79 | + |
| 80 | +### Filtering Options |
| 81 | +- **Status**: Pending, In Progress, Resolved, etc. |
| 82 | +- **Error Type**: Citation, Grammar, Content Plausibility |
| 83 | +- **Severity**: High, Medium, Low |
| 84 | +- **Page Range**: Specific page numbers |
| 85 | +- **Confidence**: AI confidence scores |
| 86 | +- **Search**: Text search in error content |
| 87 | + |
| 88 | +### Bulk Operations |
| 89 | +- Mark multiple errors as resolved |
| 90 | +- Dismiss false positives in bulk |
| 91 | +- Assign errors to team members |
| 92 | +- Export filtered error lists |
| 93 | + |
| 94 | +## 📊 Visualizations |
| 95 | + |
| 96 | +Both frameworks use the same Plotly charts: |
| 97 | + |
| 98 | +- **Error Summary**: Bar charts by type and severity |
| 99 | +- **Status Distribution**: Pie chart of error statuses |
| 100 | +- **Page Heatmap**: Error distribution across document pages |
| 101 | +- **Confidence Analysis**: Histogram of AI confidence scores |
| 102 | +- **Progress Timeline**: Resolution progress over time |
| 103 | +- **Workload Distribution**: Errors by assignee |
| 104 | + |
| 105 | +## 🔧 Technical Details |
| 106 | + |
| 107 | +### FastHTML Implementation |
| 108 | +- **Framework**: FastHTML with HTMX for dynamic interactions |
| 109 | +- **Styling**: Custom CSS with modern design |
| 110 | +- **Interactions**: Server-side rendering with HTMX updates |
| 111 | +- **Benefits**: Clean URLs, fast loading, mobile-responsive |
| 112 | + |
| 113 | +### Panel Implementation |
| 114 | +- **Framework**: Panel with Param for reactive programming |
| 115 | +- **Widgets**: Tabulator for advanced table features |
| 116 | +- **Interactions**: Client-side reactivity with automatic updates |
| 117 | +- **Benefits**: Scientific computing integration, Jupyter compatibility |
| 118 | + |
| 119 | +### Shared Core |
| 120 | +- **Database**: SQLite for persistent error state |
| 121 | +- **Models**: Pydantic for data validation |
| 122 | +- **Visualizations**: Plotly for interactive charts |
| 123 | +- **Processing**: Pandas for data manipulation |
| 124 | + |
| 125 | +## 🧪 Testing |
| 126 | + |
| 127 | +Run the test suite to validate both implementations: |
| 128 | + |
| 129 | +```bash |
| 130 | +cd dashboard |
| 131 | +python -m pytest tests/test_dashboard.py -v |
| 132 | +``` |
| 133 | + |
| 134 | +Tests cover: |
| 135 | +- Data import/export functionality |
| 136 | +- Error filtering and management |
| 137 | +- Bulk operations |
| 138 | +- Visualization generation |
| 139 | +- Database persistence |
| 140 | +- Complete workflow integration |
| 141 | + |
| 142 | +## 📈 Performance |
| 143 | + |
| 144 | +**Shared Components Benefits**: |
| 145 | +- 85% code reuse between frameworks |
| 146 | +- Consistent visualization appearance |
| 147 | +- Single database for both implementations |
| 148 | +- Unified data processing logic |
| 149 | + |
| 150 | +**Framework Comparison**: |
| 151 | +- **FastHTML**: Lighter weight, faster initial load |
| 152 | +- **Panel**: Richer widgets, better for data exploration |
| 153 | + |
| 154 | +## 🔒 Data Security |
| 155 | + |
| 156 | +- Local SQLite database (no cloud dependencies) |
| 157 | +- No external API calls for core functionality |
| 158 | +- User activity logging for audit trails |
| 159 | +- Export capabilities for backup/archival |
| 160 | + |
| 161 | +## 🛠️ Development |
| 162 | + |
| 163 | +### Adding New Features |
| 164 | + |
| 165 | +1. **Shared Logic**: Add to `core/` modules |
| 166 | +2. **FastHTML UI**: Update `fasthtml_app/` components |
| 167 | +3. **Panel UI**: Update `panel_app/` widgets |
| 168 | +4. **Tests**: Add to `tests/test_dashboard.py` |
| 169 | + |
| 170 | +### Database Schema |
| 171 | + |
| 172 | +The SQLite database includes: |
| 173 | +- `errors`: Main error table with status tracking |
| 174 | +- `documents`: Document metadata |
| 175 | +- `activity_log`: User action audit trail |
| 176 | + |
| 177 | +## 🤝 Contributing |
| 178 | + |
| 179 | +1. Fork the repository |
| 180 | +2. Create your feature branch |
| 181 | +3. Add tests for new functionality |
| 182 | +4. Ensure both FastHTML and Panel implementations work |
| 183 | +5. Submit a pull request |
| 184 | + |
| 185 | +## 📝 License |
| 186 | + |
| 187 | +Part of the VeritaScribe project. See main project for license details. |
| 188 | + |
| 189 | +--- |
| 190 | + |
| 191 | +**Choose your preferred framework and start managing thesis errors more efficiently!** 🎓✨ |
0 commit comments