# vprezende/ilpf architecture

> Architecture diagram of the GitHub repository vprezende/ilpf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vprezende/ilpf
- Repository: https://github.com/vprezende/ilpf

## Overview

##### Project type and purpose
- This is a cross-platform mobile/desktop application built with Flutter (Dart).

##### File structure
- Top-level platform folders: android/, ios/, windows/. These contain the native shell and embedding code.
- lib/: holds the Flutter application code.
- lib/main.dart: application entry point.
- lib/controllers/area_controller.dart: core domain logic for area drawing and data fetch.
- lib/widgets/: UI components (snackbars, buttons, map canvas).
- pubspec.yaml: declares dependencies (dart_jts, geodesy, http, Flutter SDK).
- test/: widget_test.dart for basic unit/widget tests.
- android/, ios/, windows/: native project wrappers generated by Flutter.

##### README for additional insights
- Technologies: Flutter (UI), Dart (language), dart_jts (geometry), geodesy (centroid), http (API client), SoilGrids API.

##### Components
a. Main components
- Presentation layer (Flutter UI widgets)
- Controller layer (AreaController)
- Geometry library modules (dart_jts, geodesy)
- HTTP Client module (http package)
- External service (ISRIC SoilGrids API)
- Native platform shells (Android, iOS, Windows embedding)
b. Relationships and interactions
- User taps/gestures in UI → UI Widgets forward events to AreaController.
- AreaController uses dart_jts/geodesy for sort/close/centroid computations.
- AreaController uses HTTP Client to send requests to SoilGrids API.
- API responses flow back to AreaController → UI updates (snackbars, map overlays).
- Native shells host the Flutter engine and render the UI.
c. Architectural patterns and design principles
- Separation of concerns: UI vs. domain/controller vs. external services.
- In-memory state management (AreaController holds currentArea, areas, originalArea).
- Retry logic for HTTP (handling 429 status).
d. Key technologies/frameworks
- Flutter framework (single codebase for all platforms).
- dart_jts & geodesy for computational geometry.
- http package for REST calls.
- Platform embedding code (Kotlin for Android, Swift for iOS, C++/CMake for Windows).

##### Elements
- Clear labels: “UI Widgets”, “AreaController”, “Geometry Library”, “HTTP Client”, “ISRIC SoilGrids API”, “Android Shell”, etc.
- Blue rectangles: internal app components (UI, controller).
- Orange rectangles: libraries/modules.
- Annotations for stateful lists (areas, currentArea) and retry logic for HTTP.

Guidelines:
- Native shells at the bottom or top to show hosting.
- Geometry operations into one “Geometry Module” with sub-labels for dart_jts and geodesy.
- HTTP client as part of a “Data Service” component.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Native Platform Shells"
        AndroidShell["Android Shell"]:::shell
        iOSShell["iOS Shell"]:::shell
        WindowsShell["Windows Shell"]:::shell
    end

    subgraph "Flutter Engine & Dart VM"
        Engine["Flutter Engine & Dart VM"]:::shell
    end

    subgraph "Flutter Application"
        Entry["App Entry (main.dart)"]:::internal
        UI["UI Widgets"]:::internal
        Controller["AreaController"]:::internal
        Geometry["Geometry Module\n(dart_jts, geodesy)"]:::library
        DataService["Data Service\n(HTTP Client)"]:::library
    end

    API["ISRIC SoilGrids API"]:::external

    AndroidShell -->|hosts| Engine
    iOSShell -->|hosts| Engine
    WindowsShell -->|hosts| Engine

    Engine -->|runs| Entry

    Entry -->|builds UI| UI
    UI -->|user events| Controller
    Controller -->|compute geometry| Geometry
    Geometry -->|results| Controller
    Controller -->|fetch soil data| DataService
    DataService -->|HTTP Request| API
    API -->|HTTP Response| DataService
    DataService -->|data| Controller
    Controller -->|update UI| UI

    click Entry "https://github.com/vprezende/ilpf/blob/main/lib/main.dart"
    click UI "https://github.com/vprezende/ilpf/blob/main/lib/widgets/app_snackbars.dart"
    click UI "https://github.com/vprezende/ilpf/tree/main/lib/widgets"
    click Controller "https://github.com/vprezende/ilpf/blob/main/lib/controllers/area_controller.dart"
    click Geometry "https://github.com/vprezende/ilpf/blob/main/pubspec.yaml"
    click DataService "https://github.com/vprezende/ilpf/blob/main/pubspec.yaml"
    click AndroidShell "https://github.com/vprezende/ilpf/tree/main/android/"
    click iOSShell "https://github.com/vprezende/ilpf/tree/main/ios/"
    click WindowsShell "https://github.com/vprezende/ilpf/tree/main/windows/"

    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef library fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef external fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef shell fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
