# gabrielhao/city-garden architecture

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

- Interactive diagram: https://gitdiagram.com/gabrielhao/city-garden
- Repository: https://github.com/gabrielhao/city-garden

## Overview

##### Project type and purpose
- City Garden is an AI-powered backend service with a REST API (FastAPI) that analyzes garden conditions and delivers personalized design recommendations and visualizations.

##### File structure
- Top level:
- src/
– main.py: orchestrator entry (if used)
– api.py: FastAPI endpoint definitions
– run_api.py: launches the FastAPI server
– city_garden/: core library
- src/city_garden/
– graph_builder.py: builds the computational graph of steps
– city_garden_nodes.py: node implementations for each pipeline step
– garden_state.py: manages the in-memory state of analysis results
– llm.py: configures OpenAI calls
– services/: adapters to external systems (image loader, content safety, generation)
– tools/: domain-specific utilities (e.g., climate data fetcher)
- tests/: unit tests
- prompts/: various YAML prompts for LLM-driven tasks (relevant to your pipeline but not CORE runtime)

##### README for additional insights
- Technologies: FastAPI, Azure Blob Storage, Azure Content Safety, OpenAI GPT, external Weather API.

##### Detail recommendations
- Edge cases: error paths from Content Safety or generation failures.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External UI"
        UI["UI Client"]:::externalUI
    end

    subgraph "API Layer"
        API["FastAPI Endpoints\n(src/api.py)"]:::api
        Run["Server Launcher\n(src/run_api.py)"]:::api
        Main["Orchestrator Entry\n(src/main.py)"]:::api
    end

    subgraph "Core Services"
        GB["Graph Builder\n(graph_builder.py)"]:::core
        Nodes["Node Implementations\n(city_garden_nodes.py)"]:::core
        State["Garden State\n(garden_state.py)"]:::data
        LLM["LLM Configuration\n(llm.py)"]:::core
    end

    subgraph "Processing Pipeline & Adapters"
        ImgLoader["Image Loader\n(services/image_loader.py)"]:::pipeline
        Safety["Content Safety Checker\n(services/content_safety.py)"]:::pipeline
        ImgGen["Image Generation\n(services/image_generation.py)"]:::pipeline
        Climate["Climate Data Fetcher\n(tools/climate.py)"]:::pipeline
    end

    subgraph "External Systems"
        Blob[(Azure Blob Storage)]:::external
        SafetyAPI["Azure Content Safety API"]:::external
        OpenAIAPI["OpenAI API"]:::external
        WeatherAPI["External Weather API"]:::external
    end

    UI -->|"HTTP Request"| API
    API -->|"invoke"| GB
    GB -->|"builds DAG"| Nodes
    Nodes -->|"reads/writes"| State
    Nodes -->|"uses"| LLM
    Nodes -->|"calls"| ImgLoader
    Nodes -->|"calls"| Safety
    Nodes -->|"calls"| ImgGen
    Nodes -->|"calls"| Climate

    ImgLoader -->|"SDK Call"| Blob
    Safety -->|"HTTP Request"| SafetyAPI
    ImgGen -->|"API Call"| OpenAIAPI
    Climate -->|"HTTP Request"| WeatherAPI

    State -->|"serialize JSON"| API
    API -->|"HTTP Response"| UI

    click API "https://github.com/gabrielhao/city-garden/blob/main/src/api.py"
    click Run "https://github.com/gabrielhao/city-garden/blob/main/src/run_api.py"
    click Main "https://github.com/gabrielhao/city-garden/blob/main/src/main.py"
    click GB "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/graph_builder.py"
    click Nodes "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/city_garden_nodes.py"
    click State "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/garden_state.py"
    click LLM "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/llm.py"
    click ImgLoader "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/services/image_loader.py"
    click Safety "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/services/content_safety.py"
    click ImgGen "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/services/image_generation.py"
    click Climate "https://github.com/gabrielhao/city-garden/blob/main/src/city_garden/tools/climate.py"

    classDef api fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#FFFFE0,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
    classDef data fill:#FFFACD,stroke:#333,stroke-width:1px;
    classDef externalUI fill:#FFE4E1,stroke:#333,stroke-width:1px;
```
