README.md

---
title: TreeTrack
colorFrom: green
colorTo: blue
sdk: docker
app_port: 7860
pinned: false
license: mit
short_description: Professional tree mapping and forestry management platform
---

# TreeTrack - Professional Field Research Platform

A **secure, robust, and high-performance** web application for mapping, tracking, and managing urban forest data using FastAPI with comprehensive security implementations and modern modular architecture.

## Current Version: 3.0.0 - Supabase Edition

### Key Features
- **Modular JavaScript Architecture**: Clean separation of concerns with 6 specialized modules
- **Supabase Cloud Integration**: PostgreSQL database with real-time capabilities
- **146 Pre-loaded Tree Species**: Comprehensive database from Tezpur research team
- **Smart Auto-completion**: Real-time species suggestions with debounced search
- **Multi-language Support**: Local Assamese names, scientific names, common names
- **Enhanced Button Design**: Professional UX with clear visual hierarchy
- **Interactive Mapping**: Beautiful tree-shaped pins with 3D design
- **Multi-role Authentication**: Admin, researcher, and viewer roles
- **Professional UI**: Emoji-free interface suitable for research environments

## Core Features

- **Interactive Tree Mapping**: Add, edit, and visualize trees on an interactive map
- **Intelligent Species Identification**: Auto-suggestions from master species database
- **Comprehensive Data Management**: Track species, health status, dimensions, and more
- **Advanced Security**: Input validation, SQL injection prevention, XSS protection
- **Performance Optimized**: Database indexing, caching, and efficient queries
- **RESTful API**: Full API documentation with FastAPI's automatic OpenAPI docs
- **Responsive Design**: Works on desktop and mobile devices

## Usage

1. **View Trees**: Browse the interactive map to see all registered trees
2. **Add New Trees**: Click on the map to add new tree entries with detailed information
3. **Edit Trees**: Update existing tree data including health status and measurements
4. **API Access**: Use the `/docs` endpoint for full API documentation
5. **Statistics**: View comprehensive statistics about your urban forest

## API Endpoints

### Core Tree Management
- `GET /` - Main application interface
- `GET /docs` - Interactive API documentation
- `GET /api/trees` - List all trees with filtering
- `POST /api/trees` - Add new tree
- `GET /api/trees/{id}` - Get specific tree details
- `PUT /api/trees/{id}` - Update tree information
- `DELETE /api/trees/{id}` - Remove tree
- `GET /api/stats` - Get forest statistics
- `GET /health` - Application health check

### Auto-Suggestion System
- `GET /api/tree-suggestions` - Get species suggestions based on query
- `GET /api/tree-codes` - Get all available tree reference codes
- `GET /api/master-database/status` - Master database health and statistics

### Data Management
- `GET /download/database` - Download SQLite database file
- `GET /download/csv` - Download CSV export of tree data
- `GET /download/status` - Download database status report

## Security Features

- Input validation and sanitization
- SQL injection prevention
- XSS protection with Content Security Policy
- CORS configuration
- Secure file path validation
- Comprehensive error handling

## Technical Stack

- **Backend**: FastAPI 3.0.0 (Python 3.11+)
- **Database**: Supabase PostgreSQL (cloud-hosted)
- **Storage**: Supabase Storage for file uploads
- **Frontend**: Modular JavaScript with ES6 modules
- **Architecture**: 6 specialized modules (Auth, API, UI, Form, AutoComplete, Media)
- **Mapping**: Interactive maps with custom tree-shaped pins
- **Validation**: Pydantic 2.10.0+ with custom validators
- **Security**: Multi-layer protection with role-based access
- **Performance**: Debounced search, Promise.all(), optimized DOM queries
- **Deployment**: Docker on Hugging Face Spaces

---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## Developer workflow notes

### Automatic cache busting on commit/push

This repo includes a small utility and Git hooks to ensure browsers always fetch the latest static assets:
- scripts/bump_cache.py updates service worker, HTML inline version/timestamp, and script tag query params.
- .githooks/pre-commit runs the bump (timestamp-only) and stages changed files.
- .githooks/pre-push runs a final bump and, if necessary, auto-commits the change before pushing.

Setup (one-time):
- git config core.hooksPath .githooks

Usage:
- Just commit and push normally. The hooks will bump the timestamp each time.
- To bump semantic version too: python scripts/bump_cache.py --bump patch (or minor/major). The hooks will stage the changes for your next commit.

Note for Windows developers:
- Git for Windows ships with a POSIX shell that executes hooks. Ensure Python is available on PATH.