# anjishnum/geode architecture

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

- Interactive diagram: https://gitdiagram.com/anjishnum/geode
- Repository: https://github.com/anjishnum/geode

## Overview

##### Project Type and Purpose
- Geode is a full-stack geospatial question answering agent built with Python and Streamlit.

##### High-Level Component Analysis
- Frontend (app directory)
- app/app.py: Streamlit web interface for user queries and visualization
- app/style.py: UI styling definitions
- Backend Code-Generation Engine (codegen directory)
- generator.py: orchestrates LLM prompting to produce executable Python code
- base_prompt.txt: template prompt guiding code generation
- spec_gen.py: builds function specifications for the LLM
- serve.py: optional HTTP server wrapper around the generator
- Expert Modules (experts directory)
- base.py: abstract expert class and interface
- database_experts.py, functional_experts.py, model_experts.py: concrete expert implementations handling spatial queries, raster/vector operations, ML inference, etc.
- experts/.env: configuration for expert services (API keys, endpoints)
- Scripts (scripts directory)
- launch_v1.py, launch_v2.py: command-line entry points to spin up the system in different modes
- Third-Party Dependencies
- Streamlit: frontend framework
- PyTorch: ML models for specialized reasoning (model_experts)
- GeoPandas, Folium, SciPy, OSM: geospatial data handling and visualization

##### Component Relationships and Data Flows
- User → Streamlit UI: user submits a natural‐language query.
- Streamlit UI → Codegen Engine: query sent to generator or serve endpoint.
- Codegen Engine → LLM: builds prompt (base_prompt.txt + spec_gen) and receives generated Python code.
- Generated Code → Expert Modules: at runtime, calls expert functions (e.g., patch_location_expert, air_quality_expert).
- Expert Modules → External Data: fetch geospatial data from OpenStreetMap, perform raster/vector computations via GeoPandas, SciPy, ML inference via PyTorch.
- Expert Modules → Code Output: produce textual answers and GeoPatch objects.
- Codegen Engine → Streamlit UI: returns answer text and visualization objects.
- Streamlit UI → Browser: displays the answer and interactive map via Folium.

##### Architectural Patterns and Design Principles
- Modular Plugin Architecture: each expert implements a common interface, enabling easy addition of new spatial reasoning capabilities.
- Separation of Concerns: distinct layers for UI, code generation, domain logic, and data retrieval.
- Prompt-Driven Code Generation: decouples high-level queries from low-level implementation by leveraging LLMs.
- Micro-service-style Entry Points: serve.py provides an HTTP API for other systems, while scripts allow CLI invocation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tier
    subgraph "Frontend Tier"
        UI["Streamlit UI"]:::ui
        Style["Style Definitions"]:::ui
        Assets["Static Assets"]:::ui
    end

    %% Backend Tier
    subgraph "Backend Tier"
        Generator["Codegen Generator"]:::engine
        BasePrompt["Base Prompt Template"]:::engine
        SpecGen["Specification Generator"]:::engine
        Serve["HTTP Serve Endpoint"]:::engine
        LLM["LLM Cloud API"]:::external
    end

    %% Domain Logic Tier
    subgraph "Domain Logic Tier"
        BaseExpert["Base Expert Interface"]:::expert
        DBExpert["Database Experts"]:::expert
        FuncExpert["Functional Experts"]:::expert
        ModelExpert["Model Experts"]:::expert
        Env["Expert Config (.env)"]:::expert
    end

    %% External Services/Data Tier
    subgraph "External Services/Data Tier"
        OSM["OpenStreetMap"]:::external
        GeoPandas["GeoPandas/SciPy"]:::external
        MLModels["PyTorch Models"]:::external
    end

    %% Deployment/Launcher Layer
    subgraph "Deployment/Launcher Layer"
        Launch1["Launch v1 CLI"]:::script
        Launch2["Launch v2 CLI"]:::script
        Req["requirements.txt"]:::script
    end

    %% User Interaction
    User["User (Browser)"]:::external

    %% Connections
    User -->|"submits query"| UI
    UI -->|"invoke generate"| Generator
    UI -->|"invoke serve"| Serve
    Serve -->|"forward query"| Generator
    Generator -->|"use prompt"| BasePrompt
    Generator -->|"build specs"| SpecGen
    Generator -->|"call API"| LLM
    Generator -->|"execute code"| DBExpert
    Generator -->|"execute code"| FuncExpert
    Generator -->|"execute code"| ModelExpert
    DBExpert -->|"fetch spatial data"| OSM
    DBExpert -->|"compute raster/vector"| GeoPandas
    FuncExpert -->|"compute operations"| GeoPandas
    ModelExpert -->|"run inference"| MLModels
    DBExpert -->|"return results"| Generator
    FuncExpert -->|"return results"| Generator
    ModelExpert -->|"return results"| Generator
    Generator -->|"return answer & visualization"| UI
    UI -->|"render map"| Browser["Browser Rendering"]:::external

    Launch1 -->|"start app"| Generator
    Launch2 -->|"start app"| Generator
    Req --- Generator

    %% Click Events
    click UI "https://github.com/anjishnum/geode/blob/main/app/app.py"
    click Style "https://github.com/anjishnum/geode/blob/main/app/style.py"
    click Assets "https://github.com/anjishnum/geode/tree/main/assets/"
    click Generator "https://github.com/anjishnum/geode/blob/main/codegen/generator.py"
    click BasePrompt "https://github.com/anjishnum/geode/blob/main/codegen/base_prompt.txt"
    click SpecGen "https://github.com/anjishnum/geode/blob/main/codegen/spec_gen.py"
    click Serve "https://github.com/anjishnum/geode/blob/main/codegen/serve.py"
    click BaseExpert "https://github.com/anjishnum/geode/blob/main/experts/base.py"
    click DBExpert "https://github.com/anjishnum/geode/blob/main/experts/database_experts.py"
    click FuncExpert "https://github.com/anjishnum/geode/blob/main/experts/functional_experts.py"
    click ModelExpert "https://github.com/anjishnum/geode/blob/main/experts/model_experts.py"
    click Env "https://github.com/anjishnum/geode/blob/main/experts/.env"
    click Launch1 "https://github.com/anjishnum/geode/blob/main/scripts/launch_v1.py"
    click Launch2 "https://github.com/anjishnum/geode/blob/main/scripts/launch_v2.py"
    click Req "https://github.com/anjishnum/geode/blob/main/requirements.txt"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#3498DB,color:#0B3D91,stroke-width:1px;
    classDef engine fill:#A9DFBF,stroke:#27AE60,color:#145A32,stroke-width:1px;
    classDef expert fill:#F9E79F,stroke:#F1C40F,color:#7D6608,stroke-width:1px;
    classDef external fill:#D5D8DC,stroke:#566573,color:#2C3E50,stroke-width:1px,stroke-dasharray: 2 2;
    classDef script fill:#E8DAEF,stroke:#9B59B6,color:#4A235A,stroke-width:1px;
```
