# cashewdevs/faunawatch architecture

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

- Interactive diagram: https://gitdiagram.com/cashewdevs/faunawatch
- Repository: https://github.com/cashewdevs/faunawatch

## Overview

FaunaWatch is a Flutter wildlife-reporting and community app with AI-assisted species identification, location-aware reporting, social discovery, and push notifications. The broad user journey spans account access, creating or identifying a wildlife report, and viewing community activity; the tree also shows messaging, profiles, and monitoring features. The map, OAuth, and push setup are documented, but most Dart implementation was not sampled, so those internal connections are shown only where the README supports them or are omitted. The sampled push function has explicit webhook, database, and FCM interactions.

Main entry points: [`supabase/functions/send-push/index.ts`](https://github.com/cashewdevs/faunawatch/blob/main/supabase/functions/send-push/index.ts) (Notification webhook), [`lib/app.dart`](https://github.com/cashewdevs/faunawatch/blob/main/lib/app.dart) (FaunaWatch app), [`lib/features/create_post/services/create_post_service.dart`](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/create_post/services/create_post_service.dart) (Create report), [`lib/features/community_map/services/mapbox_map_service.dart`](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/community_map/services/mapbox_map_service.dart) (Community map)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Flutter application"]
  node_flutter_app["FaunaWatch app<br/>[app.dart]"]
end

subgraph group_community["Community and reports"]
  node_feed["For You feed<br/>[feed_service.dart]"]
  node_gallery["Public galleries"]
  node_messages["Direct messages"]
  node_create_report["Create report"]
  node_map["Community map"]
  node_report_detail["Report details"]
end

subgraph group_wildlife["Wildlife tools"]
  node_lens["Fauna Lens"]
  node_ai_client["AI vision clients"]
  node_fauna_guard["Fauna Guard"]
end

subgraph group_identity["Identity and profiles"]
  node_auth["Sign-in and registration<br/>[auth_service.dart]"]
  node_profile_setup["Profile setup"]
  node_public_profile["Public profiles"]
end

subgraph group_push["Push delivery"]
  node_notifications["In-app notifications"]
  node_push_client["Device push services"]
  node_webhook["Notification webhook<br/>[index.ts]"]
  node_push_logic["Push message rules<br/>[logic.ts]"]
end

node_person(("App user"))
node_supabase[("Supabase")]
node_fcm["Firebase Cloud Messaging"]
node_mapbox["Mapbox"]

node_person -.->|"uses"| node_flutter_app
node_flutter_app -.->|"offers access"| node_auth
node_auth -->|"OAuth"| node_supabase
node_person -.->|"submits sighting"| node_create_report
node_create_report -.->|"selects location"| node_map
node_map -->|"renders map"| node_mapbox
node_person -.->|"identifies species"| node_lens
node_lens -.->|"requests analysis"| node_ai_client
node_person -.->|"browses reports"| node_feed
node_person -->|"views gallery"| node_gallery
node_person -->|"opens profile"| node_public_profile
node_person -.->|"sends messages"| node_messages
node_person -.->|"uses monitoring"| node_fauna_guard
node_notifications -.->|"shows updates"| node_person
node_push_client -->|"registers device token"| node_supabase
node_supabase -->|"posts notification event"| node_webhook
node_webhook -->|"checks and builds"| node_push_logic
node_webhook -->|"checks suspension; reads tokens"| node_supabase
node_webhook -->|"sends push"| node_fcm
node_webhook -->|"deletes invalid tokens"| node_supabase

click node_flutter_app "https://github.com/cashewdevs/faunawatch/blob/main/lib/app.dart"
click node_auth "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/auth/services/auth_service.dart"
click node_profile_setup "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/profile_customization/services/profile_service.dart"
click node_public_profile "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/public_profile/services/public_profile_service.dart"
click node_feed "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/feed/services/feed_service.dart"
click node_gallery "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/gallery/services/gallery_service.dart"
click node_messages "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/messages/services/messages_service.dart"
click node_create_report "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/create_post/services/create_post_service.dart"
click node_map "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/community_map/services/mapbox_map_service.dart"
click node_report_detail "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/report_detail/services/report_detail_service.dart"
click node_lens "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/fauna_lens/services/species_identification_service.dart"
click node_ai_client "https://github.com/cashewdevs/faunawatch/blob/main/lib/core/services/ai/ai_vision_client.dart"
click node_fauna_guard "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/fauna_guard/services/guard_location_service.dart"
click node_notifications "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/notifications/services/notifications_service.dart"
click node_push_client "https://github.com/cashewdevs/faunawatch/blob/main/lib/features/push/services/push_messaging_service.dart"
click node_webhook "https://github.com/cashewdevs/faunawatch/blob/main/supabase/functions/send-push/index.ts"
click node_push_logic "https://github.com/cashewdevs/faunawatch/blob/main/supabase/functions/send-push/logic.ts"

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_flutter_app,node_person toneBlue
class node_feed,node_gallery,node_messages,node_create_report,node_map,node_report_detail,node_supabase toneAmber
class node_lens,node_ai_client,node_fauna_guard toneMint
class node_auth,node_profile_setup,node_public_profile toneRose
class node_notifications,node_push_client,node_webhook,node_push_logic,node_fcm,node_mapbox toneIndigo
```

## Components

### Flutter application

- [FaunaWatch app](https://github.com/cashewdevs/faunawatch/blob/main/lib/app.dart): `lib/app.dart`

### Community and reports

- [For You feed](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/feed/services/feed_service.dart): `lib/features/feed/services/feed_service.dart`
- [Public galleries](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/gallery/services/gallery_service.dart): `lib/features/gallery/services/gallery_service.dart`
- [Direct messages](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/messages/services/messages_service.dart): `lib/features/messages/services/messages_service.dart`
- [Create report](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/create_post/services/create_post_service.dart): `lib/features/create_post/services/create_post_service.dart`
- [Community map](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/community_map/services/mapbox_map_service.dart): `lib/features/community_map/services/mapbox_map_service.dart`
- [Report details](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/report_detail/services/report_detail_service.dart): `lib/features/report_detail/services/report_detail_service.dart`

### Wildlife tools

- [Fauna Lens](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/fauna_lens/services/species_identification_service.dart): `lib/features/fauna_lens/services/species_identification_service.dart`
- [AI vision clients](https://github.com/cashewdevs/faunawatch/blob/main/lib/core/services/ai/ai_vision_client.dart): `lib/core/services/ai/ai_vision_client.dart`
- [Fauna Guard](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/fauna_guard/services/guard_location_service.dart): `lib/features/fauna_guard/services/guard_location_service.dart`

### Identity and profiles

- [Sign-in and registration](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/auth/services/auth_service.dart): `lib/features/auth/services/auth_service.dart`
- [Profile setup](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/profile_customization/services/profile_service.dart): `lib/features/profile_customization/services/profile_service.dart`
- [Public profiles](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/public_profile/services/public_profile_service.dart): `lib/features/public_profile/services/public_profile_service.dart`

### Push delivery

- [In-app notifications](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/notifications/services/notifications_service.dart): `lib/features/notifications/services/notifications_service.dart`
- [Device push services](https://github.com/cashewdevs/faunawatch/blob/main/lib/features/push/services/push_messaging_service.dart): `lib/features/push/services/push_messaging_service.dart`
- [Notification webhook](https://github.com/cashewdevs/faunawatch/blob/main/supabase/functions/send-push/index.ts): `supabase/functions/send-push/index.ts`
- [Push message rules](https://github.com/cashewdevs/faunawatch/blob/main/supabase/functions/send-push/logic.ts): `supabase/functions/send-push/logic.ts`

### Other components

- **App user**
- **Supabase**
- **Firebase Cloud Messaging**
- **Mapbox**

## Connections

- App user → FaunaWatch app: uses
- FaunaWatch app → Sign-in and registration: offers access
- Sign-in and registration → Supabase: OAuth (evidence: `README.md`)
- App user → Create report: submits sighting
- Create report → Community map: selects location
- Community map → Mapbox: renders map (evidence: `README.md`)
- App user → Fauna Lens: identifies species
- Fauna Lens → AI vision clients: requests analysis
- App user → For You feed: browses reports
- App user → Public galleries: views gallery (evidence: `README.md`)
- App user → Public profiles: opens profile (evidence: `README.md`)
- App user → Direct messages: sends messages
- App user → Fauna Guard: uses monitoring
- In-app notifications → App user: shows updates
- Device push services → Supabase: registers device token (evidence: `README.md`)
- Supabase → Notification webhook: posts notification event (evidence: `README.md`)
- Notification webhook → Push message rules: checks and builds (evidence: `supabase/functions/send-push/index.ts`)
- Notification webhook → Supabase: checks suspension; reads tokens (evidence: `supabase/functions/send-push/index.ts`)
- Notification webhook → Firebase Cloud Messaging: sends push (evidence: `supabase/functions/send-push/index.ts`)
- Notification webhook → Supabase: deletes invalid tokens (evidence: `supabase/functions/send-push/index.ts`)
