# drotschie/ai-agent-challenge architecture

> Architecture diagram of the GitHub repository drotschie/ai-agent-challenge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/drotschie/ai-agent-challenge
- Repository: https://github.com/drotschie/ai-agent-challenge

## Overview

This is a gardening guidance and planting-record verification application. Gardeners ask locally grounded crop, soil and watering questions, or submit planting records for cleanup and agronomic validation. The guide path rewrites queries, retrieves structured references and synthesizes cited advice with weather; the verification path ingests calendar and email data, normalizes records, checks rules and produces an audited CSV. The graph follows documented capabilities and sampled calls; some frontend-to-API and external-service links are documented rather than visible in backend excerpts.

Main entry points: [`backend/app/rag/pipeline.py`](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/pipeline.py) (Grounded synthesis), [`backend/app/agent/graph.py`](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/graph.py) (Workflow orchestration), [`backend/app/main.py`](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/agent/verifier.py`](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/verifier.py) (Rule verification)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Gardener interface"]
  node_guide_ui["Guide workspace<br/>[RagWorkspace.tsx]"]
  node_agent_ui["Verification workspace<br/>[AgentWorkspace.tsx]"]
  node_data_ui["Data explorer<br/>[DataExplorer.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_service["Application API"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_config["LLM configuration<br/>[config.py]"]
end

subgraph group_guide["Gardening guide"]
  node_rag_query["Query transform<br/>[query_transform.py]"]
  node_rag_pipeline["Grounded synthesis<br/>[pipeline.py]"]
  node_chunkers["Source chunking<br/>[chunkers.py]"]
  node_vector[("Vector retrieval<br/>[vector_store.py]")]
  node_rag_schemas["Guide data models<br/>[schemas.py]"]
  node_garden_data["Garden references"]
end

subgraph group_verification["Planting verification"]
  node_agent_graph["Workflow orchestration<br/>[graph.py]"]
  node_calendar["Calendar ingestion<br/>[calendar_tool.py]"]
  node_email["Email ingestion<br/>[email_tool.py]"]
  node_normalizer["Record cleanup<br/>[normalizer.py]"]
  node_verifier["Rule verification<br/>[verifier.py]"]
  node_agent_schemas["Agent data models<br/>[schemas.py]"]
  node_gbif["Taxonomy lookup<br/>[gbif_tool.py]"]
  node_weather["Weather lookup<br/>[weather_tool.py]"]
end

node_gardener(("Gardener"))
node_google["Google Calendar"]
node_gmail["Gmail"]
node_openmeteo["Open-Meteo"]
node_gbif_service["GBIF API"]
node_llm["LLM providers"]

node_gardener -->|"asks"| node_guide_ui
node_gardener -->|"runs verification"| node_agent_ui
node_gardener -->|"browses sources"| node_data_ui
node_guide_ui -.->|"submits query"| node_api_client
node_agent_ui -.->|"starts workflow"| node_api_client
node_data_ui -.->|"requests sources"| node_api_client
node_api_client -.->|"calls routes"| node_api
node_api -->|"runs query"| node_rag_pipeline
node_api -->|"runs workflow"| node_agent_graph
node_api -->|"loads source data"| node_garden_data
node_rag_pipeline -->|"transforms query"| node_rag_query
node_rag_pipeline -->|"retrieves chunks"| node_vector
node_vector -->|"indexes chunks"| node_chunkers
node_chunkers -->|"parses references"| node_garden_data
node_rag_pipeline -->|"uses agronomic rules"| node_garden_data
node_rag_pipeline -->|"fetches forecast"| node_openmeteo
node_rag_pipeline -->|"uses synthesis fallback"| node_config
node_config -.->|"invokes providers"| node_llm
node_agent_graph -->|"fetches events"| node_calendar
node_agent_graph -->|"fetches messages"| node_email
node_agent_graph -->|"cleans records"| node_normalizer
node_agent_graph -->|"validates records"| node_verifier
node_calendar -.->|"reads events"| node_google
node_email -.->|"reads messages"| node_gmail
node_verifier -->|"checks taxonomy"| node_gbif
node_verifier -->|"checks forecast"| node_weather
node_gbif -.->|"matches species"| node_gbif_service
node_weather -.->|"gets forecast"| node_openmeteo
node_verifier -->|"checks crop rules"| node_garden_data
node_agent_graph -.->|"returns audit and CSV"| node_agent_ui

click node_guide_ui "https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/RagWorkspace.tsx"
click node_agent_ui "https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/AgentWorkspace.tsx"
click node_data_ui "https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/DataExplorer.tsx"
click node_api_client "https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/main.py"
click node_rag_query "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/query_transform.py"
click node_rag_pipeline "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/pipeline.py"
click node_chunkers "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/chunkers.py"
click node_vector "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/vector_store.py"
click node_rag_schemas "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/schemas.py"
click node_garden_data "https://github.com/drotschie/ai-agent-challenge/tree/main/backend/data"
click node_config "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/config.py"
click node_agent_graph "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/graph.py"
click node_calendar "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/calendar_tool.py"
click node_email "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/email_tool.py"
click node_normalizer "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/normalizer.py"
click node_verifier "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/verifier.py"
click node_agent_schemas "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/schemas.py"
click node_gbif "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/gbif_tool.py"
click node_weather "https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/weather_tool.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_guide_ui,node_agent_ui,node_data_ui,node_api_client toneBlue
class node_api,node_config toneAmber
class node_rag_query,node_rag_pipeline,node_chunkers,node_vector,node_rag_schemas,node_garden_data,node_gbif_service toneMint
class node_agent_graph,node_calendar,node_email,node_normalizer,node_verifier,node_agent_schemas,node_gbif,node_weather toneRose
class node_gardener,node_google,node_gmail,node_openmeteo,node_llm toneIndigo
```

## Components

### Gardener interface

- [Guide workspace](https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/RagWorkspace.tsx): `frontend/src/components/RagWorkspace.tsx`
- [Verification workspace](https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/AgentWorkspace.tsx): `frontend/src/components/AgentWorkspace.tsx`
- [Data explorer](https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/components/DataExplorer.tsx): `frontend/src/components/DataExplorer.tsx`
- [API client](https://github.com/drotschie/ai-agent-challenge/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Application API

- [FastAPI routes](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/main.py): `backend/app/main.py`
- [LLM configuration](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/config.py): `backend/app/config.py`

### Gardening guide

- [Query transform](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/query_transform.py): `backend/app/rag/query_transform.py`
- [Grounded synthesis](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/pipeline.py): `backend/app/rag/pipeline.py`
- [Source chunking](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/chunkers.py): `backend/app/rag/chunkers.py`
- [Vector retrieval](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/vector_store.py): `backend/app/rag/vector_store.py`
- [Guide data models](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/rag/schemas.py): `backend/app/rag/schemas.py`
- [Garden references](https://github.com/drotschie/ai-agent-challenge/tree/main/backend/data): `backend/data`

### Planting verification

- [Workflow orchestration](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/graph.py): `backend/app/agent/graph.py`
- [Calendar ingestion](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/calendar_tool.py): `backend/app/agent/tools/calendar_tool.py`
- [Email ingestion](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/email_tool.py): `backend/app/agent/tools/email_tool.py`
- [Record cleanup](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/normalizer.py): `backend/app/agent/normalizer.py`
- [Rule verification](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/verifier.py): `backend/app/agent/verifier.py`
- [Agent data models](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/schemas.py): `backend/app/agent/schemas.py`
- [Taxonomy lookup](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/gbif_tool.py): `backend/app/agent/tools/gbif_tool.py`
- [Weather lookup](https://github.com/drotschie/ai-agent-challenge/blob/main/backend/app/agent/tools/weather_tool.py): `backend/app/agent/tools/weather_tool.py`

### Other components

- **Gardener**
- **Google Calendar**
- **Gmail**
- **Open-Meteo**
- **GBIF API**
- **LLM providers**

## Connections

- Gardener → Guide workspace: asks (evidence: `README.md`)
- Gardener → Verification workspace: runs verification (evidence: `README.md`)
- Gardener → Data explorer: browses sources (evidence: `README.md`)
- Guide workspace → API client: submits query
- Verification workspace → API client: starts workflow
- Data explorer → API client: requests sources
- API client → FastAPI routes: calls routes
- FastAPI routes → Grounded synthesis: runs query (evidence: `backend/app/main.py`)
- FastAPI routes → Workflow orchestration: runs workflow (evidence: `backend/app/main.py`)
- FastAPI routes → Garden references: loads source data (evidence: `backend/app/main.py`)
- Grounded synthesis → Query transform: transforms query (evidence: `backend/app/rag/pipeline.py`)
- Grounded synthesis → Vector retrieval: retrieves chunks (evidence: `backend/app/rag/pipeline.py`)
- Vector retrieval → Source chunking: indexes chunks (evidence: `backend/app/rag/vector_store.py`)
- Source chunking → Garden references: parses references (evidence: `README.md`)
- Grounded synthesis → Garden references: uses agronomic rules (evidence: `README.md`)
- Grounded synthesis → Open-Meteo: fetches forecast (evidence: `README.md`)
- Grounded synthesis → LLM configuration: uses synthesis fallback (evidence: `backend/app/rag/pipeline.py`)
- LLM configuration → LLM providers: invokes providers (evidence: `backend/app/config.py`)
- Workflow orchestration → Calendar ingestion: fetches events (evidence: `backend/app/agent/graph.py`)
- Workflow orchestration → Email ingestion: fetches messages (evidence: `backend/app/agent/graph.py`)
- Workflow orchestration → Record cleanup: cleans records (evidence: `backend/app/agent/graph.py`)
- Workflow orchestration → Rule verification: validates records (evidence: `backend/app/agent/graph.py`)
- Calendar ingestion → Google Calendar: reads events (evidence: `backend/app/agent/tools/calendar_tool.py`)
- Email ingestion → Gmail: reads messages (evidence: `backend/app/agent/tools/email_tool.py`)
- Rule verification → Taxonomy lookup: checks taxonomy (evidence: `backend/app/agent/verifier.py`)
- Rule verification → Weather lookup: checks forecast (evidence: `backend/app/agent/verifier.py`)
- Taxonomy lookup → GBIF API: matches species (evidence: `README.md`)
- Weather lookup → Open-Meteo: gets forecast (evidence: `README.md`)
- Rule verification → Garden references: checks crop rules (evidence: `README.md`)
- Workflow orchestration → Verification workspace: returns audit and CSV