TimeTracker/docs/development/PROJECT_STRUCTURE.md

TimeTracker Project Structure

This document provides an overview of the cleaned up TimeTracker project structure after removing unnecessary files and consolidating the codebase.

📁 Root Directory Structure

TimeTracker/
├── 📁 app/                    # Main Flask application
│   ├── blueprint_registry.py  # Centralized blueprint registration
│   ├── routes/                # Route blueprints (auth, api, tasks, workforce, etc.)
│   ├── templates/            # Jinja2 HTML templates
│   ├── models/                # SQLAlchemy models
│   ├── services/              # Business logic layer
│   └── utils/                 # Utilities (timezone, validation, etc.)
├── 📁 desktop/                # Desktop app (Electron/Tauri-style wrapper, esbuild bundle)
├── 📁 mobile/                 # Flutter mobile app
├── 📁 assets/                 # Static assets (images, screenshots)
├── 📁 docker/                 # Docker configuration files
├── 📁 tests/                  # Test suite
├── 📁 .github/                # GitHub workflows and configurations
├── 📁 logs/                   # Application logs (with .gitkeep)
├── 🐳 Dockerfile              # Main Dockerfile
├── 📄 docker-compose.yml          # Default stack (HTTPS via nginx)
├── 📄 docker-compose.example.yml # HTTP on port 8080 (no nginx)
├── 📄 docker/docker-compose.local-test.yml # SQLite, HTTP 8080 (quick test)
├── 📄 docker/docker-compose.remote.yml   # Remote/production compose (ghcr.io)
├── 📄 docker/docker-compose.remote-dev.yml # Remote dev/testing compose (ghcr.io)
├── 📄 requirements.txt         # Python dependencies
├── 📄 app.py                  # Application entry point
├── 📄 env.example             # Environment variables template
├── 📄 README.md               # Main project documentation
├── 📄 CONTRIBUTING.md         # Contribution guidelines
├── 📄 CODE_OF_CONDUCT.md      # Community code of conduct
├── 📄 LICENSE                 # GPL v3 license
├── 📄 GITHUB_WORKFLOW_IMAGES.md  # Docker image workflow docs
├── 📄 DOCKER_PUBLIC_SETUP.md     # Public container setup docs
├── 📄 REQUIREMENTS.md         # Detailed requirements documentation
├── 📄 deploy-public.bat       # Windows deployment script
└── 📄 deploy-public.sh        # Linux/Mac deployment script

🧹 Cleanup Summary

Files Removed

• DATABASE_INIT_FIX_FINAL_README.md - Database fix documentation (resolved)
• DATABASE_INIT_FIX_README.md - Database fix documentation (resolved)
• TIMEZONE_FIX_README.md - Timezone fix documentation (resolved)
• Dockerfile.test - Test Dockerfile (not needed)
• Dockerfile.combined - Combined Dockerfile (consolidated)
• docker-compose.yml - Old compose file (replaced)
• deploy.sh - Old deployment script (replaced)
• index.html - Unused HTML file
• _config.yml - Unused config file
• logs/timetracker.log - Large log file (not in version control)
• .pytest_cache/ - Python test cache directory

Files Consolidated

• Dockerfiles: Primary Dockerfile at repo root; additional Dockerfiles in docker/ as needed
• Docker Compose: docker-compose.yml (local), docker/docker-compose.remote.yml, docker/docker-compose.remote-dev.yml
• Deployment: deploy-public.bat, deploy-public.sh

🏗️ Core Components

Application (app/)

• blueprint_registry.py: Centralized registration of all route blueprints (reduces __init__.py size). Optional blueprints log logger.exception on failure; in local development (FLASK_ENV=development or DEBUG) failures re-raise; production and tests continue without that blueprint.
• Models: Database models for users, projects, time entries, tasks, and settings
• Routes: API endpoints and web routes (auth, api, api_v1, tasks, admin, etc.)
• Templates: Jinja2 HTML templates under app/templates/ (task management, reports, timer, etc.)
• Utils: Utility functions including timezone management, validation, cache
• Config: Application configuration (app/config.py)

Docker Configuration (docker/)

• Startup scripts: Container initialization and database setup
• Database scripts: SQL-based database initialization
• Configuration files: Docker-specific configurations

Templates (app/templates/)

• All Jinja2 templates live under app/templates/ (admin, main, projects, reports, tasks, timer, workforce, mileage, etc.)

Assets (assets/)

• Screenshots: Application screenshots for documentation
• Images: Logo and other static images

🚀 Deployment Options

1. Default stack (HTTPS)

• File: docker-compose.yml
• Image: Built from local source
• Use case: Quick start and production; serves https://localhost (nginx + self-signed cert).

2. HTTP (no HTTPS)

• File: docker-compose.example.yml — app on http://localhost:8080 (published image or build).
• File: docker/docker-compose.local-test.yml — SQLite, http://localhost:8080 (no PostgreSQL).

3. Remote/Production

• File: docker/docker-compose.remote.yml
• Image: ghcr.io/drytrix/timetracker:latest (or versioned tag)
• Use case: Production deployment

4. Remote Dev/Testing

• File: docker/docker-compose.remote-dev.yml
• Image: ghcr.io/drytrix/timetracker:development
• Use case: Pre-release testing

📚 Documentation Files

• README.md (root): Main project documentation and quick start guide
• CONTRIBUTING.md (root): Contributing — quick overview; full guidelines in CONTRIBUTING.md (this folder)
• CODE_OF_CONDUCT.md (this folder): CODE_OF_CONDUCT.md — community guidelines
• ARCHITECTURE.md: Architecture overview
• INSTALLATION.md (root): Installation guide
• DEVELOPMENT.md: Development guide
• API.md: API quick reference
• PROJECT_STRUCTURE.md (this folder): Project structure overview
• TASK_MANAGEMENT_README.md (docs/): Detailed Task Management feature documentation

✅ Workforce & Timesheet Governance

Timesheet periods, policies, and time-off tracking for payroll and compliance:

• Models: TimesheetPeriod, TimesheetPolicy, TimeOff (in app/models/)
• Routes: workforce blueprint — dashboard, period close, policies, time-off, delete (periods, time-off requests, leave types, holidays)
• Services: workforce_governance_service.py — period close, policy checks, time-off logic, delete (period, leave request, leave type, holiday)
• Templates: app/templates/workforce/ (e.g. dashboard, with delete buttons where allowed)
• Migration: 132_add_timesheet_governance_and_time_off.py
• Docs: Workforce delete feature (Issue #562)

✅ Task Management Feature

The Task Management feature is fully integrated into the application with automatic database migration:

Automatic Migration

• No manual setup required: Database tables are created automatically on first startup
• Integrated migration: Migration logic is built into the application initialization
• Fallback support: Manual migration script available if needed

Components Added

• Models: Task model with full relationship support
• Routes: Complete CRUD operations for task management
• Templates: Responsive task management interface
• Integration: Tasks linked to projects and time tracking
• GITHUB_WORKFLOW_IMAGES.md: Docker image build workflow
• DOCKER_PUBLIC_SETUP.md: Public container setup guide
• REQUIREMENTS.md: Detailed system requirements

🔧 Development Files

• requirements.txt: Python package dependencies
• app.py: Flask application entry point
• env.example: Environment variables template
• tests/: Test suite and test files

📝 Key Improvements Made

1. Removed Duplicate Files: Eliminated redundant documentation and configuration files
2. Consolidated Docker Setup: Streamlined to two main container types
3. Updated Documentation: README now reflects current project state
4. Timezone Support: Added comprehensive timezone management (100+ options)
5. Clean Structure: Organized project for better maintainability

🎯 Getting Started

1. Choose deployment type: Local dev, remote, or remote-dev
2. Follow README.md: Complete setup instructions
3. Use appropriate compose file: docker-compose.yml, docker/docker-compose.remote.yml, or docker/docker-compose.remote-dev.yml
4. Configure timezone: Access admin settings to set your local timezone

Versioning

• Canonical app version: Defined in setup.py (single source of truth). Do not duplicate the version in other docs.
• Desktop: desktop/package.json version should align with the app version when the desktop client ships with that release.
• Frontend build: Root package.json is for Tailwind/build tooling and may use a separate semver (e.g. 1.0.0).
• API docs (OpenAPI): GET /api/openapi.json sets info.version from get_version_from_setup() in app/config/analytics_defaults.py (reads setup.py at runtime). TIMETRACKER_VERSION or APP_VERSION may override that for CI or containers; if still unknown, app/routes/api_docs.py falls back to Flask APP_VERSION config. Do not hardcode a version string in the spec.

🔍 File Purposes

• .gitkeep files: Ensure empty directories are tracked in Git
• .github/: GitHub Actions workflows for automated builds
• logs/: Application log storage (cleaned up, only .gitkeep remains)
• LICENSE: GPL v3 open source license
• .gitignore: Git ignore patterns for temporary files

This cleaned up structure provides a more maintainable and focused codebase while preserving all essential functionality and documentation.