Projects and more

PROJECT_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,128 @@
+# Project Implementation Summary
+
+## Overview
+Successfully implemented the "projects" feature that allows users to organize sessions into projects. Each project can contain multiple sessions, providing better organization and management capabilities.
+
+## Files Created
+
+### 1. Core Logic
+- **`src/core/logic/project_handler.py`** - New class for managing projects, including creation, deletion, and metadata management
+
+### 2. User Interface Screens
+- **`src/core/screens/projects_window.py`** - Main project management interface
+- **`src/core/screens/create_project_window.py`** - Interface for creating new projects
+- **`src/core/screens/project_sessions_window.py`** - Project-specific session management
+
+### 3. Utilities
+- **`src/core/utils/migration.py`** - Migration script to move existing sessions to the new project structure
+
+## Files Modified
+
+### 1. Core Logic Updates
+- **`src/core/logic/file_handler.py`** - Enhanced to work with project-aware file operations
+- **`src/core/logic_root.py`** - Added ProjectHandler to the logic controller
+
+### 2. User Interface Updates
+- **`src/core/screens/create_session_window.py`** - Added project selection dropdown
+- **`src/core/screens/main_window.py`** - Updated navigation to include project management
+- **`src/core/gui_root.py`** - Added new screens to the application
+
+### 3. Utilities Updates
+- **`src/core/utils/file_utils.py`** - Added project-related utility functions
+- **`src/main.py`** - Added migration check on application startup
+
+## Key Features Implemented
+
+### 1. Project Management
+- Create new projects with validation
+- Delete projects (with safety checks)
+- View project information and session counts
+- Set current active project
+
+### 2. Session Organization
+- Sessions are now stored within project directories
+- Each session includes project metadata
+- Project-aware session loading and saving
+- Session count tracking per project
+
+### 3. User Interface Enhancements
+- **ProjectsWindow**: List all projects with session counts and current project indicator
+- **CreateProjectWindow**: Create new projects with name validation
+- **ProjectSessionsWindow**: View and manage sessions within a specific project
+- **Enhanced CreateSessionWindow**: Select project when creating new sessions
+
+### 4. Data Structure Changes
+- **New Directory Structure**:
+  ```
+  AppUsageGUI/
+  ├── Projects/
+  │   ├── No Project/
+  │   │   ├── session1.dat
+  │   │   ├── session1.hash
+  │   │   └── ...
+  │   ├── Project1/
+  │   │   ├── session1.dat
+  │   │   └── ...
+  │   └── Project2/
+  │       └── ...
+  └── User/
+      ├── config.dat
+      └── apps.dat
+  ```
+
+- **Enhanced Session Data**:
+  ```python
+  {
+      'app_name': session_app_name,
+      'time_spent': session_time,
+      'session_version': session_version,
+      'config': self.config,
+      'time_captures': captures,
+      'project_name': project_name,    # NEW
+      'created_date': timestamp,       # NEW
+      'last_modified': timestamp       # NEW
+  }
+  ```
+
+###
+
+## Navigation Flow
+
+### New User Flow
+```
+MainWindow → ProjectsWindow → ProjectSessionsWindow → SelectAppWindow → TrackerWindow
+         → CreateProjectWindow
+         → CreateSessionWindow (with project selection)
+```
+
+### Updated MainWindow Options
+- "Start new session" - Goes to app selection
+- "Manage Projects" - Goes to project management
+- "Continue previous session" - Goes to projects (then sessions)
+- "Configure custom rules" - Settings (unchanged)
+
+## Backward Compatibility
+- Old session data structure is preserved
+- No data loss during migration
+- Graceful handling of missing project information
+
+## Benefits
+1. **Organization**: Sessions grouped by project for better management
+2. **Scalability**: Can handle many projects without cluttering interface
+3. **Flexibility**: Easy to add project-specific settings or metadata
+4. **Backup**: Can backup/restore entire projects
+5. **Analytics**: Project-level time tracking and reporting capabilities
+
+## Testing Recommendations
+2. Test project creation and deletion
+3. Test session creation within different projects
+4. Test navigation between projects and sessions
+5. Test data integrity after migration
+6. Test with multiple projects and sessions
+
+## Future Enhancements
+- Project-specific settings and configurations
+- Project-level time analytics and reporting
+- Project export/import functionality
+- Project templates
+- Project collaboration features

README.md

@@ -1,33 +1,160 @@
-![version](https://img.shields.io/badge/Version-1.5.1-white.svg)
+![version](https://img.shields.io/badge/Version-2.0.0-white.svg)
 ![license](https://img.shields.io/badge/License-GPL%20v3-blue.svg)
 ![python](https://img.shields.io/badge/Python-3.12-green.svg)
 
 # AppUsageGUI
 ### Application Runtime Tracker
 
-This program tracks the runtime of a specified application, logging the duration the application is running over multiple instances, with unique sessions created by the user.
+This program tracks the runtime of specified applications, organizing sessions into projects for better management. Users can create multiple projects, each containing multiple tracking sessions, providing comprehensive time tracking and organization capabilities.
 
 ## How It Works
 
-AppUsageGUI is a cross-platform desktop application built with Python and Tkinter that monitors application usage time. The application works by:
+AppUsageGUI is a cross-platform desktop application built with Python and Tkinter that monitors application usage time with project-based organization. The application works by:
 
-1. **Process Monitoring**: Uses the `psutil` library to detect running applications and monitor their process status
-2. **Time Tracking**: Implements a precise time tracker that runs in a separate thread, capable of pausing and resuming
-3. **Session Management**: Creates named sessions that can be saved, loaded, and continued across application restarts
-4. **Data Persistence**: Saves session data with integrity checking using hash verification
-5. **Cross-Platform Support**: Handles Windows and macOS differences in process detection and GUI application filtering
+1. **Project Organization**: Users create projects to organize related tracking sessions, with each project containing multiple sessions
+2. **Session Creation**: Before tracking begins, users select a project and name their session, establishing clear organization upfront
+3. **Process Monitoring**: Uses the `psutil` library to detect running applications and monitor their process status
+4. **Time Tracking**: Implements a precise time tracker that runs in a separate thread, capable of pausing and resuming
+5. **Session Management**: Creates named sessions within projects that can be saved, loaded, and continued across application restarts
+6. **Data Persistence**: Saves session data with integrity checking using hash verification, organized by project directories
+7. **Cross-Platform Support**: Handles Windows and macOS differences in process detection and GUI application filtering
 
 The application follows a Model-View-Controller (MVC) architecture with separate logic and GUI components, ensuring clean separation of concerns and maintainable code.
 
+## Project and Session Structure
+
+AppUsageGUI organizes your time tracking data using a hierarchical project-based structure. This allows you to group related sessions together and manage your time tracking more effectively.
+
+### Data Organization
+
+```
+AppUsageGUI/
+├── Sessions/                          # Standalone sessions (No Project)
+│   ├── session1.dat
+│   ├── session1.hash
+│   ├── session2.dat
+│   └── session2.hash
+├── Projects/                          # Project-organized sessions
+│   ├── Web Development/               # Custom project
+│   │   ├── frontend_work.dat
+│   │   ├── frontend_work.hash
+│   │   ├── backend_api.dat
+│   │   └── backend_api.hash
+│   ├── Design Projects/               # Another custom project
+│   │   ├── logo_design.dat
+│   │   ├── logo_design.hash
+│   │   └── ui_mockup.dat
+│   └── projects_metadata.json         # Project information and metadata
+└── User/
+    ├── config.dat                     # User configuration
+    └── apps.dat                       # Tracked applications list
+```
+
+### Project Structure Diagram
+
+```mermaid
+graph TD
+    A[AppUsageGUI Application] --> B[Sessions Directory]
+    A --> C[Projects Directory]
+
+    B --> B1[Session 1]
+    B --> B2[Session 2]
+    B --> B3[Session N...]
+
+    C --> D[Web Development]
+    C --> E[Design Projects]
+    C --> F[Other Projects...]
+
+    D --> D1[Frontend Work]
+    D --> D2[Backend API]
+    D --> D3[Database Design]
+
+    E --> E1[Logo Design]
+    E --> E2[UI Mockup]
+    E --> E3[Brand Guidelines]
+
+    B1 --> B1A[session1.dat]
+    B1 --> B1B[session1.hash]
+
+    D1 --> D1A[frontend_work.dat]
+    D1 --> D1B[frontend_work.hash]
+
+    style A fill:#e1f5fe
+    style B fill:#fff3e0
+    style C fill:#f3e5f5
+    style D fill:#e8f5e8
+    style E fill:#fce4ec
+```
+
+### Key Concepts
+
+- **Projects**: Top-level containers that group related sessions together, stored in the `Projects/` directory
+- **Standalone Sessions**: Sessions not assigned to any project, stored directly in the `Sessions/` directory
+- **"No Project"**: A UI label for sessions that aren't assigned to any project (not an actual project directory)
+- **Sessions**: Individual time tracking instances that can belong to a project or exist standalone
+- **Session Files**: Each session consists of a `.dat` file (data) and `.hash` file (integrity check)
+- **Metadata**: Project information is stored in `projects_metadata.json` including creation dates and session counts
+
+### Session Data Structure
+
+Each session file contains comprehensive tracking information:
+
+```python
+{
+    'app_name': 'Visual Studio Code',           # Application being tracked
+    'time_spent': 7200.5,                      # Total time in seconds
+    'session_version': '2.0.0',                # App version when created
+    'config': {...},                           # Tracking configuration
+    'time_captures': [...],                    # Detailed time capture data
+    'project_name': 'Web Development',         # Project this session belongs to
+    'created_date': '2024-01-15T10:30:00',    # When session was created
+    'last_modified': '2024-01-15T12:30:00'    # Last modification time
+}
+```
+
+### Benefits of Project Organization
+
+1. **Better Organization**: Group related work sessions together
+2. **Easier Management**: Quickly find and manage sessions by project
+3. **Project Analytics**: View total time spent on specific projects
+4. **Scalability**: Handle many sessions without interface clutter
+5. **Backup & Restore**: Backup entire projects or migrate between systems
+6. **Future Extensibility**: Foundation for project-specific settings and reporting
+
 ## Features
 
-- Supports tracking the total runtime of any executable
-- Supports continuation from previous sessions
-- User customizable tracking rules
-- Cross-platform support (Windows and macOS) - macOS installation is janky because of permissions required
-- Session data integrity with hash verification
-- Pause/resume functionality during tracking
-- Automatic detection of GUI applications vs background processes
+- **Project Management**: Organize sessions into projects for better organization and management
+- **Session Tracking**: Track the total runtime of any executable with named sessions
+- **Session Continuation**: Continue from previous sessions within any project
+- **User Customizable Rules**: Configure custom tracking rules and application filtering
+- **Cross-Platform Support**: Works on Windows and macOS (macOS installation requires permissions)
+- **Data Integrity**: Session data integrity with hash verification
+- **Pause/Resume**: Pause and resume functionality during active tracking
+- **Smart Detection**: Automatic detection of GUI applications vs background processes
+- **Project Analytics**: View total time spent across all sessions within a project
+- **Migration Support**: Automatic migration of existing sessions to the new project structure
+
+## User Workflow
+
+### New Session Creation
+The application now uses a streamlined workflow where users select their project and session name before starting the timer:
+
+1. **Main Menu** → "Start new session"
+2. **Create Session Window** → Select project and enter session name
+3. **Select App Window** → Choose application to track
+4. **Tracker Window** → Timer runs with pause/resume controls
+5. **Save Window** → Save session data
+6. **Session Total Window** → View results and statistics
+
+### Project Management
+- **Main Menu** → "Manage Projects" → View all projects with session counts and total time
+- **Create New Project** → Set up new project containers
+- **View Project Sessions** → Manage sessions within specific projects
+- **Delete Projects** → Remove projects and all associated sessions (with confirmation)
+
+### Continuing Existing Sessions
+- **Main Menu** → "Continue previous session" → Navigate through projects to find and resume sessions
+- Sessions can be continued across application restarts with full state preservation
 
 ## Installation
 
@@ -56,27 +183,31 @@ To install, follow the instructions for your platform found here:
 
 #### Main Controllers
 - **`gui_root.py`** - Main GUI controller that manages the application's window system, initializes all screens, and handles navigation between different windows
-- **`logic_root.py`** - Central logic controller that coordinates all tracking components (AppTracker, TimeTracker, FileHandler, MouseTracker)
+- **`logic_root.py`** - Central logic controller that coordinates all tracking components (AppTracker, TimeTracker, FileHandler, ProjectHandler, MouseTracker)
 
 #### Logic Components (`src/core/logic/`)
 - **`app_tracker.py`** - Monitors running processes using psutil, filters GUI applications from background processes, and maintains lists of available applications for tracking
 - **`time_tracker.py`** - Implements precise time tracking with pause/resume functionality, runs in a separate thread for accuracy, and captures timing data for analysis
 - **`file_handler.py`** - Manages session data persistence, handles file I/O operations with pickle serialization, and implements data integrity checking using hash verification
+- **`project_handler.py`** - Manages project creation, deletion, and organization, handles project metadata and session counts
 - **`user_trackers.py`** - Contains additional tracking modules like MouseTracker for user activity monitoring and ResolveProjectTracker for specific application integration
 
 #### User Interface (`src/core/screens/`)
-- **`main_window.py`** - Main menu screen providing options to start new sessions, continue previous sessions, or configure settings
+- **`main_window.py`** - Main menu screen providing options to start new sessions, manage projects, continue previous sessions, or configure settings
+- **`projects_window.py`** - Project management interface for viewing, creating, and deleting projects with session counts and total time
+- **`create_project_window.py`** - Project creation dialog with name validation and project setup
+- **`project_sessions_window.py`** - Project-specific session management interface for viewing and managing sessions within a project
+- **`create_session_window.py`** - Session creation dialog with project selection, name validation, and session setup
 - **`select_app_window.py`** - Application selection interface with search functionality and real-time app list updates
 - **`tracker_window.py`** - Active tracking display showing elapsed time, pause/resume controls, and stop functionality
-- **`sessions_window.py`** - Session management interface for loading, analyzing, and deleting saved sessions
-- **`create_session_window.py`** - Session creation dialog with name validation and confirmation
+- **`sessions_window.py`** - Global session management interface for loading, analyzing, and deleting saved sessions across all projects
 - **`save_window.py`** - Session saving interface with data confirmation
 - **`session_total_window.py`** - Session summary display showing total tracked time and statistics
 - **`tracker_settings_window.py`** - Configuration interface for custom tracking rules and application filtering
 - **`splash_screen.py`** - Application startup splash screen with loading animation
 
 #### Utilities (`src/core/utils/`)
-- **`file_utils.py`** - File system operations, directory management, session file handling, and data integrity functions
+- **`file_utils.py`** - File system operations, directory management, session file handling, project directory management, and data integrity functions
 - **`time_utils.py`** - Time formatting utilities for displaying elapsed time in human-readable format
 - **`logic_utils.py`** - Threading utilities and decorators for running functions in separate threads
 - **`tk_utils.py`** - Tkinter-specific utilities including window centering and dark mode detection
@@ -90,6 +221,6 @@ To install, follow the instructions for your platform found here:
 - **`build.py`** - Build script for creating distributable packages
 - **`requirements.txt`** - Python dependencies list
 - **`pytest.ini`** - Testing configuration
-- **`tests/`** - Unit tests for application components
+- **`tests/`** - Unit tests for application components including project management and session creation workflows