mirror of
https://github.com/DRYTRIX/TimeTracker.git
synced 2026-05-19 12:50:11 -05:00
Dries Peeters
29f7186ee8
Complete reorganization of project documentation to improve discoverability, navigation, and maintainability. All documentation has been restructured into a clear, role-based hierarchy. ## Major Changes ### New Directory Structure - Created `docs/api/` for API documentation - Created `docs/admin/` with subdirectories: - `admin/configuration/` - Configuration guides - `admin/deployment/` - Deployment guides - `admin/security/` - Security documentation - `admin/monitoring/` - Monitoring and analytics - Created `docs/development/` for developer documentation - Created `docs/guides/` for user-facing guides - Created `docs/reports/` for analysis reports and summaries - Created `docs/changelog/` for detailed changelog entries (ready for future use) ### File Organization #### Moved from Root Directory (40+ files) - Implementation notes → `docs/implementation-notes/` - Test reports → `docs/testing/` - Analysis reports → `docs/reports/` - User guides → `docs/guides/` #### Reorganized within docs/ - API documentation → `docs/api/` - Administrator documentation → `docs/admin/` (with subdirectories) - Developer documentation → `docs/development/` - Security documentation → `docs/admin/security/` - Telemetry documentation → `docs/admin/monitoring/` ### Documentation Updates #### docs/README.md - Complete rewrite with improved navigation - Added visual documentation map - Organized by role (Users, Administrators, Developers) - Better categorization and quick links - Updated all internal links to new structure #### README.md (root) - Updated all documentation links to reflect new structure - Fixed 8 broken links #### app/templates/main/help.html - Enhanced "Where can I get additional help?" section - Added links to new documentation structure - Added documentation index link - Added admin documentation link for administrators - Improved footer with organized documentation links - Added "Complete Documentation" section with role-based links ### New Index Files - Created README.md files for all new directories: - `docs/api/README.md` - `docs/guides/README.md` - `docs/reports/README.md` - `docs/development/README.md` - `docs/admin/README.md` ### Cleanup - Removed empty `docs/security/` directory (moved to `admin/security/`) - Removed empty `docs/telemetry/` directory (moved to `admin/monitoring/`) - Root directory now only contains: README.md, CHANGELOG.md, LICENSE ## Results **Before:** - 45+ markdown files cluttering root directory - Documentation scattered across root and docs/ - Difficult to find relevant documentation - No clear organization structure **After:** - 3 files in root directory (README, CHANGELOG, LICENSE) - Clear directory structure organized by purpose and audience - Easy navigation with role-based organization - All documentation properly categorized - Improved discoverability ## Benefits 1. Better Organization - Documentation grouped by purpose and audience 2. Easier Navigation - Role-based sections (Users, Admins, Developers) 3. Improved Discoverability - Clear structure with README files in each directory 4. Cleaner Root - Only essential files at project root 5. Maintainability - Easier to add and organize new documentation ## Files Changed - 40+ files moved from root to appropriate docs/ subdirectories - 15+ files reorganized within docs/ - 3 major documentation files updated (docs/README.md, README.md, help.html) - 5 new README index files created - 2 empty directories removed All internal links have been updated to reflect the new structure.
136 lines
2.7 KiB
Markdown
136 lines
2.7 KiB
Markdown
# 🐛 Bug Fix: Import Errors in Route Files
|
|
|
|
## Issues
|
|
|
|
### Issue 1: Import Error for 'db'
|
|
|
|
**Error**:
|
|
```
|
|
ImportError: cannot import name 'db' from 'app.models'
|
|
```
|
|
|
|
**Cause**: Two route files were trying to import `db` from `app.models`, but `db` is defined in `app/__init__.py`, not in the models module.
|
|
|
|
### Issue 2: Missing Module 'db_helpers'
|
|
|
|
**Error**:
|
|
```
|
|
ModuleNotFoundError: No module named 'app.utils.db_helpers'
|
|
```
|
|
|
|
**Cause**: Two route files were trying to import from `app.utils.db_helpers`, but the module is actually named `app.utils.db`.
|
|
|
|
---
|
|
|
|
## 🔧 Fixes Applied
|
|
|
|
### Changed Files (2)
|
|
|
|
#### 1. `app/routes/time_entry_templates.py`
|
|
|
|
**Fix 1 - Wrong db import source:**
|
|
```python
|
|
# Before (WRONG)
|
|
from app.models import TimeEntryTemplate, Project, Task, db
|
|
|
|
# After (CORRECT)
|
|
from app import db
|
|
from app.models import TimeEntryTemplate, Project, Task
|
|
```
|
|
|
|
**Fix 2 - Wrong module name for safe_commit:**
|
|
```python
|
|
# Before (WRONG)
|
|
from app.utils.db_helpers import safe_commit
|
|
|
|
# After (CORRECT)
|
|
from app.utils.db import safe_commit
|
|
```
|
|
|
|
#### 2. `app/routes/saved_filters.py`
|
|
|
|
**Fix 1 - Wrong db import source:**
|
|
```python
|
|
# Before (WRONG)
|
|
from app.models import SavedFilter, db
|
|
|
|
# After (CORRECT)
|
|
from app import db
|
|
from app.models import SavedFilter
|
|
```
|
|
|
|
**Fix 2 - Wrong module name for safe_commit:**
|
|
```python
|
|
# Before (WRONG)
|
|
from app.utils.db_helpers import safe_commit
|
|
|
|
# After (CORRECT)
|
|
from app.utils.db import safe_commit
|
|
```
|
|
|
|
---
|
|
|
|
## ✅ Verification
|
|
|
|
```bash
|
|
python -m py_compile app/routes/time_entry_templates.py
|
|
python -m py_compile app/routes/saved_filters.py
|
|
|
|
✅ Both files compile successfully
|
|
```
|
|
|
|
---
|
|
|
|
## 📝 Notes
|
|
|
|
### Correct Import Patterns
|
|
|
|
#### Pattern 1: Database Instance (`db`)
|
|
|
|
In Flask-SQLAlchemy applications, the `db` object should always be imported from the main app module:
|
|
|
|
```python
|
|
# ✅ CORRECT
|
|
from app import db
|
|
from app.models import SomeModel
|
|
|
|
# ❌ WRONG
|
|
from app.models import SomeModel, db
|
|
```
|
|
|
|
This is because:
|
|
1. `db` is created in `app/__init__.py`
|
|
2. Models import `db` from `app` to define themselves
|
|
3. Trying to import `db` from `app.models` creates a circular dependency issue
|
|
|
|
#### Pattern 2: Utility Functions
|
|
|
|
Always verify the actual module name before importing utilities:
|
|
|
|
```python
|
|
# ✅ CORRECT - Check what exists in app/utils/
|
|
from app.utils.db import safe_commit
|
|
|
|
# ❌ WRONG - Assuming a module name
|
|
from app.utils.db_helpers import safe_commit
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Ready to Deploy
|
|
|
|
The application should now start successfully. Run:
|
|
|
|
```bash
|
|
docker-compose restart app
|
|
```
|
|
|
|
---
|
|
|
|
**Date**: 2025-10-23
|
|
**Type**: Bug Fix
|
|
**Severity**: Critical (prevented startup)
|
|
**Resolution Time**: < 5 minutes
|
|
**Bugs Fixed**: 2 (import errors)
|
|
**Files Modified**: 2 route files
|