From 668e7c85e0f3d6497d57ba21512d22b8cf9ec577 Mon Sep 17 00:00:00 2001 From: Jens Luedicke Date: Sun, 29 Jun 2025 17:26:31 +0200 Subject: [PATCH] Update README.md and add a LICENSE file. --- LICENSE | 21 +++++++++ README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 145 insertions(+), 10 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0901957 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 Jens Luedicke, jens@luedicke.cloud + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. \ No newline at end of file diff --git a/README.md b/README.md index 8fda83b..7e1d533 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,49 @@ # TimeTrack -TimeTrack is a web-based time tracking application built with Flask that helps users monitor their work hours, breaks, and maintain a history of their time entries. +TimeTrack is a comprehensive web-based time tracking application built with Flask that provides enterprise-level time management capabilities for teams and organizations. The application features role-based access control, project management, team collaboration, and secure authentication. ## Features -- **Time Tracking**: Record arrival and departure times -- **Break Management**: Pause and resume work sessions -- **Daily Overview**: View today's time entries at a glance -- **Complete History**: Access all past time entries -- **Configuration**: Customize work hours and break settings +### Core Time Tracking +- **Real-time Time Tracking**: Clock in/out with live timer functionality +- **Project Time Logging**: Track time spent on specific projects with project codes +- **Break Management**: Configurable mandatory and additional break tracking +- **Time Entry Management**: Edit, delete, and view time entries with complete history +- **Automatic Calculations**: Duration calculations for work hours and breaks + +### User Management & Security +- **Two-Factor Authentication (2FA)**: TOTP-based authentication with QR codes +- **Role-Based Access Control**: Admin, Supervisor, Team Leader, and Team Member roles +- **User Administration**: Create, edit, block/unblock users with verification system +- **Profile Management**: Update email, password, and personal settings + +### Team & Project Management +- **Team Management**: Create teams, assign members, and track team hours +- **Project Management**: Create projects with codes, assign to teams, set active/inactive status +- **Team Hours Tracking**: View team member working hours with date filtering +- **Project Assignment**: Flexible project-team assignments and access control + +### Export & Reporting +- **Multiple Export Formats**: CSV and Excel export capabilities +- **Individual Time Export**: Personal time entries with date range selection +- **Team Hours Export**: Export team member hours with filtering options +- **Quick Export Options**: Today, week, month, or all-time data exports + +### Administrative Features +- **Admin Dashboard**: System overview with user, team, and activity statistics +- **System Settings**: Configure registration settings and global preferences +- **User Administration**: Complete user lifecycle management +- **Team & Project Administration**: Full CRUD operations for teams and projects ## Tech Stack -- **Backend**: Flask 2.0.1 -- **Database**: SQLAlchemy with SQLite -- **Frontend**: HTML, CSS, JavaScript +- **Backend**: Flask 2.0.1 with SQLAlchemy ORM +- **Database**: SQLite with comprehensive relational schema +- **Authentication**: Flask session management with 2FA support +- **Frontend**: Responsive HTML, CSS, JavaScript with real-time updates +- **Security**: TOTP-based two-factor authentication, role-based access control +- **Export**: CSV and Excel export capabilities +- **Dependencies**: See Pipfile for complete dependency list ## Installation @@ -36,9 +65,94 @@ pipenv install # Activate the virtual environment pipenv shell -# Initialize the database +# Initialize the database and run migrations python migrate_db.py +python migrate_roles_teams.py # Add role and team support +python migrate_projects.py # Add project management # Run the application python app.py ``` + +### First-Time Setup + +1. **Admin Account**: Create the first admin user through the registration page +2. **System Configuration**: Access Admin Dashboard to configure system settings +3. **Team Setup**: Create teams and assign team leaders +4. **Project Creation**: Set up projects with codes and team assignments +5. **User Management**: Add users and assign appropriate roles + +### Database Migrations + +The application includes several migration scripts to upgrade existing installations: + +- `migrate_db.py`: Core database initialization +- `migrate_roles_teams.py`: Add role-based access control and team management +- `migrate_projects.py`: Add project management capabilities +- `repair_roles.py`: Fix role assignments if needed + +### Configuration + +The application can be configured through: +- **Admin Dashboard**: System-wide settings and user management +- **User Profiles**: Individual work hour and break preferences +- **Environment Variables**: Database and Flask configuration + +## Usage + +### For Regular Users +1. **Register/Login**: Create account or log in with existing credentials +2. **Setup 2FA**: Optionally enable two-factor authentication for enhanced security +3. **Clock In/Out**: Use the timer interface to track work hours +4. **Manage Breaks**: Record and track break periods +5. **View History**: Access complete time entry history with filtering +6. **Export Data**: Download time entries in CSV or Excel format + +### For Team Leaders +1. **Manage Team Members**: View team member status and activity +2. **Track Team Hours**: Monitor team working hours with date filtering +3. **Export Team Data**: Generate team hour reports + +### For Supervisors/Admins +1. **User Management**: Create, edit, and manage user accounts +2. **Team Administration**: Create teams and assign members +3. **Project Management**: Set up projects and assign to teams +4. **System Configuration**: Configure global settings and permissions +5. **Analytics**: View system-wide statistics and activity + +## Security Features + +- **Two-Factor Authentication**: TOTP-based 2FA with QR code setup +- **Role-Based Access Control**: Four distinct user roles with appropriate permissions +- **Session Management**: Secure login/logout with "remember me" functionality +- **Data Validation**: Comprehensive input validation and error handling +- **Account Verification**: Email verification system for new accounts + +## API Endpoints + +The application provides various endpoints for different user roles: +- `/admin/*`: Administrative functions (Admin only) +- `/supervisor/*`: Supervisor functions (Supervisor+ roles) +- `/team/*`: Team management (Team Leader+ roles) +- `/export/*`: Data export functionality +- `/auth/*`: Authentication and profile management + +## File Structure + +- `app.py`: Main Flask application +- `models.py`: Database models and relationships +- `templates/`: HTML templates for all pages +- `static/`: CSS and JavaScript files +- `migrate_*.py`: Database migration scripts + +## Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test thoroughly +5. Submit a pull request + +## License + +This project is licensed under the MIT License.