README.md

metadata

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.