docs(cache): document HF Spaces cache resolution; bump SW VERSION to invalidate old assets

llm.txt

@@ -1,597 +1,604 @@
-# TreeTrack - Professional Field Research Platform - LLM Knowledge Base
-
-## PROJECT OVERVIEW
-TreeTrack is a comprehensive tree mapping and urban forestry management web application with Supabase cloud database, modular JavaScript architecture, and beautiful interactive mapping. Deployed on **Hugging Face Spaces** using **Docker**.
-
-### Current Status & Direct Access
-- **Live Application**: https://huggingface.co/spaces/RoyAalekh/TreeTrack
-- **Main Interface**: https://royaalekh-treetrack.hf.space/
-- **Interactive Map**: https://royaalekh-treetrack.hf.space/map
-- **API Documentation**: https://royaalekh-treetrack.hf.space/docs
-- **Health Check**: https://royaalekh-treetrack.hf.space/health
-- **Login Page**: https://royaalekh-treetrack.hf.space/login
-- **Repository**: https://huggingface.co/spaces/RoyAalekh/TreeTrack/tree/main
-
-### Key Information:
-- **Platform**: Hugging Face Spaces (Docker deployment)
-- **Database**: Supabase PostgreSQL with cloud storage
-- **Technology Stack**: FastAPI + Supabase + Modular JavaScript (ES6) + Interactive Maps
-- **Purpose**: Professional field research tool for tree documentation with 12 comprehensive data fields
-- **Architecture**: Modular design with 6 specialized JavaScript modules + beautiful tree-shaped map pins
-- **Version**: 3.0.0 (Latest: Supabase Edition with enhanced mapping)
-- **Authentication**: Multi-role system (admin, researcher, viewer)
-
-## CURRENT DATABASE ARCHITECTURE (SUPABASE)
-
-### Database Provider: Supabase
-- **Type**: PostgreSQL cloud database
-- **Storage**: Supabase Storage for file uploads
-- **Real-time**: Supabase real-time capabilities
-- **Authentication**: Supabase Auth integration
-- **URL**: Configured via environment variables
-
-### Key Database Files
-- **supabase_client.py**: Supabase client configuration and connection
-- **supabase_database.py**: Database operations and queries
-- **supabase_storage.py**: File storage operations
-- **master_tree_database.py**: Master tree species database with autocomplete
-- **auth.py**: Authentication logic and user management
-
-### Database Tables
-1. **trees**: Main tree records table with all 12 fields
-2. **users**: User authentication and permissions
-3. **file_uploads**: Tracking uploaded images/audio files
-4. **master_species**: Reference database of tree species for autocomplete
-
-## INTERACTIVE MAPPING SYSTEM
-
-### Current Map Features
-- **Technology**: Leaflet.js with custom styling
-- **Map Interface**: https://royaalekh-treetrack.hf.space/map
-- **Beautiful Tree Pins**: 
-  - Red tree-shaped pins for new locations (temporary)
-  - Green tree-shaped pins for existing trees (permanent)
-  - 3D layered design with drop shadows
-  - Multiple highlight layers for realistic appearance
-
-### Pin Design Specifications
-- **Temporary Pins**: 32x40 pixels, red base (#dc2626) with tree icon
-- **Tree Markers**: 36x44 pixels, green base (#16a34a) with detailed tree design
-- **User Location**: 24x32 pixels, blue pin (#3b82f6)
-- **Features**: SVG-based, scalable, professional appearance
-
-### Map Functionality
-- **Pin Dropping**: Click anywhere to drop location pin
-- **Location Transfer**: Selected coordinates auto-fill form
-- **Tree Popups**: Enhanced modal with proper close button and responsive design
-- **GPS Location**: Get current user location
-- **Tree Clustering**: Multiple trees in same area
-- **Fixed Issues**: Popup overflow, button positioning, close button functionality
-
-## AUTHENTICATION SYSTEM
-
-### User Roles & Permissions
-1. **Admin**: Full access (create, read, update, delete all)
-2. **System**: Full administrative access
-3. **Researcher**: Can add and edit own trees, view all
-4. **Viewer**: Read-only access to tree data
-
-### Authentication Features
-- **Multi-role System**: Role-based access control
-- **Session Management**: Secure token-based sessions
-- **Login UI**: Professional login interface at /login
-- **Permission Checking**: Per-operation permission validation
-
-### Default Authentication (configured in auth.py)
-- Admin user with full permissions
-- System user for automated operations
-- Role-based tree editing and deletion rights
-
-## DEPLOYMENT ARCHITECTURE
-
-### Hugging Face Spaces Configuration
-- **App Port**: 7860 (required by HF Spaces)
-- **SDK**: docker
-- **Command**: `uvicorn app:app --host 0.0.0.0 --port 7860`
-- **User Context**: Non-root user (uid 1000) for security
-- **Base Image**: python:3.11-slim
-
-### Docker Configuration
-```dockerfile
-FROM python:3.11-slim
-RUN useradd -m -u 1000 user
-USER user
-WORKDIR /app
-EXPOSE 7860
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
-```
-
-## MODULAR ARCHITECTURE (Version 3.0.0)
-
-### Current Implementation
-- **Architecture**: Fully modular design with 6 specialized JavaScript modules
-- **Benefits**: Better maintainability, testability, and performance
-- **Design**: Clean separation of concerns with dependency injection
-- **UI**: Professional emoji-free interface suitable for research
-
-### Modular Architecture
-
-#### Module Structure
-```
-static/js/
-├── modules/
-│   ├── auth-manager.js        - Authentication & permissions (95 lines)
-│   ├── api-client.js          - API communication (148 lines)
-│   ├── ui-manager.js          - User interface & messaging (192 lines)
-│   ├── form-manager.js        - Form handling & validation (285 lines)
-│   ├── autocomplete-manager.js - Smart suggestions (322 lines)
-│   └── media-manager.js       - File uploads & recording (268 lines)
-└── tree-track-app.js          - Main orchestrator (206 lines)
-```
-
-#### Module Dependencies
-```
-TreeTrackApp
-├── AuthManager (independent)
-├── ApiClient (depends on AuthManager)
-├── UIManager (depends on AuthManager)
-├── FormManager (depends on ApiClient, UIManager)
-├── AutoCompleteManager (depends on ApiClient, UIManager)
-└── MediaManager (depends on FormManager, UIManager)
-```
-
-#### Key Improvements
-- **Separation of Concerns**: Each module has single responsibility
-- **Dependency Injection**: Clean dependencies between modules
-- **ES6 Modules**: Modern import/export structure
-- **Event Delegation**: Replaced global functions with proper event handling
-- **Performance**: Debounced search, Promise.all(), DOM caching
-- **Error Handling**: Centralized error management
-- **Code Reuse**: Shared utilities across modules
-
-## TECHNOLOGY STACK
-
-### Backend
-- **Framework**: FastAPI 0.115.0+
-- **Server**: Uvicorn with standard extras  
-- **Database**: Supabase PostgreSQL (cloud-hosted)
-- **Storage**: Supabase Storage for file uploads
-- **Authentication**: Supabase Auth integration
-- **File Handling**: aiofiles for async file operations
-- **Validation**: Pydantic 2.10.0+ with custom validators
-- **Configuration**: pydantic-settings for environment-based config
-
-### Frontend (Refactored)
-- **JavaScript**: Modular ES6+ with 6 specialized modules
-- **Architecture**: Dependency injection pattern
-- **Performance**: Debounced search (300ms), parallel API calls
-- **CSS**: Custom responsive design with Inter font (emoji-free)
-- **PWA**: Service Worker for offline capabilities
-- **Maps**: Interactive mapping with marker clustering
-- **Media**: Camera integration and audio recording
-
-### Dependencies
-```
-fastapi>=0.115.0
-uvicorn[standard]>=0.32.0
-python-multipart>=0.0.12
-pydantic>=2.10.0
-pydantic-settings>=2.6.0
-pandas>=2.3.1
-aiofiles>=24.1.0
-GitPython>=3.1.40
-huggingface-hub>=0.19.0
-```
-
-## DATA MODEL - 12 COMPREHENSIVE FIELDS
-
-### Core Tree Data Structure
-1. **Geolocation** (Required)
-   - Latitude: REAL (-90 to 90)
-   - Longitude: REAL (-180 to 180)
-
-2. **Identification**
-   - Local Name (Assamese): TEXT (max 200 chars)
-   - Scientific Name: TEXT (max 200 chars)
-   - Common Name: TEXT (max 200 chars)
-   - Tree Reference Code: TEXT (max 20 chars, e.g., "C.A", "A-G1")
-
-3. **Physical Measurements**
-   - Height: REAL (meters, 0-200)
-   - Width/Girth: REAL (cm, 0-2000)
-
-4. **Ecological & Cultural Data**
-   - Utility: JSON array of selected utilities
-     - Valid options: "Religious", "Timber", "Biodiversity", "Hydrological benefit", "Faunal interaction", "Food", "Medicine", "Shelter", "Cultural"
-
-5. **Phenology Assessment**
-   - Stages: JSON array of current development stages
-     - Valid options: "New leaves", "Old leaves", "Open flowers", "Fruiting", "Ripe fruit", "Recent fruit drop", "Other"
-
-6. **Documentation**
-   - Photographs: JSON object with categories and file paths
-     - Categories: "Leaf", "Bark", "Fruit", "Seed", "Flower", "Full tree"
-   - Storytelling Text: TEXT (max 5000 chars)
-   - Storytelling Audio: File path to audio recording
-
-7. **Field Notes**
-   - Notes: TEXT (max 2000 chars) for additional observations
-
-### System Fields
-- ID: Auto-increment primary key
-- Timestamp: Auto-generated creation time
-- Created_by: Default 'system'
-- Updated_at: Auto-updated modification time
-
-## SECURITY ARCHITECTURE
-
-### Multi-Layer Security
-- **Input Validation**: Pydantic models with custom validators
-- **SQL Injection Prevention**: Parameterized queries only
-- **XSS Protection**: Content Security Policy headers
-- **CORS**: Configured for specific origins
-- **File Security**: Secure path validation, type checking
-- **Rate Limiting**: Configurable request limits
-- **Error Handling**: Comprehensive exception management
-
-### Production Security Settings
-- Secret key validation (min 32 chars)
-- Debug mode disabled
-- Secure headers (X-Frame-Options, X-Content-Type-Options, etc.)
-- Trusted host middleware available
-
-## CACHE MANAGEMENT SYSTEM
-
-### Current Issue: Aggressive Service Worker Caching
-The app uses a Service Worker (`sw.js`) for PWA capabilities and offline support, but this causes caching issues during development.
-
-### Service Worker Configuration
-- **Cache Name**: `treetrack-v{timestamp}` (dynamic versioning implemented)
-- **Cached Resources**: HTML, JS, CSS, external fonts/libraries
-- **Cache Strategy**: Cache-first for production, network-first for development
-- **Development Mode Detection**: `isDevelopment = self.location.hostname === 'localhost' || '127.0.0.1'`
-
-### Cache Busting Solutions Implemented
-
-#### 1. Dynamic Service Worker Versioning
-```javascript
-const VERSION = new Date().getTime(); // Dynamic versioning
-const CACHE_NAME = `treetrack-v${VERSION}`;
-```
-
-#### 2. Development Mode Cache Bypass
-```javascript
-if (isDevelopment && event.request.url.includes('/static/')) {
-    event.respondWith(
-        fetch(event.request, { cache: 'no-cache' })
-    );
-}
-```
-
-#### 3. Version Management API
-- **GET /api/version**: Returns current version info
-- **POST /api/version/update**: Forces version update and cache clear
-
-#### 4. HTML Cache Busting
-```html
-<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
-<meta http-equiv="Pragma" content="no-cache">
-<meta http-equiv="Expires" content="0">
-<script src="/static/app.js?v=3.{timestamp}&t={timestamp}">
-```
-
-#### 5. FastAPI Middleware
-```python
-@app.middleware("http")
-async def add_cache_headers(request: Request, call_next):
-    if request.url.path.startswith("/static/"):
-        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
-```
-
-## FILE STRUCTURE (Current)
-
-```
-TreeTrack/
-├── README.md                 # HF Spaces config + documentation
-├── Dockerfile               # HF Spaces Docker configuration
-├── requirements.txt         # Python dependencies
-├── llm.txt                  # LLM knowledge base (this file)
-├── app.py                  # Main FastAPI application
-├── config.py               # Comprehensive configuration system
-├── constants.py            # Application constants
-├── auth.py                 # Authentication system
-├── supabase_client.py      # Supabase connection client
-├── supabase_database.py    # Database operations
-├── supabase_storage.py     # File storage operations
-├── master_tree_database.py # Tree species autocomplete
-├── .env.example            # Environment variables template
-├── .gitattributes          # Git configuration
-├── .gitignore              # Git ignore patterns
-├── data/
-│   └── master_trees.db     # Local SQLite for tree species
-└── static/
-    ├── css/
-    │   └── design-system.css # Professional design system
-    ├── index.html          # Main application interface
-    ├── login.html          # Login page
-    ├── map.html            # Interactive map interface
-    ├── map.js              # Map functionality
-    ├── sw.js               # Service Worker for PWA
-    └── js/
-        ├── modules/
-        │   ├── auth-manager.js        # Authentication module
-        │   ├── api-client.js          # API communication module
-        │   ├── ui-manager.js          # UI management module
-        │   ├── form-manager.js        # Form handling module
-        │   ├── autocomplete-manager.js # Smart suggestions module
-        │   └── media-manager.js       # Media handling module
-        └── tree-track-app.js          # Main orchestrator
-```
-
-## API ENDPOINTS
-
-### Core Tree Management
-- `GET /api/trees` - List trees with filtering/pagination
-- `POST /api/trees` - Create new tree record
-- `GET /api/trees/{id}` - Get specific tree
-- `PUT /api/trees/{id}` - Update tree record
-- `DELETE /api/trees/{id}` - Delete tree record
-
-### File Upload
-- `POST /api/upload/image` - Upload categorized photos
-- `POST /api/upload/audio` - Upload storytelling audio
-- `GET /api/files/{type}/{filename}` - Serve uploaded files
-
-### Form Data Helpers
-- `GET /api/utilities` - Valid utility options
-- `GET /api/phenology-stages` - Valid phenology stages  
-- `GET /api/photo-categories` - Valid photo categories
-
-### System Management
-- `GET /health` - Health check
-- `GET /api/stats` - Comprehensive statistics
-- `GET /api/version` - Current version info
-- `POST /api/version/update` - Force cache clear
-- `GET /api/persistence/status` - Database backup status
-- `POST /api/persistence/backup` - Force database backup
-
-### Frontend Routes
-- `GET /` - Main application (index.html)
-- `GET /map` - Interactive map interface
-- `GET /docs` - FastAPI auto-generated API documentation
-
-## CONFIGURATION SYSTEM
-
-### Environment-Based Settings (config.py)
-- **DatabaseConfig**: SQLite settings, backup configuration
-- **SecurityConfig**: Authentication, CORS, CSP, rate limiting
-- **ServerConfig**: Host, port, workers, timeout settings
-- **LoggingConfig**: File logging, rotation, access logs
-- **CacheConfig**: TTL settings, cache sizes
-- **MonitoringConfig**: Metrics, health checks, alerting
-- **ApplicationConfig**: Feature flags, validation rules
-
-### Configuration Hierarchy
-1. Environment variables
-2. `.env` file
-3. Default values in config classes
-
-## COMMON ISSUES & SOLUTIONS
-
-### Cache Issues (PRIMARY ISSUE)
-**Problem**: Service Worker aggressively caches static files
-**Solutions**:
-1. Run `python clear_cache.py` to update all version files
-2. Manually clear Service Worker in DevTools > Application > Service Workers
-3. Use `Ctrl+Shift+R` for hard refresh
-4. Open in incognito/private mode for testing
-5. Use version API endpoints to force cache updates
-
-### Deployment to HF Spaces
-**Remember**: This app runs on Hugging Face Spaces, not localhost
-- Port must be 7860
-- Use Docker deployment
-- Non-root user for security
-- Static files served through FastAPI
-
-### Development vs Production
-- Development: Cache bypassing enabled
-- Production: Full caching for performance
-- Environment detection via hostname
-
-## CACHE BUSTING WORKFLOW
-
-### For Hugging Face Spaces Deployment (PRIMARY)
-```bash
-# Run HF Spaces optimized cache manager
-python hf_cache_manager.py
-```
-
-### For Local Development
-```bash
-# Run comprehensive cache buster
-python clear_cache.py
-
-# Or use batch file on Windows
-clear_cache.bat
-```
-
-### Manual Steps
-1. Update service worker version: `const VERSION = {timestamp}`
-2. Update HTML cache busting parameters
-3. Update version.json file
-4. Clear browser service worker
-5. Hard refresh browser
-6. Test in incognito mode
-
-### API-Based Solution
-```bash
-# Update version via API (when server running)
-curl -X POST http://localhost:7860/api/version/update
-
-# Check current version
-curl http://localhost:7860/api/version
-```
-
-## DEVELOPMENT GUIDELINES
-
-### Adding New Features
-1. Update Pydantic models in app.py
-2. Add API endpoints with proper validation
-3. Update frontend JavaScript
-4. Add appropriate tests
-5. Update cache version if static files change
-
-### Database Schema Changes
-- Use SQLite migrations carefully
-- Backup database before schema changes
-- Update Pydantic models to match
-- Test with existing data
-
-### Security Considerations
-- Always validate input with Pydantic
-- Use parameterized queries
-- Implement rate limiting for public endpoints
-- Regular security header updates
-- Monitor for suspicious activity
-
-## CACHE VERSION HISTORY
-- v3.0: Initial version with basic cache busting
-- v3.{timestamp}: Dynamic versioning system
-- Current: Automated cache management with API endpoints
-
-## TROUBLESHOOTING CHECKLIST
-
-### UI Not Updating
-1.  Check if service worker is registered (DevTools > Application)
-2.  Unregister service worker if present
-3.  Hard refresh browser (Ctrl+Shift+R)
-4.  Check Network tab for 304 (cached) responses
-5.  Try incognito/private mode
-6.  Run cache buster script
-7.  Verify version.json timestamp is recent
-
-### Deployment Issues
-1.  Verify Dockerfile uses port 7860
-2.  Check requirements.txt is complete
-3.  Ensure non-root user setup
-4.  Verify static files are copied correctly
-5.  Check HF Spaces logs for errors
-
-## CURRENT STATUS ENDPOINTS & DATA ACCESS
-
-### System Status URLs
-- **Health Check**: https://royaalekh-treetrack.hf.space/health
-- **API Stats**: https://royaalekh-treetrack.hf.space/api/stats  
-- **Version Info**: https://royaalekh-treetrack.hf.space/api/version
-- **Tree Data**: https://royaalekh-treetrack.hf.space/api/trees
-
-### Interactive API Documentation
-- **Swagger UI**: https://royaalekh-treetrack.hf.space/docs
-- **ReDoc**: https://royaalekh-treetrack.hf.space/redoc
-
-## RECENT MAJOR UPDATES (Latest Commits)
-
-### Repository Cleanup (Latest)
-- Removed development documentation files
-- Cleaned up repository structure
-- Preserved all core functionality
-- Maintained Supabase integration files
-
-### Enhanced Map Pins (Recent)
-- Beautiful tree-shaped SVG pins with 3D design
-- Fixed popup modal overflow and layout issues
-- Improved responsive design for mobile
-- Enhanced close button functionality
-- Better coordinate transfer from map to form
-
-### Modular Architecture (Version 3.0.0)
-- Complete modular design with 6 specialized modules
-- Professional emoji-free interface
-- Enhanced button design with improved UX
-- Better performance and maintainability
-
-## FILE LOCATIONS FOR SPECIFIC FUNCTIONALITY
-
-### Authentication & Users
-- **Backend**: `auth.py` (user management and permissions)
-- **Frontend**: `static/js/modules/auth-manager.js`
-- **Login Page**: `static/login.html`
-
-### Database Operations
-- **Main Database**: `supabase_database.py` (all CRUD operations)
-- **Supabase Client**: `supabase_client.py` (connection and config)
-- **Storage**: `supabase_storage.py` (file uploads)
-- **Species Data**: `master_tree_database.py` (autocomplete)
-
-### Interactive Mapping
-- **Map Logic**: `static/map.js` (all mapping functionality)
-- **Map Interface**: `static/map.html` (map page UI)
-- **Pin Design**: Look for SVG definitions in map.js
-- **Popup Modals**: Enhanced popup content in map.js
-
-### Form Handling
-- **Main Form**: `static/index.html` (12-field tree form)
-- **Form Logic**: `static/js/modules/form-manager.js`
-- **Validation**: Both client-side and server-side in app.py
-- **Autocomplete**: `static/js/modules/autocomplete-manager.js`
-
-### File Uploads & Media
-- **Media Handling**: `static/js/modules/media-manager.js`
-- **Camera Integration**: Photo capture functionality
-- **Audio Recording**: Voice memo functionality
-- **File Processing**: Server-side in app.py upload endpoints
-
-### User Interface
-- **UI Updates**: `static/js/modules/ui-manager.js`
-- **Messages**: Success/error message system
-- **Tree List**: Dynamic tree list rendering
-- **Loading States**: Progress indicators and feedback
-
-## USAGE INSTRUCTIONS FOR LLMs
-
-### To Understand Project Structure:
-1. **Main Application Logic**: Review app.py for API endpoints and business logic
-2. **Frontend Architecture**: Check static/js/modules/ for modular components
-3. **Database Schema**: Look at Pydantic models in app.py and Supabase operations
-4. **Authentication Flow**: Review auth.py and auth-manager.js
-5. **Mapping Features**: Examine map.js for interactive map functionality
-
-### To Debug Specific Issues:
-1. **API Problems**: Test endpoints via /docs interface
-2. **Database Issues**: Check supabase_database.py operations
-3. **UI Problems**: Review browser console and specific module files
-4. **Authentication**: Check auth.py user configuration
-5. **Map Problems**: Look at map.js event handlers and pin creation
-
-### To Add New Features:
-1. **Backend**: Extend app.py with new FastAPI routes
-2. **Database**: Add operations to supabase_database.py
-3. **Frontend**: Extend appropriate JavaScript module
-4. **UI Changes**: Modify HTML files in static/
-5. **New Pages**: Add route in app.py and HTML file in static/
-
-### To Modify Existing Features:
-1. **Tree Data Model**: Update Pydantic models in app.py
-2. **Form Fields**: Modify index.html and form-manager.js
-3. **Map Functionality**: Update map.js and map.html
-4. **Authentication**: Modify auth.py and auth-manager.js
-5. **File Handling**: Update media-manager.js and storage operations
-
-## DEPLOYMENT STATUS & MONITORING
-
-### Current Deployment Status
-- **Status**: LIVE and OPERATIONAL
-- **Platform**: Hugging Face Spaces Docker
-- **Build Status**: Automatic deployment from main branch
-- **Health Monitoring**: Real-time via /health endpoint
-- **Performance**: Monitored via Supabase dashboard
-
-### Key Metrics to Monitor
-- **Response Time**: API endpoint performance
-- **Database Load**: Supabase connection usage
-- **Storage Usage**: File upload storage consumption  
-- **User Activity**: Authentication and session metrics
-- **Error Rates**: Application error frequency
-
-This comprehensive knowledge base reflects the current state of TreeTrack as of the latest updates and serves as the definitive guide for understanding the project's architecture, implementation, and operational status.
+# TreeTrack - Professional Field Research Platform - LLM Knowledge Base
+
+## PROJECT OVERVIEW
+TreeTrack is a comprehensive tree mapping and urban forestry management web application with Supabase cloud database, modular JavaScript architecture, and beautiful interactive mapping. Deployed on **Hugging Face Spaces** using **Docker**.
+
+### Current Status & Direct Access
+- **Live Application**: https://huggingface.co/spaces/RoyAalekh/TreeTrack
+- **Main Interface**: https://royaalekh-treetrack.hf.space/
+- **Interactive Map**: https://royaalekh-treetrack.hf.space/map
+- **API Documentation**: https://royaalekh-treetrack.hf.space/docs
+- **Health Check**: https://royaalekh-treetrack.hf.space/health
+- **Login Page**: https://royaalekh-treetrack.hf.space/login
+- **Repository**: https://huggingface.co/spaces/RoyAalekh/TreeTrack/tree/main
+
+### Key Information:
+- **Platform**: Hugging Face Spaces (Docker deployment)
+- **Database**: Supabase PostgreSQL with cloud storage
+- **Technology Stack**: FastAPI + Supabase + Modular JavaScript (ES6) + Interactive Maps
+- **Purpose**: Professional field research tool for tree documentation with 12 comprehensive data fields
+- **Architecture**: Modular design with 6 specialized JavaScript modules + beautiful tree-shaped map pins
+- **Version**: 3.0.0 (Latest: Supabase Edition with enhanced mapping)
+- **Authentication**: Multi-role system (admin, researcher, viewer)
+
+## CURRENT DATABASE ARCHITECTURE (SUPABASE)
+
+### Database Provider: Supabase
+- **Type**: PostgreSQL cloud database
+- **Storage**: Supabase Storage for file uploads
+- **Real-time**: Supabase real-time capabilities
+- **Authentication**: Supabase Auth integration
+- **URL**: Configured via environment variables
+
+### Key Database Files
+- **supabase_client.py**: Supabase client configuration and connection
+- **supabase_database.py**: Database operations and queries
+- **supabase_storage.py**: File storage operations
+- **master_tree_database.py**: Master tree species database with autocomplete
+- **auth.py**: Authentication logic and user management
+
+### Database Tables
+1. **trees**: Main tree records table with all 12 fields
+2. **users**: User authentication and permissions
+3. **file_uploads**: Tracking uploaded images/audio files
+4. **master_species**: Reference database of tree species for autocomplete
+
+## INTERACTIVE MAPPING SYSTEM
+
+### Current Map Features
+- **Technology**: Leaflet.js with custom styling
+- **Map Interface**: https://royaalekh-treetrack.hf.space/map
+- **Beautiful Tree Pins**: 
+  - Red tree-shaped pins for new locations (temporary)
+  - Green tree-shaped pins for existing trees (permanent)
+  - 3D layered design with drop shadows
+  - Multiple highlight layers for realistic appearance
+
+### Pin Design Specifications
+- **Temporary Pins**: 32x40 pixels, red base (#dc2626) with tree icon
+- **Tree Markers**: 36x44 pixels, green base (#16a34a) with detailed tree design
+- **User Location**: 24x32 pixels, blue pin (#3b82f6)
+- **Features**: SVG-based, scalable, professional appearance
+
+### Map Functionality
+- **Pin Dropping**: Click anywhere to drop location pin
+- **Location Transfer**: Selected coordinates auto-fill form
+- **Tree Popups**: Enhanced modal with proper close button and responsive design
+- **GPS Location**: Get current user location
+- **Tree Clustering**: Multiple trees in same area
+- **Fixed Issues**: Popup overflow, button positioning, close button functionality
+
+## AUTHENTICATION SYSTEM
+
+### User Roles & Permissions
+1. **Admin**: Full access (create, read, update, delete all)
+2. **System**: Full administrative access
+3. **Researcher**: Can add and edit own trees, view all
+4. **Viewer**: Read-only access to tree data
+
+### Authentication Features
+- **Multi-role System**: Role-based access control
+- **Session Management**: Secure token-based sessions
+- **Login UI**: Professional login interface at /login
+- **Permission Checking**: Per-operation permission validation
+
+### Default Authentication (configured in auth.py)
+- Admin user with full permissions
+- System user for automated operations
+- Role-based tree editing and deletion rights
+
+## DEPLOYMENT ARCHITECTURE
+
+### Hugging Face Spaces Configuration
+- **App Port**: 7860 (required by HF Spaces)
+- **SDK**: docker
+- **Command**: `uvicorn app:app --host 0.0.0.0 --port 7860`
+- **User Context**: Non-root user (uid 1000) for security
+- **Base Image**: python:3.11-slim
+
+### Docker Configuration
+```dockerfile
+FROM python:3.11-slim
+RUN useradd -m -u 1000 user
+USER user
+WORKDIR /app
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+```
+
+## MODULAR ARCHITECTURE (Version 3.0.0)
+
+### Current Implementation
+- **Architecture**: Fully modular design with 6 specialized JavaScript modules
+- **Benefits**: Better maintainability, testability, and performance
+- **Design**: Clean separation of concerns with dependency injection
+- **UI**: Professional emoji-free interface suitable for research
+
+### Modular Architecture
+
+#### Module Structure
+```
+static/js/
+├── modules/
+│   ├── auth-manager.js        - Authentication & permissions (95 lines)
+│   ├── api-client.js          - API communication (148 lines)
+│   ├── ui-manager.js          - User interface & messaging (192 lines)
+│   ├── form-manager.js        - Form handling & validation (285 lines)
+│   ├── autocomplete-manager.js - Smart suggestions (322 lines)
+│   └── media-manager.js       - File uploads & recording (268 lines)
+└── tree-track-app.js          - Main orchestrator (206 lines)
+```
+
+#### Module Dependencies
+```
+TreeTrackApp
+├── AuthManager (independent)
+├── ApiClient (depends on AuthManager)
+├── UIManager (depends on AuthManager)
+├── FormManager (depends on ApiClient, UIManager)
+├── AutoCompleteManager (depends on ApiClient, UIManager)
+└── MediaManager (depends on FormManager, UIManager)
+```
+
+#### Key Improvements
+- **Separation of Concerns**: Each module has single responsibility
+- **Dependency Injection**: Clean dependencies between modules
+- **ES6 Modules**: Modern import/export structure
+- **Event Delegation**: Replaced global functions with proper event handling
+- **Performance**: Debounced search, Promise.all(), DOM caching
+- **Error Handling**: Centralized error management
+- **Code Reuse**: Shared utilities across modules
+
+## TECHNOLOGY STACK
+
+### Backend
+- **Framework**: FastAPI 0.115.0+
+- **Server**: Uvicorn with standard extras  
+- **Database**: Supabase PostgreSQL (cloud-hosted)
+- **Storage**: Supabase Storage for file uploads
+- **Authentication**: Supabase Auth integration
+- **File Handling**: aiofiles for async file operations
+- **Validation**: Pydantic 2.10.0+ with custom validators
+- **Configuration**: pydantic-settings for environment-based config
+
+### Frontend (Refactored)
+- **JavaScript**: Modular ES6+ with 6 specialized modules
+- **Architecture**: Dependency injection pattern
+- **Performance**: Debounced search (300ms), parallel API calls
+- **CSS**: Custom responsive design with Inter font (emoji-free)
+- **PWA**: Service Worker for offline capabilities
+- **Maps**: Interactive mapping with marker clustering
+- **Media**: Camera integration and audio recording
+
+### Dependencies
+```
+fastapi>=0.115.0
+uvicorn[standard]>=0.32.0
+python-multipart>=0.0.12
+pydantic>=2.10.0
+pydantic-settings>=2.6.0
+pandas>=2.3.1
+aiofiles>=24.1.0
+GitPython>=3.1.40
+huggingface-hub>=0.19.0
+```
+
+## DATA MODEL - 12 COMPREHENSIVE FIELDS
+
+### Core Tree Data Structure
+1. **Geolocation** (Required)
+   - Latitude: REAL (-90 to 90)
+   - Longitude: REAL (-180 to 180)
+
+2. **Identification**
+   - Local Name (Assamese): TEXT (max 200 chars)
+   - Scientific Name: TEXT (max 200 chars)
+   - Common Name: TEXT (max 200 chars)
+   - Tree Reference Code: TEXT (max 20 chars, e.g., "C.A", "A-G1")
+
+3. **Physical Measurements**
+   - Height: REAL (meters, 0-200)
+   - Width/Girth: REAL (cm, 0-2000)
+
+4. **Ecological & Cultural Data**
+   - Utility: JSON array of selected utilities
+     - Valid options: "Religious", "Timber", "Biodiversity", "Hydrological benefit", "Faunal interaction", "Food", "Medicine", "Shelter", "Cultural"
+
+5. **Phenology Assessment**
+   - Stages: JSON array of current development stages
+     - Valid options: "New leaves", "Old leaves", "Open flowers", "Fruiting", "Ripe fruit", "Recent fruit drop", "Other"
+
+6. **Documentation**
+   - Photographs: JSON object with categories and file paths
+     - Categories: "Leaf", "Bark", "Fruit", "Seed", "Flower", "Full tree"
+   - Storytelling Text: TEXT (max 5000 chars)
+   - Storytelling Audio: File path to audio recording
+
+7. **Field Notes**
+   - Notes: TEXT (max 2000 chars) for additional observations
+
+### System Fields
+- ID: Auto-increment primary key
+- Timestamp: Auto-generated creation time
+- Created_by: Default 'system'
+- Updated_at: Auto-updated modification time
+
+## SECURITY ARCHITECTURE
+
+### Multi-Layer Security
+- **Input Validation**: Pydantic models with custom validators
+- **SQL Injection Prevention**: Parameterized queries only
+- **XSS Protection**: Content Security Policy headers
+- **CORS**: Configured for specific origins
+- **File Security**: Secure path validation, type checking
+- **Rate Limiting**: Configurable request limits
+- **Error Handling**: Comprehensive exception management
+
+### Production Security Settings
+- Secret key validation (min 32 chars)
+- Debug mode disabled
+- Secure headers (X-Frame-Options, X-Content-Type-Options, etc.)
+- Trusted host middleware available
+
+## CACHE MANAGEMENT SYSTEM
+
+Deployment cache resolution (HF Spaces):
+- Always bump the SW VERSION constant in static/sw.js after any frontend changes. This forces a new cache (treetrack-v{VERSION}) and invalidates old assets.
+- Bump script query params if present (e.g., /static/js/tree-track-app.js?v=...).
+- Dev/Spaces mode bypass: SW bypasses caching for /static/ when hostname includes localhost, 127.0.0.1, or hf.space.
+- Manual steps: Unregister SW in DevTools 3e Application 3e Service Workers, then hard reload. For persistent issues, try incognito.
+- API references: GET /api/version to view build; optional POST /api/version/update can be implemented for remote SW update signaling.
+
+### Current Issue: Aggressive Service Worker Caching
+The app uses a Service Worker (`sw.js`) for PWA capabilities and offline support, but this causes caching issues during development.
+
+### Service Worker Configuration
+- **Cache Name**: `treetrack-v{timestamp}` (dynamic versioning implemented)
+- **Cached Resources**: HTML, JS, CSS, external fonts/libraries
+- **Cache Strategy**: Cache-first for production, network-first for development
+- **Development Mode Detection**: `isDevelopment = self.location.hostname === 'localhost' || '127.0.0.1'`
+
+### Cache Busting Solutions Implemented
+
+#### 1. Dynamic Service Worker Versioning
+```javascript
+const VERSION = new Date().getTime(); // Dynamic versioning
+const CACHE_NAME = `treetrack-v${VERSION}`;
+```
+
+#### 2. Development Mode Cache Bypass
+```javascript
+if (isDevelopment && event.request.url.includes('/static/')) {
+    event.respondWith(
+        fetch(event.request, { cache: 'no-cache' })
+    );
+}
+```
+
+#### 3. Version Management API
+- **GET /api/version**: Returns current version info
+- **POST /api/version/update**: Forces version update and cache clear
+
+#### 4. HTML Cache Busting
+```html
+<meta http-equiv="Cache-Control" content="no-cache, no-store, must-revalidate">
+<meta http-equiv="Pragma" content="no-cache">
+<meta http-equiv="Expires" content="0">
+<script src="/static/app.js?v=3.{timestamp}&t={timestamp}">
+```
+
+#### 5. FastAPI Middleware
+```python
+@app.middleware("http")
+async def add_cache_headers(request: Request, call_next):
+    if request.url.path.startswith("/static/"):
+        response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
+```
+
+## FILE STRUCTURE (Current)
+
+```
+TreeTrack/
+├── README.md                 # HF Spaces config + documentation
+├── Dockerfile               # HF Spaces Docker configuration
+├── requirements.txt         # Python dependencies
+├── llm.txt                  # LLM knowledge base (this file)
+├── app.py                  # Main FastAPI application
+├── config.py               # Comprehensive configuration system
+├── constants.py            # Application constants
+├── auth.py                 # Authentication system
+├── supabase_client.py      # Supabase connection client
+├── supabase_database.py    # Database operations
+├── supabase_storage.py     # File storage operations
+├── master_tree_database.py # Tree species autocomplete
+├── .env.example            # Environment variables template
+├── .gitattributes          # Git configuration
+├── .gitignore              # Git ignore patterns
+├── data/
+│   └── master_trees.db     # Local SQLite for tree species
+└── static/
+    ├── css/
+    │   └── design-system.css # Professional design system
+    ├── index.html          # Main application interface
+    ├── login.html          # Login page
+    ├── map.html            # Interactive map interface
+    ├── map.js              # Map functionality
+    ├── sw.js               # Service Worker for PWA
+    └── js/
+        ├── modules/
+        │   ├── auth-manager.js        # Authentication module
+        │   ├── api-client.js          # API communication module
+        │   ├── ui-manager.js          # UI management module
+        │   ├── form-manager.js        # Form handling module
+        │   ├── autocomplete-manager.js # Smart suggestions module
+        │   └── media-manager.js       # Media handling module
+        └── tree-track-app.js          # Main orchestrator
+```
+
+## API ENDPOINTS
+
+### Core Tree Management
+- `GET /api/trees` - List trees with filtering/pagination
+- `POST /api/trees` - Create new tree record
+- `GET /api/trees/{id}` - Get specific tree
+- `PUT /api/trees/{id}` - Update tree record
+- `DELETE /api/trees/{id}` - Delete tree record
+
+### File Upload
+- `POST /api/upload/image` - Upload categorized photos
+- `POST /api/upload/audio` - Upload storytelling audio
+- `GET /api/files/{type}/{filename}` - Serve uploaded files
+
+### Form Data Helpers
+- `GET /api/utilities` - Valid utility options
+- `GET /api/phenology-stages` - Valid phenology stages  
+- `GET /api/photo-categories` - Valid photo categories
+
+### System Management
+- `GET /health` - Health check
+- `GET /api/stats` - Comprehensive statistics
+- `GET /api/version` - Current version info
+- `POST /api/version/update` - Force cache clear
+- `GET /api/persistence/status` - Database backup status
+- `POST /api/persistence/backup` - Force database backup
+
+### Frontend Routes
+- `GET /` - Main application (index.html)
+- `GET /map` - Interactive map interface
+- `GET /docs` - FastAPI auto-generated API documentation
+
+## CONFIGURATION SYSTEM
+
+### Environment-Based Settings (config.py)
+- **DatabaseConfig**: SQLite settings, backup configuration
+- **SecurityConfig**: Authentication, CORS, CSP, rate limiting
+- **ServerConfig**: Host, port, workers, timeout settings
+- **LoggingConfig**: File logging, rotation, access logs
+- **CacheConfig**: TTL settings, cache sizes
+- **MonitoringConfig**: Metrics, health checks, alerting
+- **ApplicationConfig**: Feature flags, validation rules
+
+### Configuration Hierarchy
+1. Environment variables
+2. `.env` file
+3. Default values in config classes
+
+## COMMON ISSUES & SOLUTIONS
+
+### Cache Issues (PRIMARY ISSUE)
+**Problem**: Service Worker aggressively caches static files
+**Solutions**:
+1. Run `python clear_cache.py` to update all version files
+2. Manually clear Service Worker in DevTools > Application > Service Workers
+3. Use `Ctrl+Shift+R` for hard refresh
+4. Open in incognito/private mode for testing
+5. Use version API endpoints to force cache updates
+
+### Deployment to HF Spaces
+**Remember**: This app runs on Hugging Face Spaces, not localhost
+- Port must be 7860
+- Use Docker deployment
+- Non-root user for security
+- Static files served through FastAPI
+
+### Development vs Production
+- Development: Cache bypassing enabled
+- Production: Full caching for performance
+- Environment detection via hostname
+
+## CACHE BUSTING WORKFLOW
+
+### For Hugging Face Spaces Deployment (PRIMARY)
+```bash
+# Run HF Spaces optimized cache manager
+python hf_cache_manager.py
+```
+
+### For Local Development
+```bash
+# Run comprehensive cache buster
+python clear_cache.py
+
+# Or use batch file on Windows
+clear_cache.bat
+```
+
+### Manual Steps
+1. Update service worker version: `const VERSION = {timestamp}`
+2. Update HTML cache busting parameters
+3. Update version.json file
+4. Clear browser service worker
+5. Hard refresh browser
+6. Test in incognito mode
+
+### API-Based Solution
+```bash
+# Update version via API (when server running)
+curl -X POST http://localhost:7860/api/version/update
+
+# Check current version
+curl http://localhost:7860/api/version
+```
+
+## DEVELOPMENT GUIDELINES
+
+### Adding New Features
+1. Update Pydantic models in app.py
+2. Add API endpoints with proper validation
+3. Update frontend JavaScript
+4. Add appropriate tests
+5. Update cache version if static files change
+
+### Database Schema Changes
+- Use SQLite migrations carefully
+- Backup database before schema changes
+- Update Pydantic models to match
+- Test with existing data
+
+### Security Considerations
+- Always validate input with Pydantic
+- Use parameterized queries
+- Implement rate limiting for public endpoints
+- Regular security header updates
+- Monitor for suspicious activity
+
+## CACHE VERSION HISTORY
+- v3.0: Initial version with basic cache busting
+- v3.{timestamp}: Dynamic versioning system
+- Current: Automated cache management with API endpoints
+
+## TROUBLESHOOTING CHECKLIST
+
+### UI Not Updating
+1.  Check if service worker is registered (DevTools > Application)
+2.  Unregister service worker if present
+3.  Hard refresh browser (Ctrl+Shift+R)
+4.  Check Network tab for 304 (cached) responses
+5.  Try incognito/private mode
+6.  Run cache buster script
+7.  Verify version.json timestamp is recent
+
+### Deployment Issues
+1.  Verify Dockerfile uses port 7860
+2.  Check requirements.txt is complete
+3.  Ensure non-root user setup
+4.  Verify static files are copied correctly
+5.  Check HF Spaces logs for errors
+
+## CURRENT STATUS ENDPOINTS & DATA ACCESS
+
+### System Status URLs
+- **Health Check**: https://royaalekh-treetrack.hf.space/health
+- **API Stats**: https://royaalekh-treetrack.hf.space/api/stats  
+- **Version Info**: https://royaalekh-treetrack.hf.space/api/version
+- **Tree Data**: https://royaalekh-treetrack.hf.space/api/trees
+
+### Interactive API Documentation
+- **Swagger UI**: https://royaalekh-treetrack.hf.space/docs
+- **ReDoc**: https://royaalekh-treetrack.hf.space/redoc
+
+## RECENT MAJOR UPDATES (Latest Commits)
+
+### Repository Cleanup (Latest)
+- Removed development documentation files
+- Cleaned up repository structure
+- Preserved all core functionality
+- Maintained Supabase integration files
+
+### Enhanced Map Pins (Recent)
+- Beautiful tree-shaped SVG pins with 3D design
+- Fixed popup modal overflow and layout issues
+- Improved responsive design for mobile
+- Enhanced close button functionality
+- Better coordinate transfer from map to form
+
+### Modular Architecture (Version 3.0.0)
+- Complete modular design with 6 specialized modules
+- Professional emoji-free interface
+- Enhanced button design with improved UX
+- Better performance and maintainability
+
+## FILE LOCATIONS FOR SPECIFIC FUNCTIONALITY
+
+### Authentication & Users
+- **Backend**: `auth.py` (user management and permissions)
+- **Frontend**: `static/js/modules/auth-manager.js`
+- **Login Page**: `static/login.html`
+
+### Database Operations
+- **Main Database**: `supabase_database.py` (all CRUD operations)
+- **Supabase Client**: `supabase_client.py` (connection and config)
+- **Storage**: `supabase_storage.py` (file uploads)
+- **Species Data**: `master_tree_database.py` (autocomplete)
+
+### Interactive Mapping
+- **Map Logic**: `static/map.js` (all mapping functionality)
+- **Map Interface**: `static/map.html` (map page UI)
+- **Pin Design**: Look for SVG definitions in map.js
+- **Popup Modals**: Enhanced popup content in map.js
+
+### Form Handling
+- **Main Form**: `static/index.html` (12-field tree form)
+- **Form Logic**: `static/js/modules/form-manager.js`
+- **Validation**: Both client-side and server-side in app.py
+- **Autocomplete**: `static/js/modules/autocomplete-manager.js`
+
+### File Uploads & Media
+- **Media Handling**: `static/js/modules/media-manager.js`
+- **Camera Integration**: Photo capture functionality
+- **Audio Recording**: Voice memo functionality
+- **File Processing**: Server-side in app.py upload endpoints
+
+### User Interface
+- **UI Updates**: `static/js/modules/ui-manager.js`
+- **Messages**: Success/error message system
+- **Tree List**: Dynamic tree list rendering
+- **Loading States**: Progress indicators and feedback
+
+## USAGE INSTRUCTIONS FOR LLMs
+
+### To Understand Project Structure:
+1. **Main Application Logic**: Review app.py for API endpoints and business logic
+2. **Frontend Architecture**: Check static/js/modules/ for modular components
+3. **Database Schema**: Look at Pydantic models in app.py and Supabase operations
+4. **Authentication Flow**: Review auth.py and auth-manager.js
+5. **Mapping Features**: Examine map.js for interactive map functionality
+
+### To Debug Specific Issues:
+1. **API Problems**: Test endpoints via /docs interface
+2. **Database Issues**: Check supabase_database.py operations
+3. **UI Problems**: Review browser console and specific module files
+4. **Authentication**: Check auth.py user configuration
+5. **Map Problems**: Look at map.js event handlers and pin creation
+
+### To Add New Features:
+1. **Backend**: Extend app.py with new FastAPI routes
+2. **Database**: Add operations to supabase_database.py
+3. **Frontend**: Extend appropriate JavaScript module
+4. **UI Changes**: Modify HTML files in static/
+5. **New Pages**: Add route in app.py and HTML file in static/
+
+### To Modify Existing Features:
+1. **Tree Data Model**: Update Pydantic models in app.py
+2. **Form Fields**: Modify index.html and form-manager.js
+3. **Map Functionality**: Update map.js and map.html
+4. **Authentication**: Modify auth.py and auth-manager.js
+5. **File Handling**: Update media-manager.js and storage operations
+
+## DEPLOYMENT STATUS & MONITORING
+
+### Current Deployment Status
+- **Status**: LIVE and OPERATIONAL
+- **Platform**: Hugging Face Spaces Docker
+- **Build Status**: Automatic deployment from main branch
+- **Health Monitoring**: Real-time via /health endpoint
+- **Performance**: Monitored via Supabase dashboard
+
+### Key Metrics to Monitor
+- **Response Time**: API endpoint performance
+- **Database Load**: Supabase connection usage
+- **Storage Usage**: File upload storage consumption  
+- **User Activity**: Authentication and session metrics
+- **Error Rates**: Application error frequency
+
+This comprehensive knowledge base reflects the current state of TreeTrack as of the latest updates and serves as the definitive guide for understanding the project's architecture, implementation, and operational status.

static/sw.js

@@ -1,5 +1,5 @@
 // TreeTrack Service Worker - PWA and Offline Support
-const VERSION = 1754659000; // Cache busting bump - force clients to fetch new static assets and header image change
+const VERSION = 1754662800; // Cache busting bump - force clients to fetch new static assets and header image change
 const CACHE_NAME = `treetrack-v${VERSION}`;
 const STATIC_CACHE = `static-v${VERSION}`;
 const API_CACHE = `api-v${VERSION}`;