turftracker/README.md

TurfTracker - Professional Lawn Care Management

TurfTracker is a comprehensive web application designed for homeowners to track and manage their lawn care activities including fertilizer applications, weed control, mowing schedules, and equipment management.

Features

✅ Completed Features

• User Authentication & Authorization

  • Local account registration and login
  • OAuth2 Google Sign-In integration
  • Role-based access control (Admin/User)
  • Password reset functionality

• Property Management

  • Multiple property support
  • Satellite view integration for area mapping
  • Lawn section creation and management
  • Square footage calculation

• Equipment Management

  • Equipment type catalog (mowers, spreaders, sprayers, etc.)
  • Detailed equipment specifications
  • Application rate calculations
  • Tank size and nozzle configuration for sprayers

• Product Management

  • Shared product database with application rates
  • Custom user products
  • Fertilizer, herbicide, and pesticide tracking
  • Multiple application rates per product

• Application Planning & Execution

  • Create application plans
  • Calculate product and water requirements
  • Tank mixing support
  • GPS tracking integration (framework ready)

• History & Logging

  • Complete application history
  • Weather condition logging
  • Speed and area coverage tracking
  • Detailed reporting

• Weather Integration

  • Current weather conditions
  • 5-day forecast
  • Application suitability checking
  • Historical weather data

• Admin Dashboard

  • User management
  • Product catalog management
  • System health monitoring
  • Usage statistics

🚧 Planned Features

• Google Maps Integration - Enhanced satellite view and area calculation
• GPS Speed Monitoring - Real-time speed feedback during applications
• Mobile App - Native iOS/Android applications

Technology Stack

• Frontend: React 18, Tailwind CSS, React Router, React Query
• Backend: Node.js, Express.js, PostgreSQL
• Authentication: JWT, OAuth2 (Google)
• Infrastructure: Docker, Nginx
• APIs: OpenWeatherMap, Google Maps (planned)

Quick Start

Prerequisites

• Docker and Docker Compose
• Git

Installation

1. Clone the repository

   git clone <repository-url>
   cd turftracker
   

2. Environment Configuration

   Create environment files with your API keys:

   Backend Environment (create .env in root):

   # Database
   DATABASE_URL=postgresql://turftracker:password123@db:5432/turftracker
   
   # Authentication
   JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
   
   # Google OAuth2 (optional)
   GOOGLE_CLIENT_ID=your-google-client-id
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   
   # Weather API (get free key from OpenWeatherMap)
   WEATHER_API_KEY=your-openweathermap-api-key
   
   # App URLs
   FRONTEND_URL=http://localhost:3000
   

3. Start the application

   docker-compose up -d
   

4. Access the application

   • Frontend: http://localhost:3000
   • Backend API: http://localhost:5000
   • Database: localhost:5432

First Time Setup

1. Create an admin account

   • Go to http://localhost:3000/register
   • Register with your email and password
   • The first user becomes an admin automatically

2. Add your first property

   • Navigate to Properties
   • Click "Add Property"
   • Enter property details and location

3. Set up equipment

   • Go to Equipment section
   • Add your lawn care equipment
   • Configure sprayer tank sizes and nozzle specifications

4. Add products

   • Browse the Products section
   • Add custom products or use the pre-loaded database
   • Configure application rates

API Keys Setup

OpenWeatherMap API Key

1. Go to OpenWeatherMap
2. Sign up for a free account
3. Get your API key from the dashboard
4. Add it to your .env file as WEATHER_API_KEY

Google OAuth2 (Optional)

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable Google+ API
4. Create OAuth2 credentials
5. Add http://localhost:5000/api/auth/google/callback as redirect URI
6. Add client ID and secret to your .env file

Google Maps API (Future Enhancement)

1. Go to Google Cloud Console
2. Enable Maps JavaScript API and Geocoding API
3. Create an API key
4. Will be integrated in future updates

Application Structure

turftracker/
├── backend/                 # Node.js API server
│   ├── src/
│   │   ├── routes/         # API endpoints
│   │   ├── middleware/     # Authentication, validation
│   │   ├── config/         # Database configuration
│   │   └── utils/          # Helper functions
│   └── package.json
├── frontend/               # React application
│   ├── src/
│   │   ├── components/     # Reusable UI components
│   │   ├── pages/          # Page components
│   │   ├── contexts/       # React contexts
│   │   ├── hooks/          # Custom React hooks
│   │   └── services/       # API client
│   └── package.json
├── database/               # PostgreSQL schema
│   └── init.sql           # Database initialization
├── nginx/                  # Reverse proxy configuration
│   └── nginx.conf
└── docker-compose.yml      # Container orchestration

Usage Guide

Property Management

1. Add Properties: Set up multiple lawn areas with addresses
2. Create Sections: Divide properties into manageable sections
3. Calculate Areas: Use the satellite view to map out exact lawn areas

Equipment Setup

1. Add Equipment: Register all your lawn care equipment
2. Configure Sprayers: Enter tank size, pump GPM, and nozzle specifications
3. Set Spreader Width: Configure spreader coverage width

Product Management

1. Browse Products: Use the pre-loaded product database
2. Add Custom Products: Create entries for specialized products
3. Set Application Rates: Configure rates for different application types

Application Planning

1. Create Plans: Select section, equipment, and products
2. Review Calculations: Check product amounts and water requirements
3. Check Weather: Verify conditions are suitable for application
4. Execute Plan: Follow the calculated application rates

History & Reporting

1. Log Applications: Record completed treatments
2. Track Weather: Automatic weather condition logging
3. View Reports: Analyze application history and effectiveness
4. Export Data: Download reports for record keeping

API Documentation

The backend provides a comprehensive REST API. Key endpoints include:

• Authentication: /api/auth/*
• Properties: /api/properties/*
• Equipment: /api/equipment/*
• Products: /api/products/*
• Applications: /api/applications/*
• Weather: /api/weather/*
• Admin: /api/admin/*

Development

Running in Development Mode

1. Backend Development

   cd backend
   npm install
   npm run dev
   

2. Frontend Development

   cd frontend
   npm install
   npm start
   

3. Database Setup

   docker-compose up db -d
   

Project Roadmap

• Google Maps integration for enhanced property mapping
• Mobile application development
• GPS speed monitoring with audio feedback
• Advanced reporting and analytics
• Weather-based application recommendations
• Integration with IoT sensors
• Multi-language support

Contributing

This is a personal project, but contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is licensed under the MIT License.

Support

For questions or issues:

1. Check the documentation above
2. Review the application logs: docker-compose logs
3. Ensure all environment variables are configured
4. Verify API keys are valid and have proper permissions

Security Considerations

• Change default passwords in production
• Use strong JWT secrets
• Enable HTTPS in production
• Regularly update dependencies
• Follow security best practices for API key management