turftracker/README.md

TurfTracking - Professional Lawn Care Management

TurfTracking 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

• GPS Speed Monitoring - Real-time speed feedback during applications
• Mobile App - Native iOS/Android applications
• Advanced Reporting - PDF reports and data export
• IoT Integration - Sensor data integration

Technology Stack

• Frontend: React 18, Tailwind CSS, React Router, React Query, Leaflet Maps
• Backend: Node.js, Express.js, PostgreSQL
• Authentication: JWT, OAuth2 (Authentik)
• Infrastructure: Docker, Traefik
• Maps: OpenStreetMap via Leaflet, Esri Satellite Imagery
• APIs: OpenWeatherMap

Quick Start

Prerequisites

• Docker and Docker Compose
• Traefik reverse proxy running with proxy network
• DNS pointing turftracker.kaspers.us to your server (or your chosen domain)
• Git

Traefik Configuration Notes

This application is pre-configured for deployment behind Traefik with:

• Networks: proxy (external) for Traefik, turftracker (internal) for service communication
• SSL/TLS: Automatic Let's Encrypt certificates via Traefik
• Security: Database isolated from public network
• Routing: Frontend serves on root, API on /api path

Installation

1. Clone the repository

   git clone <repository-url>
   cd turftracking
   

2. Environment Configuration

   Copy the example environment file and configure it:

   cp .env.example .env
   

   Required Configuration - Edit the .env file:

   # Database - Use separate fields OR full DATABASE_URL
   DB_HOST=db
   DB_PORT=5432
   DB_NAME=turftracker
   DB_USER=turftracker
   DB_PASSWORD=password123
   
   # Authentication - GENERATE A SECURE JWT SECRET
   JWT_SECRET=your-generated-jwt-secret-here
   
   # Weather API (get free key from OpenWeatherMap)
   WEATHER_API_KEY=your-openweathermap-api-key
   
   # Authentik OAuth2 (optional - for SSO)
   AUTHENTIK_CLIENT_ID=your-authentik-client-id
   AUTHENTIK_CLIENT_SECRET=your-authentik-client-secret
   AUTHENTIK_BASE_URL=https://your-authentik-domain.com
   AUTHENTIK_CALLBACK_URL=http://localhost:5000/api/auth/authentik/callback
   
   # App URLs
   FRONTEND_URL=http://localhost:3000
   

3. Start the application

   docker-compose up -d
   

4. Access the application

   • Application: https://turftracker.kaspers.us
   • API: https://turftracker.kaspers.us/api
   • Database: Internal network only (not exposed)

First Time Setup

1. Create an admin account

   • Go to https://turftracker.kaspers.us/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

Environment Configuration Guide

JWT Secret Generation

The JWT secret is used to sign authentication tokens and MUST be secure in production.

Generate a secure JWT secret:

# Option 1: Using OpenSSL (recommended)
openssl rand -base64 64

# Option 2: Using Node.js
node -e "console.log(require('crypto').randomBytes(64).toString('base64'))"

# Option 3: Using Python
python3 -c "import secrets; print(secrets.token_urlsafe(64))"

# Option 4: Online generator
# Visit: https://generate-secret.vercel.app/64

⚠️ Security Warning: Never use the default JWT secret in production! Always generate a unique, random secret for each environment.

Database Configuration

You can configure the database connection using either:

Option 1: Separate Fields (Recommended)

DB_HOST=db
DB_PORT=5432
DB_NAME=turftracker
DB_USER=turftracker
DB_PASSWORD=password123

Option 2: Connection URL

DATABASE_URL=postgresql://username:password@host:port/database

Note: If both are provided, DATABASE_URL takes precedence.

API Keys Setup

OpenWeatherMap API Key

1. Go to OpenWeatherMap
2. Sign up for a free account (allows 1,000 calls/day)
3. Navigate to "API keys" in your dashboard
4. Copy your API key
5. Add it to your .env file as WEATHER_API_KEY

Authentik OAuth2 Setup (Optional)

If you have an Authentik instance for SSO:

1. In Authentik Admin Panel:

   • Go to Applications → Providers
   • Create new "OAuth2/OpenID Provider"
   • Set Authorization grant type: authorization-code
   • Set Client type: confidential
   • Set Redirect URIs: https://turftracker.kaspers.us/api/auth/authentik/callback
   • Note the Client ID and Client Secret

2. In your .env file:

   AUTHENTIK_CLIENT_ID=your-client-id-from-authentik
   AUTHENTIK_CLIENT_SECRET=your-client-secret-from-authentik
   AUTHENTIK_BASE_URL=https://your-authentik-domain.com
   AUTHENTIK_CALLBACK_URL=https://turftracker.kaspers.us/api/auth/authentik/callback
   

3. In Authentik Applications:

   • Create new Application
   • Set Name: TurfTracking
   • Set Slug: turftracking
   • Set Provider: (select the provider created above)

Scopes Required: openid profile email

Application Structure

turftracking/
├── 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
└── docker-compose.yml      # Container orchestration with Traefik

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

• OpenStreetMap integration for property mapping and satellite imagery
• Authentik OAuth2 integration for SSO
• Interactive lawn section drawing and area calculation
• GPS speed monitoring with audio feedback
• Mobile application development
• Advanced reporting and analytics with PDF export
• 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