{"id":30041475,"url":"https://github.com/youneslaaroussi/forestshield-infrastructure","last_synced_at":"2026-04-15T15:34:26.540Z","repository":{"id":302151413,"uuid":"1011211648","full_name":"youneslaaroussi/forestshield-infrastructure","owner":"youneslaaroussi","description":"Automated Deforestation Monitoring Platform","archived":false,"fork":false,"pushed_at":"2025-06-30T20:33:35.000Z","size":16792,"stargazers_count":4,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-07T02:55:15.780Z","etag":null,"topics":["aws","aws-lambda","nestjs"],"latest_commit_sha":null,"homepage":"https://forestshieldapp.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/youneslaaroussi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-30T13:22:32.000Z","updated_at":"2025-07-23T08:25:09.000Z","dependencies_parsed_at":"2025-06-30T21:44:50.203Z","dependency_job_id":null,"html_url":"https://github.com/youneslaaroussi/forestshield-infrastructure","commit_stats":null,"previous_names":["youneslaaroussi/forestshield-infrastructure"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/youneslaaroussi/forestshield-infrastructure","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youneslaaroussi%2Fforestshield-infrastructure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youneslaaroussi%2Fforestshield-infrastructure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youneslaaroussi%2Fforestshield-infrastructure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youneslaaroussi%2Fforestshield-infrastructure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youneslaaroussi","download_url":"https://codeload.github.com/youneslaaroussi/forestshield-infrastructure/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youneslaaroussi%2Fforestshield-infrastructure/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31847985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","nestjs"],"created_at":"2025-08-07T02:45:57.975Z","updated_at":"2026-04-15T15:34:26.533Z","avatar_url":"https://github.com/youneslaaroussi.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![AWS](https://img.shields.io/badge/AWS-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/)\r\n[![AWS Lambda](https://img.shields.io/badge/AWS%20Lambda%20Core-FF9900?style=for-the-badge\u0026logo=aws-lambda\u0026logoColor=white)](https://aws.amazon.com/lambda/)\r\n[![AWS S3](https://img.shields.io/badge/AWS%20S3-569A31?style=for-the-badge\u0026logo=amazon-s3\u0026logoColor=white)](https://aws.amazon.com/s3/)\r\n[![AWS DynamoDB](https://img.shields.io/badge/AWS%20DynamoDB-4053D6?style=for-the-badge\u0026logo=amazon-dynamodb\u0026logoColor=white)](https://aws.amazon.com/dynamodb/)\r\n[![AWS SageMaker](https://img.shields.io/badge/AWS%20SageMaker-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/sagemaker/)\r\n[![AWS Step Functions](https://img.shields.io/badge/AWS%20Step%20Functions-FF4F8B?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/step-functions/)\r\n[![AWS App Runner](https://img.shields.io/badge/AWS%20App%20Runner-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/apprunner/)\r\n[![AWS CloudFormation](https://img.shields.io/badge/AWS%20CloudFormation-FF4F00?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/cloudformation/)\r\n\r\n[![AWS Athena](https://img.shields.io/badge/AWS%20Athena-8C4FFF?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/athena/)\r\n[![AWS ElastiCache](https://img.shields.io/badge/AWS%20ElastiCache-C925D1?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/elasticache/)\r\n[![AWS SNS](https://img.shields.io/badge/AWS%20SNS-FF4F8B?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/sns/)\r\n[![AWS ECR](https://img.shields.io/badge/AWS%20ECR-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/ecr/)\r\n[![AWS Glue](https://img.shields.io/badge/AWS%20Glue-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/glue/)\r\n[![AWS IAM](https://img.shields.io/badge/AWS%20IAM-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/iam/)\r\n[![AWS VPC](https://img.shields.io/badge/AWS%20VPC-FF9900?style=for-the-badge\u0026logo=amazon-aws\u0026logoColor=white)](https://aws.amazon.com/vpc/)\r\n[![AWS CloudWatch](https://img.shields.io/badge/AWS%20CloudWatch-FF4F8B?style=for-the-badge\u0026logo=amazon-cloudwatch\u0026logoColor=white)](https://aws.amazon.com/cloudwatch/)\r\n\r\n[![NestJS](https://img.shields.io/badge/NestJS-E0234E?style=for-the-badge\u0026logo=nestjs\u0026logoColor=white)](https://nestjs.com/)\r\n[![Python](https://img.shields.io/badge/Python-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)](https://python.org/)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)](https://typescriptlang.org/)\r\n[![Java](https://img.shields.io/badge/Java-ED8B00?style=for-the-badge\u0026logo=openjdk\u0026logoColor=white)](https://openjdk.org/)\r\n[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)](https://docker.com/)\r\n[![Redis](https://img.shields.io/badge/Redis-DC382D?style=for-the-badge\u0026logo=redis\u0026logoColor=white)](https://redis.io/)\r\n\r\n[![GitHub Repository](https://img.shields.io/badge/GitHub-100000?style=for-the-badge\u0026logo=github\u0026logoColor=white)](https://github.com/your-org/forestshield)\r\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg?style=for-the-badge)](LICENSE)\r\n[![Serverless](https://img.shields.io/badge/Serverless-FD5750?style=for-the-badge\u0026logo=serverless\u0026logoColor=white)](https://serverless.com/)\r\n[![Machine Learning](https://img.shields.io/badge/ML-K--means-4285F4?style=for-the-badge\u0026logo=tensorflow\u0026logoColor=white)](https://scikit-learn.org/)\r\n\r\n---\r\n\r\n**Objective:**  \r\nForestShield aims to provide an automated, real-time, and scientifically robust platform for monitoring deforestation using satellite imagery and advanced machine learning. By leveraging cloud-native architecture and unsupervised learning, ForestShield delivers accurate, scalable, and actionable insights to help protect global forests.\r\n\r\n---\r\n\r\n## 🌲 ForestShield: Automated Deforestation Monitoring Platform\r\n\r\n![ForestShield Architecture](./assets/BannerImage.png)\r\n\r\n**ForestShield** is a fully serverless, cloud-native platform for automated monitoring and analysis of deforestation using Sentinel-2 satellite imagery. It leverages AWS managed services, machine learning (K-means clustering), and scalable event-driven architecture to provide real-time forest monitoring capabilities.\r\n\r\n### 🔗 Quick Links\r\n\r\n- **🌐 Live Application:** [https://forestshieldapp.com](https://forestshieldapp.com)\r\n- **🚀 API Docs on Swagger UI:** [https://api.forestshieldapp.com](https://api.forestshieldapp.com/api/docs)\r\n- **📂 Frontend GitHub Repository:** [https://github.com/youneslaaroussi/forestshield-frontend](https://github.com/youneslaaroussi/forestshield-frontend)\r\n\r\n---\r\n\r\n## 📦 Setup \u0026 Deployment\r\n\r\n### Prerequisites\r\n\r\nBefore setting up ForestShield, ensure you have the following installed and configured:\r\n\r\n#### **Required Software**\r\n- **AWS CLI** (v2.x) - [Installation Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)\r\n- **Docker** (v20.x+) - [Installation Guide](https://docs.docker.com/get-docker/)\r\n- **Node.js** (v18.x+) - [Installation Guide](https://nodejs.org/)\r\n- **Python** (v3.9+) - [Installation Guide](https://python.org/downloads/)\r\n- **Java** (v11+) - [Installation Guide](https://openjdk.org/install/)\r\n- **Maven** (v3.6+) - [Installation Guide](https://maven.apache.org/install.html)\r\n\r\n#### **AWS Account Setup**\r\n- **AWS Account** with appropriate permissions\r\n- **AWS CLI configured** with credentials:\r\n  ```bash\r\n  aws configure\r\n  # Enter your AWS Access Key ID, Secret Access Key, and default region\r\n  ```\r\n- **Docker authenticated with ECR**:\r\n  ```bash\r\n  aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin \u003caccount-id\u003e.dkr.ecr.us-west-2.amazonaws.com\r\n  ```\r\n\r\n#### **Required AWS Permissions**\r\nYour AWS user/role needs permissions for:\r\n- CloudFormation (full access)\r\n- Lambda, Step Functions, SageMaker\r\n- S3, DynamoDB, Athena, Glue\r\n- App Runner, ECR, ElastiCache\r\n- IAM (for role creation)\r\n- SNS, CloudWatch\r\n\r\n### Installation Steps\r\n\r\n#### **1. Clone the Repository**\r\n```bash\r\ngit clone https://github.com/youneslaaroussi/forestshield-server.git\r\ncd forestshield-server\r\n```\r\n\r\n#### **2. Configure Environment**\r\n```bash\r\n# Copy and edit the sample environment file\r\ncp env.sample .env\r\n\r\n# Edit .env with your AWS credentials and configuration\r\nnano .env\r\n```\r\n\r\n#### **3. Deploy on AWS**\r\n```bash\r\n# Deploy on AWS (This Script will perform all required setup and uses CloudFormation)\r\n./deploy.sh\r\n\r\n# if on Windows Powershell and have WSL installed\r\nbash deploy.sh\r\n```\r\n\r\n---\r\n\r\n## 🧪 Usage Examples\r\n\r\n### **Trigger Deforestation Analysis**\r\n```bash\r\ncurl -X POST https://api.forestshieldapp.com/sentinel/step-functions/trigger \\\r\n-H \"Content-Type: application/json\" \\\r\n-d '{\r\n  \"searchParams\": {\r\n    \"latitude\": -6.0,\r\n    \"longitude\": -53.0,\r\n    \"startDate\": \"2024-01-01\",\r\n    \"endDate\": \"2024-01-15\",\r\n    \"cloudCover\": 20\r\n  },\r\n  \"maxImages\": 3\r\n}'\r\n```\r\n\r\nView the Step Functions workflow live in your AWS Dashboard.\r\n\r\n### **Get Heatmap Data**\r\n```bash\r\ncurl \"https://api.forestshieldapp.com/dashboard/heatmap?north=-5.9\u0026south=-6.1\u0026east=-52.9\u0026west=-53.1\u0026days=30\"\r\n```\r\n\r\n### **Manage Alerts**\r\n```bash\r\n# Get recent alerts\r\ncurl \"https://api.forestshieldapp.com/dashboard/alerts?limit=10\"\r\n\r\n# Get high-priority alerts\r\ncurl \"https://api.forestshieldapp.com/dashboard/alerts?level=HIGH\u0026acknowledged=false\"\r\n```\r\n\r\nFor complete API documentation see [DOCS.md](./DOCS.md).\r\n\r\n---\r\n\r\n## 🏗️ Architecture Overview\r\n\r\n\r\nForestShield represents a **state-of-the-art serverless architecture** that leverages the full power of AWS managed services to create an intelligent, scalable, and cost-effective deforestation monitoring system. The platform demonstrates advanced cloud-native design patterns and scientific computing at scale.\r\n\r\n![Pipeline](./assets/overall_arch.png)\r\n\r\n### 🎯 **Core Architectural Principles**\r\n\r\n- **100% Serverless**: Zero server management, automatic scaling, pay-per-use pricing\r\n- **Event-Driven**: Asynchronous processing with decoupled microservices\r\n- **ML-First**: Machine learning integrated throughout the data pipeline\r\n- **Real-Time**: Live monitoring with WebSocket connections and instant alerts\r\n- **Multi-Region**: Geographically aware processing with region-specific ML models\r\n\r\n### 🧠 **ML Pipeline**\r\n\r\nThe system implements sophisticated **unsupervised machine learning** using K-means clustering on scientifically-derived vegetation indices:\r\n\r\n#### **NDVI Calculation**\r\n```latex\r\nNDVI = \\frac{(NIR - Red)}{(NIR + Red)}\r\n```\r\n- **NIR**: Near-Infrared Band (Sentinel-2 B08, 842nm)\r\n- **Red**: Red Band (Sentinel-2 B04, 665nm) \r\n- **Range**: -1.0 to +1.0 (vegetation typically \u003e 0.2)\r\n\r\n#### **5-Dimensional Feature Engineering**\r\nEach pixel becomes a feature vector: `[NDVI, Red_Reflectance, NIR_Reflectance, Latitude, Longitude]`\r\n\r\n#### **Automated K-Selection via Elbow Method**\r\n```python\r\n# Sum of Squared Errors optimization\r\nSSE = Σ(k=1 to K) Σ(x∈Cluster_k) ||x - centroid_k||²\r\n```\r\n\r\n![SageMaker K-means Clustering Results](./assets/feature_distributions.png)\r\n\r\n### ⚡ Lambda-Driven Architecture with SnapStart Optimization\r\n\r\nAt its core, ForestShield is powered by AWS Lambda — handling everything from STAC-based satellite image searches to NDVI computations and unsupervised ML.\r\n\r\nOur Java-based image ingestion Lambda is accelerated using [**AWS Lambda SnapStart**](https://docs.aws.amazon.com/lambda/latest/dg/snapstart.html), cutting cold starts from 2s to ~200ms. This ensures we can **query, fetch, and process fresh Sentinel-2 imagery in seconds**.\r\n\r\nThanks to this architecture, ForestShield:\r\n- Processes over **1M pixels/month** with **under $10 Lambda spend**\r\n- Delivers **10x faster clustering** vs EC2-based approaches\r\n- Instantly scales from zero to thousands of parallel detections\r\n\r\n---\r\n\r\n### 🏛️ **Step Functions Orchestration**\r\n\r\n![Step Functions Workflow](./assets/stepfunctions_graph%20(1).png)\r\n\r\n---\r\n\r\n**🏆 This architecture demonstrates AWS best practices for:**\r\n- Serverless-first design with event-driven processing\r\n- ML/AI integration with scientific computing\r\n- Real-time data processing and visualization  \r\n- Cost-optimized scalable infrastructure\r\n- Enterprise security and compliance patterns\r\n\r\n---\r\n\r\n## 🧹 Cleanup\r\n\r\nTo remove all AWS resources and avoid ongoing charges:\r\n\r\n```bash\r\n./deploy/cleanup.sh\r\n```\r\n\r\n**⚠️ Warning:** This will permanently delete all data, models, and infrastructure.\r\n\r\n---\r\n\r\n## 📖 Documentation\r\n\r\n- **📋 Complete Technical Specification:** [DOCS.md](./DOCS.md)\r\n- **🏗️ Infrastructure Details:** [cloudformation.yaml](./cloudformation.yaml)\r\n- **🚀 Deployment Scripts:** [deploy/](./deploy/)\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\r\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\r\n4. Push to the branch (`git push origin feature/amazing-feature`)\r\n5. Open a Pull Request\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n---\r\n\r\n## 🙏 Acknowledgments\r\n\r\n- **ESA Sentinel-2** for satellite imagery\r\n- **AWS** for cloud infrastructure\r\n- **Open source community** for tools and libraries\r\n\r\n---\r\n\r\n## Citations\r\n\r\nMethods applied based on research:\r\n\r\n- [Detecting deforestation in the Amazon rainforest using unsupervised K-means clustering on satellite imagery](./https://developers.arcgis.com/python/latest/samples/detecting-deforestation-using-kmeans-clustering-on-sentinel-imagery/)\r\n- [Md Jelas I, Zulkifley MA, Abdullah M and Spraggon M (2024) Deforestation detection using deep learning-based semantic segmentation techniques: a systematic review. Front. For. Glob. Change 7:1300060. doi: 10.3389/ffgc.2024.1300060](./https://www.frontiersin.org/journals/forests-and-global-change/articles/10.3389/ffgc.2024.1300060/full)\r\n- [aws-smsl-geospatial-analysis-deforestation](https://github.com/aws-samples/aws-smsl-geospatial-analysis-deforestation/)\r\n\r\n---\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouneslaaroussi%2Fforestshield-infrastructure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyouneslaaroussi%2Fforestshield-infrastructure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyouneslaaroussi%2Fforestshield-infrastructure/lists"}