A bilingual (English/Spanish) web application documenting the magnificent trees of Costa Rica. Built with Next.js 16, TypeScript, and modern web technologies.
- Full English and Spanish support with locale-based routing
- 180 tree species with comprehensive bilingual profiles (360 documents)
- MDX content system for rich tree profiles with React components
- Interactive Lessons: Structured learning modules about Costa Rican trees and ecosystems
- Progress Tracking: Track completed lessons and earn points
- Printable Resources: Downloadable worksheets and field guides for classrooms
- Tree Identification Guide: Interactive key for identifying trees by leaf shape, bark, flowers, and more
- Quick Search: Global ⌘K keyboard shortcut for instant tree lookup
- Full-Text Search: Search across tree names, descriptions, and scientific names
- Category Filtering: Filter by botanical family, conservation status, or tags
- Seasonal Filtering: Find trees "flowering now" or "fruiting now" based on current month
- Alphabetical Index: Browse trees A-Z with sticky navigation
- Interactive Distribution Maps: Geographic maps showing where species are found
- External API Integration: Live data from GBIF and iNaturalist biodiversity databases
- Conservation Status: IUCN Red List display with visual scale and population trends
- Seasonal Calendar: Monthly flowering and fruiting calendar with tree activity view
- Now Blooming: Homepage section highlighting currently active trees
- Tree of the Day: Daily rotating featured tree
- Favorites System: Save and bookmark trees with localStorage persistence
- Recently Viewed: Track and display browsing history on homepage
- Share Favorites: Generate shareable URLs to share collections with friends
- Export Field Guide: Print favorites as a styled field guide PDF
- Quick Compare: Side-by-side comparison of tree characteristics
- Toxicity Warnings: Comprehensive safety data for dangerous species (severe, high, moderate, low, none)
- Visual Risk Indicators: Color-coded badges (🟢🔵🟡🟠🔴⛔) on tree cards and detail pages
- Detailed Hazard Info: Toxic parts, skin contact risks, allergen information, structural hazards
- Child & Pet Safety: Clear indicators for family-safe vs. hazardous trees
- First Aid Guidance: Emergency protocols and poison control contacts (Costa Rica: 2223-1028)
- Bilingual Warnings: Medically accurate safety information in English and Spanish
- Critical Species Documented: Javillo/Sandbox Tree (explosive pods, caustic sap), Madero Negro, and more
- Nature-Inspired Theme: Custom color palette with forest greens and earth tones
- Dark Mode: System preference detection with manual toggle
- Mobile-First Design: Responsive layout with full-screen mobile navigation
- WCAG 2.1 AA Compliant: Accessible to all users
- PWA Support: Offline access for field use
- Audio Pronunciation: Text-to-speech for scientific names
| Shortcut | Action |
|---|---|
? |
Show keyboard shortcuts help |
H |
Go to home |
T |
Go to trees directory |
F |
Go to favorites |
R |
Show random tree |
D |
Toggle dark/light theme |
⌘K / Ctrl+K |
Quick search |
API endpoints are protected with persistent rate limiting using Upstash Redis:
| Endpoint | Limit | Window |
|---|---|---|
/api/identify |
10 requests | 1 hour |
/api/species |
60 requests | 1 minute |
/api/species/images |
30 requests | 1 minute |
/api/species/random |
100 requests | 1 minute |
See Development Notes for development setup instructions.
For private/internal deployments, apply the hardening checklist in docs/PRIVATE_REPOSITORY_HARDENING.md.
- Community contributions: User-submitted sightings and photographs
- AR tree identification using device camera
- Partnership with Costa Rican conservation organizations
- Multi-language expansion (German, French for tourists)
Comprehensive documentation is available in the docs/ directory:
- Documentation Index - Complete guide to all documentation
- Development Notes - Setup notes for project owner/collaborators
- Content Standards - Tree profile standards
- Implementation Plan - Phased roadmap, lane status, and v1.0 definition of done
- AI Agent Instructions - Coding conventions and patterns
Contributions are welcome — see CONTRIBUTING.md for local setup, branch conventions, and the content acceptance criteria, and CODE_OF_CONDUCT.md for community expectations.
Content changes touching indigenous knowledge follow a separate review process; see docs/INDIGENOUS_KNOWLEDGE_GOVERNANCE.md.
The project includes automated weekly image quality monitoring that:
- Validates all tree images (featured + gallery)
- Automatically fixes broken or missing images
- Generates quality metrics and health reports
- Creates PRs for manual review before merging
See Image Quality Monitoring for details on our automated maintenance system.
The project uses Sharp for high-performance image optimization:
- Multiple Formats: WebP, AVIF, and JPEG for maximum compatibility
- Responsive Sizes: 400w, 800w, 1200w, 1600w variants for different devices
- Smart Compression: Quality optimized per format (80% JPEG, 75% WebP, 70% AVIF)
- Blur Placeholders: Tiny base64 data URLs for progressive loading
- Metadata Generation: Complete image information in JSON format
Audit and validate:
npm run images:audit # Check featured images status
npm run images:audit:gallery # Check gallery images
npm run images:validate # Validate all image references (CI-ready)
npm run images:validate:verbose # Detailed validation outputOptimize images:
npm run images:optimize # Optimize new/changed images
npm run images:optimize:force # Re-optimize all imagesDownload/refresh images:
npm run images:download # Download missing images from iNaturalist
npm run images:refresh # Update with better quality versions
npm run images:refresh:gallery # Refresh gallery imagesCleanup:
npm run images:check # Check for orphaned images
npm run images:cleanup # Clean up obsolete imagesSee Image Optimization Guide for complete documentation and Image Audit Report for current status.
This project takes security seriously. We use automated security scanning including:
- Dependabot for dependency vulnerabilities
- CodeQL for static code analysis
- TruffleHog for secret scanning
- ESLint Security for code patterns
- License compliance checking
See Security Setup Guide for details on our security infrastructure.
This repository is optimized for AI-assisted development with comprehensive agent instructions:
- AGENTS.md - Core coding conventions, patterns, and best practices
- .github/instructions/ - File-pattern specific guidelines
- i18n.instructions.md - Internationalization rules
- content.instructions.md - MDX content standards
- components.instructions.md - React component patterns
- api.instructions.md - API route development
- scripts.instructions.md - Utility script conventions
These instructions help AI agents understand our architecture, maintain consistency, and follow project best practices when making contributions.
The atlas is open. Three licenses apply to three different things:
| What | License | File |
|---|---|---|
| Application code | MIT | LICENSE |
| Written content (species profiles, glossary, guides) | CC BY 4.0 | LICENSE-CONTENT.md |
| Structured dataset (Darwin Core Archive, frontmatter) | CC BY 4.0 | LICENSE-DATA.md |
Photographs are the exception. Gallery images are sourced from iNaturalist
and are mostly CC BY-NC; each carries its own credit and license props.
Commercial reuse of photographs requires separate licensing from the
photographer. Do not assume the code or content license covers them.
See USAGE-POLICY.md for the full policy.
- The magnificent trees of Costa Rica for their beauty and ecological importance
- SINAC - Costa Rica's National System of Conservation Areas
- INBio - Costa Rica's National Biodiversity Institute
- The conservation organizations working to protect Costa Rica's forests
- The maintainers and collaborators supporting this project
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Made with 💚 for Costa Rica's forests 🇨🇷
"The nation that destroys its soil destroys itself. Forests are the lungs of our land."
— Franklin D. Roosevelt