Skip to content

PROJECT_STRUCTURE.md

Latest commit

 

History

History
184 lines (148 loc) · 9.93 KB

PROJECT_STRUCTURE.md

File metadata and controls

184 lines (148 loc) · 9.93 KB
Raw

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)

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

✅ 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.