# dingshandeng/askabird architecture

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

- Interactive diagram: https://gitdiagram.com/dingshandeng/askabird
- Repository: https://github.com/dingshandeng/askabird

## Overview

AskABird is a Tucson-focused biodiversity app whose main workflow lets a visitor explore a map, ask a local bird about a location, assess a proposed construction site, find safer alternatives, and generate an impact report. The current React app delegates these capabilities to Supabase Edge Functions, which use eBird data, shared scoring logic, Gemini, and Supabase services. The README documents capabilities whose frontend wiring is not shown in excerpts; those links are marked dashed. The Python backend is retained as a separate legacy implementation, not presumed to power the current app.

Main entry points: [`app/src/App.tsx`](https://github.com/dingshandeng/askabird/blob/main/app/src/App.tsx) (Route shell), [`app/src/pages/Index.tsx`](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Index.tsx) (Bird map), [`app/src/pages/Optimize.tsx`](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Optimize.tsx) (Site optimizer), [`app/supabase/functions/region-biodiversity/index.ts`](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/region-biodiversity/index.ts) (Regional biodiversity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_app["Route shell<br/>[App.tsx]"]
  node_explore["Bird map<br/>[Index.tsx]"]
  node_mapview["Map display<br/>[MapView.tsx]"]
  node_chatui["Bird chat<br/>[BirdChat.tsx]"]
  node_optimize["Site optimizer<br/>[Optimize.tsx]"]
  node_impact["Impact results<br/>[ImpactResult.tsx]"]
  node_reportui["Site report<br/>[Report.tsx]"]
  node_story["Our story<br/>[OurStory.tsx]"]
  node_authui["Authentication<br/>[Auth.tsx]"]
end

subgraph group_edge["Edge services"]
  node_analyze["Site analysis<br/>[index.ts]"]
  node_scoring["Biodiversity scoring<br/>[biodiversity.ts]"]
  node_alternatives["Safer alternatives<br/>[index.ts]"]
  node_birdchatfn["Bird response<br/>[index.ts]"]
  node_nearby["Nearby species<br/>[index.ts]"]
  node_regional["Regional biodiversity<br/>[index.ts]"]
  node_reportfn["Report generation<br/>[index.ts]"]
end

subgraph group_data["Data and integrations"]
  node_ebird{{"eBird API"}}
  node_gemini{{"Gemini API"}}
  node_supabase[("Supabase services<br/>[client.ts]")]
end

subgraph group_legacy["Legacy backend"]
  node_legacyapi["Legacy API<br/>[main.py]"]
  node_legacyml["Legacy impact model<br/>[ml_model.py]"]
  node_legacyingest["Legacy data ingestion<br/>[data_ingestion.py]"]
  node_legacygrid["Legacy species grid<br/>[species_grid.py]"]
  node_legacydata["Synthetic data<br/>[mock_data.py]"]
end

node_visitor(("Visitor"))

node_visitor -->|"opens app"| node_app
node_app -->|"routes to"| node_explore
node_app -->|"routes to"| node_authui
node_app -->|"routes to"| node_optimize
node_app -->|"routes to"| node_reportui
node_app -->|"routes to"| node_story
node_explore -.->|"shows map"| node_mapview
node_explore -.->|"opens chat"| node_chatui
node_chatui -.->|"requests reply"| node_birdchatfn
node_birdchatfn -.->|"generates response"| node_gemini
node_optimize -.->|"requests score"| node_analyze
node_analyze -->|"uses scoring"| node_scoring
node_optimize -.->|"requests options"| node_alternatives
node_alternatives -->|"uses scoring"| node_scoring
node_optimize -.->|"shows results"| node_impact
node_reportui -.->|"requests report"| node_reportfn
node_reportfn -.->|"writes report"| node_gemini
node_explore -.->|"loads heatmap"| node_regional
node_explore -.->|"looks up birds"| node_nearby
node_nearby -.->|"fetches sightings"| node_ebird
node_regional -.->|"fetches observations"| node_ebird
node_regional -->|"reads cache"| node_supabase
node_authui -.->|"uses auth"| node_supabase
node_legacyapi -->|"predicts impact"| node_legacyml
node_legacyingest -->|"fetches sightings"| node_ebird
node_legacygrid -.->|"uses sightings"| node_legacyingest
node_legacyml -.->|"uses data"| node_legacyingest
node_legacyml -.->|"uses fallback"| node_legacydata

click node_app "https://github.com/dingshandeng/askabird/blob/main/app/src/App.tsx"
click node_explore "https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Index.tsx"
click node_mapview "https://github.com/dingshandeng/askabird/blob/main/app/src/components/MapView.tsx"
click node_chatui "https://github.com/dingshandeng/askabird/blob/main/app/src/components/BirdChat.tsx"
click node_optimize "https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Optimize.tsx"
click node_impact "https://github.com/dingshandeng/askabird/blob/main/app/src/components/ImpactResult.tsx"
click node_reportui "https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Report.tsx"
click node_story "https://github.com/dingshandeng/askabird/blob/main/app/src/pages/OurStory.tsx"
click node_authui "https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Auth.tsx"
click node_analyze "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/analyze-site/index.ts"
click node_scoring "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/_shared/biodiversity.ts"
click node_alternatives "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/suggest-alternatives/index.ts"
click node_birdchatfn "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/bird-chat/index.ts"
click node_nearby "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/nearby-birds/index.ts"
click node_regional "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/region-biodiversity/index.ts"
click node_reportfn "https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/generate-report/index.ts"
click node_supabase "https://github.com/dingshandeng/askabird/blob/main/app/src/integrations/supabase/client.ts"
click node_legacyapi "https://github.com/dingshandeng/askabird/blob/main/archive/backend/main.py"
click node_legacyml "https://github.com/dingshandeng/askabird/blob/main/archive/backend/ml_model.py"
click node_legacyingest "https://github.com/dingshandeng/askabird/blob/main/archive/backend/data_ingestion.py"
click node_legacygrid "https://github.com/dingshandeng/askabird/blob/main/archive/backend/species_grid.py"
click node_legacydata "https://github.com/dingshandeng/askabird/blob/main/archive/backend/mock_data.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_app,node_explore,node_mapview,node_chatui,node_optimize,node_impact,node_reportui,node_story,node_authui toneBlue
class node_analyze,node_scoring,node_alternatives,node_birdchatfn,node_nearby,node_regional,node_reportfn toneAmber
class node_ebird,node_gemini,node_supabase toneMint
class node_legacyapi,node_legacyml,node_legacyingest,node_legacygrid,node_legacydata toneRose
class node_visitor toneIndigo
```

## Components

### Web experience

- [Route shell](https://github.com/dingshandeng/askabird/blob/main/app/src/App.tsx): `app/src/App.tsx`
- [Bird map](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Index.tsx): `app/src/pages/Index.tsx`
- [Map display](https://github.com/dingshandeng/askabird/blob/main/app/src/components/MapView.tsx): `app/src/components/MapView.tsx`
- [Bird chat](https://github.com/dingshandeng/askabird/blob/main/app/src/components/BirdChat.tsx): `app/src/components/BirdChat.tsx`
- [Site optimizer](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Optimize.tsx): `app/src/pages/Optimize.tsx`
- [Impact results](https://github.com/dingshandeng/askabird/blob/main/app/src/components/ImpactResult.tsx): `app/src/components/ImpactResult.tsx`
- [Site report](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Report.tsx): `app/src/pages/Report.tsx`
- [Our story](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/OurStory.tsx): `app/src/pages/OurStory.tsx`
- [Authentication](https://github.com/dingshandeng/askabird/blob/main/app/src/pages/Auth.tsx): `app/src/pages/Auth.tsx`

### Edge services

- [Site analysis](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/analyze-site/index.ts): `app/supabase/functions/analyze-site/index.ts`
- [Biodiversity scoring](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/_shared/biodiversity.ts): `app/supabase/functions/_shared/biodiversity.ts`
- [Safer alternatives](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/suggest-alternatives/index.ts): `app/supabase/functions/suggest-alternatives/index.ts`
- [Bird response](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/bird-chat/index.ts): `app/supabase/functions/bird-chat/index.ts`
- [Nearby species](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/nearby-birds/index.ts): `app/supabase/functions/nearby-birds/index.ts`
- [Regional biodiversity](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/region-biodiversity/index.ts): `app/supabase/functions/region-biodiversity/index.ts`
- [Report generation](https://github.com/dingshandeng/askabird/blob/main/app/supabase/functions/generate-report/index.ts): `app/supabase/functions/generate-report/index.ts`

### Data and integrations

- **eBird API**
- **Gemini API**
- [Supabase services](https://github.com/dingshandeng/askabird/blob/main/app/src/integrations/supabase/client.ts): `app/src/integrations/supabase/client.ts`

### Legacy backend

- [Legacy API](https://github.com/dingshandeng/askabird/blob/main/archive/backend/main.py): `archive/backend/main.py`
- [Legacy impact model](https://github.com/dingshandeng/askabird/blob/main/archive/backend/ml_model.py): `archive/backend/ml_model.py`
- [Legacy data ingestion](https://github.com/dingshandeng/askabird/blob/main/archive/backend/data_ingestion.py): `archive/backend/data_ingestion.py`
- [Legacy species grid](https://github.com/dingshandeng/askabird/blob/main/archive/backend/species_grid.py): `archive/backend/species_grid.py`
- [Synthetic data](https://github.com/dingshandeng/askabird/blob/main/archive/backend/mock_data.py): `archive/backend/mock_data.py`

### Other components

- **Visitor**

## Connections

- Visitor → Route shell: opens app (evidence: `app/src/App.tsx`)
- Route shell → Bird map: routes to (evidence: `app/src/App.tsx`)
- Route shell → Authentication: routes to (evidence: `app/src/App.tsx`)
- Route shell → Site optimizer: routes to (evidence: `app/src/App.tsx`)
- Route shell → Site report: routes to (evidence: `app/src/App.tsx`)
- Route shell → Our story: routes to (evidence: `app/src/App.tsx`)
- Bird map → Map display: shows map
- Bird map → Bird chat: opens chat
- Bird chat → Bird response: requests reply
- Bird response → Gemini API: generates response
- Site optimizer → Site analysis: requests score
- Site analysis → Biodiversity scoring: uses scoring (evidence: `app/supabase/functions/analyze-site/index.ts`)
- Site optimizer → Safer alternatives: requests options
- Safer alternatives → Biodiversity scoring: uses scoring (evidence: `app/supabase/functions/suggest-alternatives/index.ts`)
- Site optimizer → Impact results: shows results
- Site report → Report generation: requests report
- Report generation → Gemini API: writes report
- Bird map → Regional biodiversity: loads heatmap
- Bird map → Nearby species: looks up birds
- Nearby species → eBird API: fetches sightings
- Regional biodiversity → eBird API: fetches observations
- Regional biodiversity → Supabase services: reads cache (evidence: `app/supabase/functions/region-biodiversity/index.ts`)
- Authentication → Supabase services: uses auth
- Legacy API → Legacy impact model: predicts impact (evidence: `archive/backend/main.py`)
- Legacy data ingestion → eBird API: fetches sightings (evidence: `archive/backend/data_ingestion.py`)
- Legacy species grid → Legacy data ingestion: uses sightings (evidence: `archive/backend/species_grid.py`)
- Legacy impact model → Legacy data ingestion: uses data (evidence: `archive/backend/ml_model.py`)
- Legacy impact model → Synthetic data: uses fallback (evidence: `archive/backend/ml_model.py`)
