Initial commit: Northern Thailand Ping River Monitor v3.1.0

Features: - Real-time water level monitoring for Ping River Basin (16 stations) - Coverage from Chiang Dao to Nakhon Sawan in Northern Thailand - FastAPI web interface with interactive dashboard and station management - Multi-database support (SQLite, MySQL, PostgreSQL, InfluxDB, VictoriaMetrics) - Comprehensive monitoring with health checks and metrics collection - Docker deployment with Grafana integration - Production-ready architecture with enterprise-grade observability CI/CD & Automation: - Complete Gitea Actions workflows for CI/CD, security, and releases - Multi-Python version testing (3.9-3.12) - Multi-architecture Docker builds (amd64, arm64) - Daily security scanning and dependency monitoring - Automated documentation generation - Performance testing and validation Production Ready: - Type safety with Pydantic models and comprehensive type hints - Data validation layer with range checking and error handling - Rate limiting and request tracking for API protection - Enhanced logging with rotation, colors, and performance metrics - Station management API for dynamic CRUD operations - Comprehensive documentation and deployment guides Technical Stack: - Python 3.9+ with FastAPI and Pydantic - Multi-database architecture with adapter pattern - Docker containerization with multi-stage builds - Grafana dashboards for visualization - Gitea Actions for CI/CD automation - Enterprise monitoring and alerting Ready for deployment to B4L infrastructure!
2025-08-12 15:37:09 +07:00
commit af62cfef0b
60 changed files with 13267 additions and 0 deletions
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,277 @@
+# Contributing to Northern Thailand Ping River Monitor
+
+Thank you for your interest in contributing to the Northern Thailand Ping River Monitor! This document provides guidelines and information for contributors.
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python 3.9 or higher
+- Git
+- Basic knowledge of water monitoring systems
+- Familiarity with FastAPI and time-series databases (optional)
+
+### Development Setup
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://git.b4l.co.th/B4L/Northern-Thailand-Ping-River-Monitor.git
+   cd Northern-Thailand-Ping-River-Monitor
+   ```
+
+2. **Create a virtual environment:**
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Run tests:**
+   ```bash
+   python test_integration.py
+   ```
+
+5. **Start the development server:**
+   ```bash
+   python run.py --web-api
+   ```
+
+## 🔧 Development Guidelines
+
+### Code Style
+- Follow PEP 8 Python style guidelines
+- Use type hints for all function parameters and return values
+- Write descriptive docstrings for all classes and functions
+- Keep functions focused and under 50 lines when possible
+
+### Testing
+- Write tests for new features
+- Ensure all existing tests pass before submitting
+- Test both success and error cases
+- Include integration tests for API endpoints
+
+### Documentation
+- Update README.md for new features
+- Add docstrings to all new functions and classes
+- Update API documentation for new endpoints
+- Include examples in documentation
+
+## 📝 Contribution Process
+
+### 1. Issue Creation
+- Check existing issues before creating new ones
+- Use clear, descriptive titles
+- Provide detailed descriptions with steps to reproduce (for bugs)
+- Include system information and logs when relevant
+
+### 2. Pull Request Process
+1. **Fork the repository**
+2. **Create a feature branch:**
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. **Make your changes**
+4. **Test thoroughly:**
+   ```bash
+   python test_integration.py
+   python test_station_management.py
+   ```
+5. **Commit with clear messages:**
+   ```bash
+   git commit -m "Add: New station validation feature"
+   ```
+6. **Push to your fork:**
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+7. **Create a pull request**
+
+### Pull Request Guidelines
+- Use clear, descriptive titles
+- Provide detailed descriptions of changes
+- Reference related issues
+- Include screenshots for UI changes
+- Ensure all tests pass
+- Update documentation as needed
+
+## 🎯 Areas for Contribution
+
+### High Priority
+- **Additional Database Support** - MongoDB, TimescaleDB
+- **Authentication System** - User management and API keys
+- **Real-time Alerts** - Email/SMS notifications for critical conditions
+- **Mobile App** - React Native or Flutter interface
+- **Advanced Analytics** - Trend analysis and forecasting
+
+### Medium Priority
+- **Bulk Station Operations** - Import/export multiple stations
+- **Map Interface** - Visual station management
+- **Data Export** - CSV, Excel format support
+- **Performance Optimization** - Query optimization and caching
+- **Internationalization** - Multi-language support
+
+### Low Priority
+- **Additional Visualizations** - Custom chart types
+- **Report Generation** - Automated PDF reports
+- **Integration APIs** - Third-party service connections
+- **Advanced Logging** - Structured logging with ELK stack
+
+## 🐛 Bug Reports
+
+When reporting bugs, please include:
+
+1. **Environment Information:**
+   - Operating system and version
+   - Python version
+   - Database type and version
+   - Browser (for web interface issues)
+
+2. **Steps to Reproduce:**
+   - Clear, numbered steps
+   - Expected vs actual behavior
+   - Screenshots or error messages
+
+3. **Additional Context:**
+   - Log files (sanitized of sensitive data)
+   - Configuration details
+   - Recent changes to the system
+
+## 💡 Feature Requests
+
+For feature requests, please provide:
+
+1. **Use Case:** Why is this feature needed?
+2. **Description:** What should the feature do?
+3. **Acceptance Criteria:** How do we know it's complete?
+4. **Priority:** How important is this feature?
+5. **Alternatives:** Are there workarounds available?
+
+## 🔒 Security
+
+### Reporting Security Issues
+- **DO NOT** create public issues for security vulnerabilities
+- Email security issues to: [security contact]
+- Include detailed information about the vulnerability
+- Allow time for fixes before public disclosure
+
+### Security Guidelines
+- Never commit sensitive data (passwords, API keys)
+- Use environment variables for configuration
+- Validate all user inputs
+- Follow OWASP security guidelines
+- Keep dependencies updated
+
+## 📊 Database Contributions
+
+### Adding New Database Support
+1. Create adapter in `src/database_adapters.py`
+2. Implement all required methods
+3. Add configuration options in `src/config.py`
+4. Update documentation
+5. Add integration tests
+
+### Database Schema Changes
+- Provide migration scripts
+- Test with existing data
+- Document breaking changes
+- Update all database adapters
+
+## 🌐 API Contributions
+
+### Adding New Endpoints
+1. Define Pydantic models in `src/models.py`
+2. Implement endpoint in `src/web_api.py`
+3. Add input validation
+4. Include error handling
+5. Write comprehensive tests
+6. Update API documentation
+
+### API Guidelines
+- Use RESTful conventions
+- Include proper HTTP status codes
+- Provide clear error messages
+- Support pagination for large datasets
+- Include rate limiting considerations
+
+## 📈 Performance Guidelines
+
+### Optimization Areas
+- Database query efficiency
+- API response times
+- Memory usage
+- Concurrent request handling
+- Data processing speed
+
+### Monitoring
+- Use built-in metrics collection
+- Monitor response times
+- Track error rates
+- Watch resource usage
+- Set up alerts for issues
+
+## 🧪 Testing Guidelines
+
+### Test Types
+- **Unit Tests:** Individual function testing
+- **Integration Tests:** Component interaction testing
+- **API Tests:** Endpoint functionality testing
+- **Performance Tests:** Load and stress testing
+
+### Test Coverage
+- Aim for >80% code coverage
+- Test both success and failure paths
+- Include edge cases
+- Test with different database backends
+
+## 📚 Documentation Standards
+
+### Code Documentation
+- Use clear, descriptive variable names
+- Write comprehensive docstrings
+- Include type hints
+- Add inline comments for complex logic
+
+### User Documentation
+- Keep README.md updated
+- Provide clear installation instructions
+- Include usage examples
+- Document configuration options
+
+## 🤝 Community Guidelines
+
+### Communication
+- Be respectful and professional
+- Help newcomers get started
+- Share knowledge and experiences
+- Provide constructive feedback
+
+### Code Reviews
+- Review code thoroughly
+- Provide specific, actionable feedback
+- Be open to suggestions
+- Focus on code quality and maintainability
+
+## 📞 Getting Help
+
+### Resources
+- **Documentation:** README.md and docs/
+- **API Reference:** http://localhost:8000/docs
+- **Issues:** GitHub Issues section
+- **Discussions:** GitHub Discussions
+
+### Contact
+- **General Questions:** Create a GitHub issue
+- **Security Issues:** [security contact]
+- **Maintainer:** [maintainer contact]
+
+## 🎉 Recognition
+
+Contributors will be recognized in:
+- README.md contributors section
+- Release notes for significant contributions
+- Special recognition for major features
+
+Thank you for contributing to the Northern Thailand Ping River Monitor! Your contributions help improve water resource monitoring and management in the region.