mirror of https://github.com/DRYTRIX/TimeTracker.git synced 2026-01-19 02:40:07 -06:00

Files

Dries Peeters 29f7186ee8 docs: Reorganize documentation structure for better navigation

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.

2025-12-14 07:56:07 +01:00

2.2 KiB

Raw Blame History

Integration System Refactoring Plan

Issues Identified

Double Pages: /calendar/integrations and /integrations - duplicate functionality
OAuth Requirements: Some integrations (Trello) don't need OAuth but are using OAuth flow
Global vs Per-User: All integrations are currently per-user, but should be global (except Google Calendar)
Setup Pages: Need dedicated setup pages for each integration instead of all in one settings page

Solution

1. Database Changes

✅ Migration 082: Add is_global flag to Integration model
✅ Make user_id nullable for global integrations
✅ Add constraint: global integrations must have user_id = NULL

2. Integration Classification

Global Integrations (shared across all users):

Jira
Slack
GitHub
Outlook Calendar
Microsoft Teams
Asana
Trello (API key based, not OAuth)
GitLab
QuickBooks
Xero

Per-User Integrations:

Google Calendar (each user connects their own)

3. OAuth vs API Key Requirements

OAuth Required:

Jira (OAuth 2.0)
Slack (OAuth 2.0)
GitHub (OAuth 2.0)
Google Calendar (OAuth 2.0) - per-user
Outlook Calendar (OAuth 2.0)
Microsoft Teams (OAuth 2.0)
Asana (OAuth 2.0)
GitLab (OAuth 2.0)
QuickBooks (OAuth 2.0)
Xero (OAuth 2.0)

API Key Based (no OAuth):

Trello (API Key + Token)

4. Implementation Steps

✅ Create migration for global integrations
✅ Update Integration model
Update IntegrationService to handle global integrations
Create admin setup pages for each integration
Fix Trello connector to use API key setup (not OAuth)
Remove duplicate calendar integrations page
Update routes to use global integrations
Update integration list page to show global vs per-user

Files to Modify

app/models/integration.py - Add is_global, make user_id nullable
app/services/integration_service.py - Handle global integrations
app/routes/integrations.py - Update to handle global
app/routes/admin.py - Add setup routes for each integration
app/integrations/trello.py - Fix to use API key setup
app/routes/calendar.py - Remove duplicate integrations page
app/templates/integrations/ - Create setup templates

2.2 KiB Raw Blame History