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**
   ```bash
   git clone <repository-url>
   cd turftracking
   ```

2. **Environment Configuration**
   
   Copy the example environment file and configure it:
   ```bash
   cp .env.example .env
   ```
   
   **Required Configuration** - Edit the `.env` file:
   ```env
   # 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**
   ```bash
   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:**

```bash
# 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)**
```env
DB_HOST=db
DB_PORT=5432
DB_NAME=turftracker
DB_USER=turftracker
DB_PASSWORD=password123
```

**Option 2: Connection URL**
```env
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](https://openweathermap.org/api)
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:**
   ```env
   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**
   ```bash
   cd backend
   npm install
   npm run dev
   ```

2. **Frontend Development**
   ```bash
   cd frontend
   npm install
   npm start
   ```

3. **Database Setup**
   ```bash
   docker-compose up db -d
   ```

### Project Roadmap

- [x] OpenStreetMap integration for property mapping and satellite imagery
- [x] Authentik OAuth2 integration for SSO
- [x] 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