# 0011ashwin/soil-analyzer architecture

> Architecture diagram of the GitHub repository 0011ashwin/soil-analyzer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0011ashwin/soil-analyzer
- Repository: https://github.com/0011ashwin/soil-analyzer

## Overview

##### Project type and purpose
- This is a multi-platform soil analysis application combining:
- A web GUI built with Streamlit (app.py, run.py)
- A native Android app built with Kivy (android_app/)

##### File structure
- Top-level:
- soil_analyzer/
– app.py, run.py, requirements.txt, soil_report_dataset_500.csv
– android_app/ (Kivy front-end, assets/, main.py, soilanalyzer.kv, report_history.json)
– README.md
- Patterns & roles:
- “app.py” & “run.py” → Streamlit “frontend + backend” in one
- android_app/ → standalone mobile UI + local logic
- Data files: CSV dataset and JSON history
- Build scripts (build.bat, create_icon.py) for Android packaging
- Config & deployment:
- requirements.txt at both levels
- .env for GROQ_API_KEY
- buildozer for Android

##### README insights
- Technologies: Python 3.8+, Streamlit, Kivy, Groq LLM API (Llama 3 70B)
- Features & flow:
1) UI collects parameters
2) Dataset lookup (nearest neighbors)
3) Groq API call → LLM generates report
4) Visualizations (gauge, radar charts)
5) Persist report history and export as HTML/JSON

##### Main components
a. Frontend(s):
- Web Client (Browser) → Streamlit Server
- Android Device → Kivy App
b. Backend & Business Logic (common code base):
- Parameter ingestion & validation
- Dataset module (CSV loader + similarity search)
- Groq API integration module
- Report generator & formatter
- History manager (JSON storage)
c. Data Storage:
- Local CSV (soil_report_dataset_500.csv)
- Local JSON (report_history.json in android_app/)
- .env config store for API key
d. External Service:
- Groq LLM API endpoint
e. Visualization & Export:
- Gauge and radar chart components
- HTML/PDF export module

##### Relationships & interactions
1) User → Frontend (parameter input)
2) Frontend → Dataset module (nearest-neighbor lookup)
3) Backend → Groq API (prompt send/response)
4) Backend → Visualization module → Frontend (render charts)
5) Backend → History manager (persist report)
6) Frontend → Export module (download HTML)
- For the Android path, show offline fallback: if no API key, use pre-generated reports from CSV.

##### Architectural patterns & principles
- Modular monolith for web: clear separation of UI, business logic, data
- Single-code logic reused across two frontends
- Externalize configuration (API keys in .env)
- Graceful fallback for offline functionality
- MVC-like flow inside Streamlit: UI callbacks → model layer → view rendering

##### Essential elements
- Arrowheads to indicate request/response flows
- A visible boundary for the “soil_analyzer” codebase
- Notes on fallback logic: “If GROQ_API_KEY missing → use pre-computed CSV report”
- Build process for Android (Buildozer step)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Devices
    U1(["User"]):::user
    U2(["User"]):::user

    %% Frontends
    subgraph "Frontends"
        direction TB
        WFE["Web Frontend\n(Streamlit UI)"]:::frontend
        AFE["Android Frontend\n(Kivy App)"]:::frontend
    end

    %% Backend Modules
    subgraph "Backend Modules"
        direction TB
        PI["Parameter Ingestion\n& Validation"]:::backend
        DL["Dataset Loader\n(CSV similarity search)"]:::backend
        API["Groq API Integration\n& Report Generator"]:::backend
        VIS["Visualization & Export\n(Charts & HTML)"]:::backend
        HM["History Manager\n(JSON storage)"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        CSV["Local CSV Dataset\n(soil_report_dataset_500.csv)"]:::storage
        ACSV["Android CSV Copy\n(data/soil_report_dataset_500.csv)"]:::storage
        JSONH["Report History JSON\n(report_history.json)"]:::storage
        ENV[".env Config\n(GROQ_API_KEY)"]:::storage
    end

    %% External Service
    GAPI(["Groq LLM API"]):::external

    %% Connections
    U1 -->|1. Input params| WFE
    U2 -->|1. Input params| AFE

    WFE -->|2. POST soil params| PI
    AFE -->|2. POST soil params| PI

    PI -->|3. GET similar profiles| DL
    DL -->|reads| CSV
    DL -->|offline fallback\nif no API key| ACSV

    PI -->|4. Send prompt| API
    API -->|calls| GAPI
    GAPI -->|response| API

    API -->|5. Generate report| VIS
    VIS -->|render charts| WFE
    VIS -->|render charts| AFE
    VIS -->|export HTML/JSON| WFE

    VIS -->|save history| HM
    HM -->|writes| JSONH

    %% Bounding
    classDef frontend fill:#D0E8FF,stroke:#024574,color:#024574
    classDef backend fill:#DFF2D8,stroke:#2E7D32,color:#2E7D32
    classDef storage fill:#FFE8A1,stroke:#F57F17,color:#F57F17
    classDef external fill:#E1D4F0,stroke:#512DA8,color:#512DA8
    classDef user fill:#FFFFFF,stroke:#000000,color:#000000

    %% Click Events
    click WFE "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/app.py"
    click WFE "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/run.py"
    click AFE "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/main.py"
    click AFE "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/soilanalyzer.kv"
    click CSV "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/soil_report_dataset_500.csv"
    click ACSV "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/data/soil_report_dataset_500.csv"
    click JSONH "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/report_history.json"
    click API "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/app.py"
    click VIS "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/app.py"
    click HM "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/report_history.json"
    click BuildScript1 "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/build.bat"
    click BuildScript2 "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/create_icon.py"
    click ReqWeb "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/requirements.txt"
    click ReqAndroid "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/requirements.txt"
    click Doc1 "https://github.com/0011ashwin/soil-analyzer/blob/main/README.md"
    click Doc2 "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/README.md"
    click Doc3 "https://github.com/0011ashwin/soil-analyzer/blob/main/soil_analyzer/android_app/README.md"
```
