Clima para Manejo

📌 Executive Summary

A high-performance Full Stack application for agribusiness, designed to assist in operational decision-making for sugarcane management. The system processes raw meteorological data and transforms it into indicators for Operational Window (ideal moments for harvesting or spraying) and Water Balance (calculation of P - ET₀).

📖 Background

"What started as a Technical Test evolved into a robust software engineering project."

This project was born from a technical challenge for a developer position. After the initial delivery, I decided to refactor and expand the application to use it as a laboratory for best practices. The goal was to transform a simple MVP into a production-ready application, implementing clean architecture, automated tests, distributed caching, and CI/CD pipelines.

It demonstrates my ability to:

• Understand complex business rules (Agronomy).
• Evolve legacy/initial code.
• Configure infrastructure and deployment from scratch.

🛠️ Tech Stack & Architecture

The system uses a modern Hybrid Architecture, separating responsibilities while maintaining deployment simplicity.

Frontend (User Experience)

• Next.js 14 (App Router): Chosen for SSR (Server-Side Rendering) capabilities, ensuring fast initial performance and good SEO.
• TypeScript: Strict end-to-end typing to reduce runtime bugs.
• Tailwind CSS + Shadcn/ui: Creation of responsive, accessible interfaces with native Dark Mode.
• State Management: Use of State Machine patterns to manage interface states (Loading, Success, Error, Empty).

Backend (Processing Engine)

• FastAPI (Python 3.11): Chosen for asynchronous performance and ease in handling data processing.
• Clean Architecture: Code is divided into Routing, Services (Business Logic), and Schemas (Data Contracts) layers.
• Redis: Implementation of cache to store external API request results, reducing latency and avoiding Rate Limits.
• Pydantic: Rigorous validation of input and output data.

Infrastructure & DevOps

• Docker & Docker Compose: Fully containerized development environment, ensuring "works on my machine" means "works anywhere".
• GitHub Actions (CI): Automated pipeline running tests (Pytest/Jest) and linters on every Push or PR.
• Vercel: Automated deployment with Serverless architecture.
• Open-Meteo API: Integration with external weather and geocoding services.

💡 Key Features & Technical Challenges

1. Water Balance Algorithm (FAO-56) Implemented agronomic logic to calculate Reference Evapotranspiration. The system crosses precipitation data with soil water loss to tell the agronomist the real water balance of the day.

2. Reverse Proxy Pattern To avoid CORS issues and exposing API keys, Next.js acts as a proxy. The client hits the Frontend ( /api/* ), which redirects the call to the Python Backend internally. This simplifies security.

3. Intelligent Caching Strategy Weather data doesn't change every second. I implemented a caching layer (Redis) that stores forecasts by city. If a user searches for "Ribeirão Preto" and, 1 minute later, another user searches for the same city, the data is returned instantly from the cache, without consuming the external API.

4. Resilient Design The system handles failures gracefully. If the weather API goes down, the user receives clear visual feedback (Toasts/Alerts) instead of a broken white screen.

🚀 How to Run (Locally)

# The project is 100% Dockerized
git clone https://github.com/samdevtx/clima-manejo.git
cd clima-manejo
docker compose up --build