353 lines
13 KiB
Markdown
353 lines
13 KiB
Markdown
# TimeTrack
|
|
|
|
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 multi-tenancy support, role-based access control, project management, team collaboration, billing/invoicing, and secure authentication with 2FA and password reset functionality. It includes a Progressive Web App (PWA) interface with mobile-optimized features.
|
|
|
|
## Features
|
|
|
|
### 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
|
|
- **Password Reset**: Secure email-based password recovery (1-hour token expiry)
|
|
- **Role-Based Access Control**: System Admin, Admin, Supervisor, Team Leader, and Team Member roles
|
|
- **Multi-Tenancy**: Complete data isolation between companies
|
|
- **User Administration**: Create, edit, block/unblock users with email verification
|
|
- **Profile Management**: Update email, password, avatar, and personal settings
|
|
- **Company Invitations**: Invite users to join your company via email
|
|
|
|
### Team & Project Management
|
|
- **Team Management**: Create teams, assign members, and track team hours
|
|
- **Project Management**: Create projects with codes, categories, billing types (hourly/daily/fixed)
|
|
- **Sprint Management**: Agile sprint planning and tracking
|
|
- **Task Management**: Create and manage tasks with subtasks and dependencies
|
|
- **Notes System**: Create, organize, and share notes with folder structure
|
|
- **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, Excel, and PDF export capabilities
|
|
- **Individual Time Export**: Personal time entries with date range selection
|
|
- **Team Hours Export**: Export team member hours with filtering options
|
|
- **Invoice Generation**: Create and export invoices with tax configurations
|
|
- **Analytics Dashboard**: Visual analytics with charts and statistics
|
|
- **Quick Export Options**: Today, week, month, or all-time data exports
|
|
|
|
### Administrative Features
|
|
- **Company Management**: Multi-company support with separate settings
|
|
- **Admin Dashboard**: System overview with user, team, and activity statistics
|
|
- **System Settings**: Configure registration, email verification, tracking scripts
|
|
- **Work Configuration**: Set work hours, break rules, and rounding preferences
|
|
- **Tax Configuration**: Country-specific tax rates for invoicing
|
|
- **Branding**: Custom logos, colors, and application naming
|
|
- **User Administration**: Complete user lifecycle management
|
|
- **Team & Project Administration**: Full CRUD operations for teams and projects
|
|
- **System Admin Tools**: Multi-company oversight and system health monitoring
|
|
|
|
## Tech Stack
|
|
|
|
- **Backend**: Flask 2.0.1 with SQLAlchemy ORM
|
|
- **Database**: PostgreSQL (production)
|
|
- **Migrations**: Flask-Migrate (Alembic-based) with custom helpers
|
|
- **Authentication**: Session-based with 2FA and password reset via Flask-Mail
|
|
- **Frontend**: Server-side Jinja2 templates with vanilla JavaScript
|
|
- **Mobile**: Progressive Web App (PWA) with mobile-optimized UI
|
|
- **Export**: Pandas for CSV/Excel, ReportLab for PDF generation
|
|
- **Containerization**: Docker and Docker Compose for easy deployment
|
|
- **Dependencies**: See requirements.txt for complete dependency list
|
|
|
|
## Installation
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.9+
|
|
- PostgreSQL 15+ (for production)
|
|
- Docker & Docker Compose (recommended)
|
|
|
|
### Quick Start with Docker (Recommended)
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://github.com/nullmedium/TimeTrack.git
|
|
cd TimeTrack
|
|
|
|
# Copy and configure environment variables
|
|
cp .env.example .env
|
|
# Edit .env with your settings
|
|
|
|
# Start the application
|
|
docker-compose up -d
|
|
|
|
# Access at http://localhost:5000
|
|
```
|
|
|
|
### Local Development Setup
|
|
|
|
```bash
|
|
# Create virtual environment
|
|
python -m venv .venv
|
|
source .venv/bin/activate # On Windows: .venv\Scripts\activate
|
|
|
|
# Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# Set environment variables
|
|
export DATABASE_URL="postgresql://user:pass@localhost/timetrack"
|
|
export SECRET_KEY="your-secret-key"
|
|
export MAIL_SERVER="smtp.example.com"
|
|
# ... other environment variables
|
|
|
|
# Run migrations
|
|
python create_migration.py "Initial setup"
|
|
python apply_migration.py
|
|
|
|
# Run the application
|
|
python app.py
|
|
```
|
|
|
|
### First-Time Setup
|
|
|
|
1. **Start the Application**: The database is automatically created and initialized on first startup
|
|
2. **Admin Account**: An initial admin user is created automatically with username `admin` and password `admin`
|
|
3. **Change Default Password**: **IMPORTANT**: Change the default admin password immediately after first login
|
|
4. **System Configuration**: Access Admin Dashboard to configure system settings
|
|
5. **Team Setup**: Create teams and assign team leaders
|
|
6. **Project Creation**: Set up projects with codes and team assignments
|
|
7. **User Management**: Add users and assign appropriate roles
|
|
|
|
### Database Migrations
|
|
|
|
**Flask-Migrate System**: The application uses Flask-Migrate (Alembic-based) for database version control.
|
|
|
|
```bash
|
|
# Create a new migration
|
|
python create_migration.py "Description of changes"
|
|
|
|
# Apply migrations
|
|
python apply_migration.py
|
|
|
|
# Check migration status
|
|
python check_migration_state.py
|
|
|
|
# For Docker environments
|
|
docker exec timetrack-timetrack-1 python create_migration.py "Description"
|
|
docker exec timetrack-timetrack-1 python apply_migration.py
|
|
```
|
|
|
|
The migration system handles:
|
|
- Automatic schema updates on container startup
|
|
- PostgreSQL-specific features (enums, constraints)
|
|
- Safe rollback capabilities
|
|
- Multi-tenancy data isolation
|
|
- Preservation of existing data during schema changes
|
|
|
|
### Configuration
|
|
|
|
#### Environment Variables
|
|
|
|
```bash
|
|
# Database
|
|
DATABASE_URL=postgresql://user:password@host:5432/dbname
|
|
|
|
# Flask
|
|
SECRET_KEY=your-secret-key-here
|
|
FLASK_ENV=development # or production
|
|
|
|
# Email (required for invitations and password reset)
|
|
MAIL_SERVER=smtp.example.com
|
|
MAIL_PORT=587
|
|
MAIL_USE_TLS=true
|
|
MAIL_USERNAME=your-email@example.com
|
|
MAIL_PASSWORD=your-password
|
|
|
|
# Optional
|
|
FORCE_HTTPS=true # Force HTTPS in production
|
|
TRUST_PROXY_HEADERS=true # When behind reverse proxy
|
|
```
|
|
|
|
#### Application Settings
|
|
|
|
- **Company Settings**: Work hours, break requirements, time rounding
|
|
- **User Preferences**: Date/time formats, timezone, UI preferences
|
|
- **System Settings**: Registration, email verification, tracking scripts
|
|
- **Branding**: Custom logos, colors, and naming
|
|
|
|
## 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
|
|
- **Password Reset**: Secure email-based recovery with time-limited tokens
|
|
- **Role-Based Access Control**: Five distinct user roles with granular permissions
|
|
- **Multi-Tenancy**: Complete data isolation between companies
|
|
- **Session Management**: Secure sessions with configurable lifetime
|
|
- **Email Verification**: Optional email verification for new accounts
|
|
- **Password Strength**: Enforced password complexity requirements
|
|
- **Security Headers**: HSTS, CSP, X-Frame-Options, and more
|
|
- **Input Validation**: Comprehensive server-side validation
|
|
- **CSRF Protection**: Built-in Flask CSRF protection
|
|
|
|
## Features for Mobile Users
|
|
|
|
- **Progressive Web App**: Install TimeTrack as an app on mobile devices
|
|
- **Mobile Navigation**: Bottom navigation bar and hamburger menu
|
|
- **Touch Optimization**: 44px minimum touch targets throughout
|
|
- **Responsive Tables**: Automatic card view on small screens
|
|
- **Mobile Gestures**: Swipe navigation and pull-to-refresh
|
|
- **Date/Time Pickers**: Mobile-friendly pickers respecting user preferences
|
|
- **Offline Support**: Basic offline functionality with service workers
|
|
- **Performance**: Lazy loading and optimized for mobile networks
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
TimeTrack/
|
|
├── app.py # Main Flask application
|
|
├── models/ # Database models organized by domain
|
|
│ ├── user.py # User, Role, UserPreferences
|
|
│ ├── company.py # Company, CompanySettings
|
|
│ ├── project.py # Project, ProjectCategory
|
|
│ ├── time_entry.py # TimeEntry model
|
|
│ └── ... # Other domain models
|
|
├── routes/ # Blueprint-based route handlers
|
|
│ ├── auth.py # Authentication routes
|
|
│ ├── projects.py # Project management
|
|
│ ├── teams.py # Team management
|
|
│ └── ... # Other route modules
|
|
├── templates/ # Jinja2 templates
|
|
├── static/ # CSS, JS, images
|
|
│ ├── css/ # Stylesheets including mobile
|
|
│ ├── js/ # JavaScript including PWA support
|
|
│ └── manifest.json # PWA manifest
|
|
├── migrations/ # Flask-Migrate/Alembic migrations
|
|
├── docker-compose.yml # Docker configuration
|
|
└── requirements.txt # Python dependencies
|
|
```
|
|
|
|
## API Endpoints
|
|
|
|
Key application routes organized by function:
|
|
- `/` - Home dashboard
|
|
- `/login`, `/logout`, `/register` - Authentication
|
|
- `/forgot_password`, `/reset_password/<token>` - Password recovery
|
|
- `/time-tracking` - Main time tracking interface
|
|
- `/projects/*` - Project management
|
|
- `/teams/*` - Team management
|
|
- `/tasks/*` - Task and sprint management
|
|
- `/notes/*` - Notes system
|
|
- `/invoices/*` - Billing and invoicing
|
|
- `/export/*` - Data export functionality
|
|
- `/admin/*` - Administrative functions
|
|
- `/system-admin/*` - System administration (multi-company)
|
|
|
|
## Deployment
|
|
|
|
### Production Deployment with Docker
|
|
|
|
```bash
|
|
# Clone and configure
|
|
git clone https://github.com/nullmedium/TimeTrack.git
|
|
cd TimeTrack
|
|
cp .env.example .env
|
|
# Edit .env with production values
|
|
|
|
# Build and start
|
|
docker-compose -f docker-compose.yml up -d
|
|
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# Backup database
|
|
docker exec timetrack-db-1 pg_dump -U timetrack timetrack > backup.sql
|
|
```
|
|
|
|
### Reverse Proxy Configuration (Nginx)
|
|
|
|
```nginx
|
|
server {
|
|
listen 80;
|
|
server_name timetrack.example.com;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:5000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
|
proxy_set_header X-Forwarded-Proto $scheme;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Migration Errors**
|
|
- Check current state: `python check_migration_state.py`
|
|
- View migration history: `flask db history`
|
|
- Fix revision conflicts in alembic_version table
|
|
|
|
2. **Docker Issues**
|
|
- Container not starting: `docker logs timetrack-timetrack-1`
|
|
- Database connection: Ensure PostgreSQL is healthy
|
|
- Permission errors: Check volume permissions
|
|
|
|
3. **Email Not Sending**
|
|
- Verify MAIL_* environment variables
|
|
- Check firewall rules for SMTP port
|
|
- Enable "less secure apps" if using Gmail
|
|
|
|
4. **2FA Issues**
|
|
- Ensure system time is synchronized
|
|
- QR code not scanning: Check for firewall blocking images
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
4. Push to the branch (`git push origin feature/amazing-feature`)
|
|
5. Open a Pull Request
|
|
|
|
### Development Guidelines
|
|
|
|
- Follow PEP 8 for Python code
|
|
- Write tests for new features
|
|
- Update documentation as needed
|
|
- Ensure migrations are reversible
|
|
- Test on both PostgreSQL and SQLite
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## Acknowledgments
|
|
|
|
- Flask community for the excellent framework
|
|
- Contributors and testers
|
|
- Open source projects that made this possible
|