Architecture

Overview

FloraScout is a mobile-first gardening system built around an Expo React Native client, a Supabase backend, and a server-side AI layer implemented as Supabase Edge Functions.

The architecture optimizes for four things:

• fast iteration through OTA-capable JavaScript changes
• server-side control over AI, credits, and external APIs
• clear domain ownership between client services, database tables, and edge functions
• real-world resilience for auth, image handling, retries, and partial failures

System Context

flowchart LR
  User["Gardener"] --> App["Expo / React Native app"]
  App --> Auth["Supabase Auth"]
  App --> DB["Supabase Postgres"]
  App --> Storage["Supabase Storage"]
  App --> Edge["Supabase Edge Functions"]
  App --> Sentry["Sentry"]
  Edge --> OpenAI["OpenAI models"]
  Edge --> Weather["OpenWeather API"]
  Edge --> RevenueCat["RevenueCat webhooks and SDK"]
  DB --> Views["Views / RPCs / RLS"]

Architectural Shape

Client

• React Native 0.81 with Expo SDK 54
• JavaScript application code
• contexts/ for session and app-wide state
• screens/ for route-level views
• components/ for reusable UI pieces
• services/ as the main business-logic seam
• theme/ as the design-system source of truth

Server

• Supabase Postgres as system of record
• Supabase Auth for identity
• Supabase Storage for plant images and media
• Edge Functions in TypeScript for AI, weather proxying, legal endpoints, and webhook handling

External integrations

• OpenAI for plant scan, plant details, health check, assistant chat, and avatar generation
• RevenueCat for subscriptions and one-time credit packs
• OpenWeather for weather-derived care context
• Sentry for crash and error monitoring

Repository Map

Runtime Layers

1. Presentation layer

The presentation layer lives in screens/ and components/.

Responsibilities:

• render data and interaction states
• route users across the core loops
• delegate side effects to services
• stay visually consistent through the design system

2. Application-service layer

The service layer in services/ is the main client-side orchestration boundary.

Examples:

• aiService.js invokes Edge Functions with auth and error normalization
• plantService.js, diaryService.js, and taskService.js map app actions to database writes
• dexService.js and discoveryService.js shape collection mechanics
• creditService.js, purchaseService.js, and pricingConfig.js define the monetization flow
• notificationService.js and weatherService.js bridge native/platform APIs and server data

3. Platform and infrastructure layer

This layer includes:

• Supabase client setup in supabase.js
• Auth session persistence with AsyncStorage
• push notifications
• maps
• image upload and signed URL resolution
• EAS update and store build workflows

Navigation Topology

The app is organized around a small number of tab-level entry points with nested stacks.

flowchart TD
  App["App.js"] --> Home["Home stack"]
  App --> Plants["Plant stack"]
  App --> Add["Add Plant stack"]
  App --> Assistant["Assistant stack"]
  App --> More["More stack"]

  Plants --> PlantList["Plant list"]
  Plants --> PlantDetail["Plant detail"]
  Plants --> PlantDex["Plant Dex"]
  Plants --> DexDetail["Dex detail"]

  More --> Tasks["Tasks"]
  More --> Store["Store"]
  More --> Leaderboard["Leaderboard"]
  More --> Calendar["Calendar"]
  More --> Feedback["Feedback"]
  More --> Settings["Settings"]
  More --> Admin["Admin dashboard"]

Primary Runtime Flows

Scan, identify, save, discover

sequenceDiagram
  participant U as User
  participant A as AddPlantScreen
  participant AI as aiService
  participant EF as ai-plant-scan
  participant DB as Supabase DB
  participant DX as discoveryService

  U->>A: Take plant photo
  A->>AI: recognizePlant(base64, language)
  AI->>EF: Invoke edge function with auth
  EF-->>AI: name, note, plant_type
  AI-->>A: normalized scan result
  A->>DB: save plant row
  A->>DX: log discovery
  DX->>DB: upsert species and insert discovery event
  DB-->>DX: species id, counters, first-discovery status
  DX-->>A: discovery metadata
  A-->>U: reveal modal and saved plant

Health check and diary loop

sequenceDiagram
  participant U as User
  participant P as PlantDetailScreen
  participant AI as aiService
  participant EF as ai-healthcheck
  participant DB as Supabase DB

  U->>P: Run health check
  P->>AI: performHealthcheck(image_url, plant_name, language)
  AI->>EF: Authenticated edge invocation
  EF-->>AI: healthscore and recommendations
  AI-->>P: parsed health result
  P->>DB: insert plant_healthchecks
  P->>DB: insert gardening_events and diary entry
  P-->>U: updated score and history

Assistant loop

The assistant is intentionally not a free-form black box.

• the client sends text and optional image context
• chat history is loaded server-side
• the edge layer can decide on function calls and structured actions
• usage is credit-metered and logged

Data Model

The schema has grown from a simple plant/task core into a multi-loop domain model.

erDiagram
  profiles ||--o{ plants : owns
  profiles ||--o{ tasks : owns
  profiles ||--o{ messages : writes
  profiles ||--|| credit_balances : has
  profiles ||--o{ usage_log : generates
  profiles ||--o{ transactions : receives
  profiles ||--o{ subscriptions : maintains
  profiles ||--o{ discovery_events : creates
  profiles ||--o{ gardening_events : creates
  profiles ||--o{ locations : owns

  locations ||--o{ zones : contains
  zones ||--o{ plants : groups

  plants ||--o{ tasks : drives
  plants ||--o{ plant_healthchecks : collects
  plants ||--o{ plant_diary : records

  species ||--o{ discovery_events : referenced_by
  species ||--o{ species_details : cached_as

  profiles {
    uuid id PK
    text username
    text language
    boolean is_admin
  }
  plants {
    uuid id PK
    uuid user_id FK
    uuid zone_id FK
    text name
    jsonb details
    uuid species_id
  }
  tasks {
    uuid id PK
    uuid user_id FK
    uuid plant_id FK
    text type
    timestamptz due_at
    text state
  }
  plant_diary {
    uuid id PK
    uuid plant_id FK
    text type
    text image_url
  }
  plant_healthchecks {
    uuid id PK
    uuid plant_id FK
    integer healthscore
  }
  species {
    uuid id PK
    text canonical_name
    text plant_type
    integer total_discoverers
  }
  species_details {
    uuid species_id FK
    text language
    jsonb details
  }
  discovery_events {
    uuid id PK
    uuid user_id FK
    uuid species_id FK
    boolean is_first
  }
  gardening_events {
    uuid id PK
    uuid user_id FK
    text event_type
    numeric points
  }
  credit_balances {
    uuid user_id PK
    integer balance
  }
  subscriptions {
    uuid id PK
    uuid user_id FK
    text product_id
    text status
  }
  locations {
    uuid id PK
    uuid user_id FK
    text name
  }
  zones {
    uuid id PK
    uuid location_id FK
    text name
    text type
  }

Key Backend Building Blocks

Core tables

• profiles
• plants
• tasks
• messages
• plant_healthchecks
• plant_diary
• locations
• zones

Progress and collection tables

• species
• species_details
• discovery_events
• gardening_events

Monetization and usage tables

• credit_balances
• usage_log
• transactions
• subscriptions

Views and RPCs

• leaderboard_public
• daily_stats
• user_economics
• heatmap_grid
• heatmap_species_grid
• rank- and neighbor-related RPCs for leaderboard slices

Edge Function Topology

Shared server-side concerns live in supabase/functions/_shared/:

• auth resolution
• credits and refunds
• OpenAI invocation
• language helpers
• validation
• rate limiting
• CORS handling

Cross-Cutting Concerns

Auth and identity

• Supabase Auth is the identity source
• sessions persist through AsyncStorage
• AuthContext hydrates user and profile, sets locale, and initializes RevenueCat identity
• Sentry user context is bound to the authenticated user id

Credits and payments

• AI features are metered by services/pricingConfig.js
• client calls route through aiService.js
• server-side edge functions enforce charging, refunds, and usage logging
• RevenueCat webhooks synchronize entitlement-driven balances and subscription state

Caching and media

• image references are stored as storage paths where possible
• signed URLs are resolved on demand in read flows
• expo-image is the default rendering path for modern image-heavy surfaces
• species details are cached centrally in species_details

Internationalization

• locale dictionaries live in i18n/locales/
• profile language is applied during auth/profile hydration
• AI and structured details are generated language-aware

Reliability and observability

• client network calls use policy wrappers for timeout and retry behavior
• AI invocation code normalizes auth, rate-limit, and insufficient-credit errors
• Sentry captures client-side runtime failures
• CI enforces zero ESLint warnings and full Jest execution on main and PRs

Security model

• Postgres tables are protected through RLS
• edge functions use explicit auth handling or custom headers depending on endpoint purpose
• sensitive AI and billing logic stays server-side
• webhook and legal flows are separated from the mobile client runtime

Delivery Pipeline

flowchart LR
  Commit["Push to main"] --> CI["GitHub Actions: CI"]
  Commit --> SB["GitHub Actions: Supabase deploy"]
  Commit --> OTA["GitHub Actions: EAS OTA update"]
  Tag["Version tag"] --> Build["GitHub Actions: EAS build + submit"]

  CI --> Lint["ESLint + token guard"]
  CI --> Test["Jest suites"]

  SB --> DBPush["supabase db push"]
  SB --> FnDeploy["Deploy edge functions"]

  OTA --> Expo["Publish production updates to iOS and Android channels"]
  Build --> Stores["Native store builds and submissions"]

Design Decisions

Why a service-heavy client?

Because most product iteration happens in JavaScript, the client is intentionally organized around service modules rather than a heavier state-management framework. This keeps features shippable through OTA while still preserving seams for testing and error handling.

Why AI behind Edge Functions?

It centralizes:

• billing
• retries
• prompt evolution
• provider credentials
• legal and abuse boundaries

This is materially safer than calling model providers directly from the client.

Why Supabase as the main backend?

Supabase gives the project a pragmatic full-stack spine:

• auth
• relational storage
• file storage
• RLS
• edge compute
• SQL-native migrations and views

That is a strong fit for a small product team shipping quickly.

Tradeoffs and Current Constraints

• the client codebase is mostly JavaScript, not end-to-end TypeScript
• some repository documents are historical and may describe older counts or prices
• OTA speed is a strength, but native dependency changes still require full EAS builds
• the domain model has grown organically, so service boundaries are strong but not fully formalized as separate packages

Safe Extension Points

When adding new features, prefer extending the system in these seams:

1. add new UI surfaces in screens/ and components/
2. centralize client orchestration in services/
3. put metered or secret-bearing logic into Edge Functions
4. evolve the schema through new migrations only
5. wire release behavior through existing GitHub Actions instead of ad hoc deploy steps

Canonical Reading Order

For a new engineer, the fastest accurate orientation path is:

1. README.md
2. VISION.md
3. ARCHITECTURE.md
4. App.js
5. contexts/AuthContext.js
6. services/
7. supabase/functions/
8. supabase/migrations/

Vision

North Star

FloraScout turns everyday gardening into a compounding loop of noticing, understanding, and caring for living things.

It should feel like the product version of a great field notebook:

• fast enough for a phone in one hand and a watering can in the other
• smart enough to translate uncertainty into action
• rewarding enough that progress feels visible and worth returning to

Product Thesis

Most hobby gardeners do not fail because they do not care. They fail because the moment of need is messy:

• they do not know what plant they are looking at
• they are unsure what to do next
• they forget recurring care at the wrong moment
• they cannot see whether they are getting better over time

FloraScout solves this by combining three systems into one coherent product:

1. Recognition

The app identifies plants, surfaces species context, and gives each discovery emotional weight.

1. Care orchestration

The app turns plant knowledge, weather, and user input into concrete next actions.

1. Progress loops

The app makes growth visible through the Plant Dex, diary, health checks, and leaderboard mechanics.

Who The Product Is For

Primary audience

• hobby gardeners with a small to medium personal plant collection
• plant-curious people who enjoy learning by doing
• users who respond well to collection, streak, and progress systems

Secondary audience

• balcony and small-space growers
• users who treat gardening as a calming routine
• people who want a practical AI assistant, not a generic chatbot

Explicit non-audience

• professional agriculture operations
• scientific taxonomic workflows
• marketplace-first users who primarily want to buy and sell plants
• users who want an unbounded general-purpose assistant

Product Promise

FloraScout should answer five user questions extremely well:

1. What is this plant?
2. What should I do next?
3. What changed since last time?
4. How healthy is this plant right now?
5. Am I becoming a better gardener?

If the product is excellent, users feel more capable after each interaction, not merely more informed.

Experience Pillars

1. Discovery must feel rewarding

Scanning a plant is not just data entry. It is the front door into the product. The reveal moment, collection progress, rarity cues, and first-discovery status are not decoration; they are retention mechanics.

2. Care must collapse ambiguity into action

Advice is only useful if it becomes a task, a decision, or a next step. FloraScout should prefer practical guidance over encyclopedic sprawl.

3. Progress must be visible

Collections, diary entries, health scores, galleries, and leaderboards all serve the same purpose: showing that the user is building competence over time.

4. Intelligence must earn trust

AI should accelerate the user, not bluff them. The product should be transparent about uncertainty, resilient to transient failures, and conservative with destructive or high-confidence claims.

5. The system should invite return visits

The product is strongest when it becomes part of a weekly rhythm: scan, review, care, log, improve.

Core Product Loop

flowchart LR
  Notice["Notice a plant or issue"] --> Scan["Scan plant or open collection"]
  Scan --> Reveal["Identify species and trigger discovery reveal"]
  Reveal --> Learn["Read details, weather context, and health signals"]
  Learn --> Plan["Create or accept care tasks"]
  Plan --> Act["Water, prune, repot, observe"]
  Act --> Log["Save diary, photos, and health checks"]
  Log --> Progress["See Dex progress, scores, and leaderboard movement"]
  Progress --> Notice

Strategic Product Bets

The Plant Dex is the emotional center

The Dex is more than a list. It is the memory structure of the app. It turns every scan into a collectible, every plant into a species entry, and every return visit into measurable progress.

AI is product infrastructure, not the product itself

The scanner, health check, species details, avatar generation, and assistant are all important, but they only matter insofar as they make the gardening workflow better. The product should never collapse into "ask AI anything."

Care orchestration beats passive content

Static plant information is commoditized. The durable value sits in timing, prioritization, and adapting advice to the user's context.

Lightweight game systems increase adherence

Discovery status, first-finder moments, badges, credits, and leaderboards are not gimmicks when they reinforce care behavior. They should remain supportive, not manipulative.

Business Intent

FloraScout monetizes through credits and subscriptions, but monetization must stay subordinate to trust.

That means:

• paid features should feel like acceleration, not ransom
• free moments must still deliver delight and competence
• credit costs should remain legible and predictable
• monetization should reinforce repeat value, not interrupt it

Success Criteria

User value signals

• a first-time user identifies a plant and understands the next step within minutes
• returning users complete tasks because the app reduces planning friction
• the collection view becomes a destination, not a dead archive

Product health signals

• repeat scan behavior
• recurring task completion
• health check reuse
• diary/gallery accumulation
• Plant Dex progression over time

Business signals

• healthy conversion from free use to credits or subscription
• high retention among users who complete the discovery-to-care loop
• low support burden caused by confusing AI or pricing behavior

Product Boundaries

FloraScout should avoid becoming:

• a generic plant content encyclopedia
• a noisy social feed
• a hyper-complex project management tool
• a brittle "AI magic" experience with no fallbacks

Simplicity is part of the product strategy.

Decision Filter

When evaluating roadmap ideas, prefer work that improves at least one of these:

1. Time to first useful outcome
2. Clarity of the next care action
3. Emotional reward of discovery and progress
4. Retention through recurring plant routines
5. Trustworthiness of the system under real-world constraints

If an idea does not improve one of those, it is probably not core.

Horizon

Now

• make scanning, discovery, and care loops feel polished and dependable
• strengthen the Dex as the main retention surface
• keep OTA-deliverable improvements flowing quickly

Next

• deeper personalized care planning
• better species-level insight and smarter reminders
• more useful admin and operational tooling around AI and content quality

Later

• richer home and zone intelligence
• longitudinal plant outcome analysis
• stronger social proof without sacrificing calmness or utility

In One Sentence

FloraScout exists to make plant care feel less uncertain, more actionable, and visibly rewarding over time.

FloraScout

Note: This document is a deployable fallback from the Contributors project profile. Once a project source provides README, vision, or architecture artifacts, that source is rendered first.

Audit Snapshot

FloraScout is functional but not publicly launched yet: it needs beta users, ASO review, pricing signals, and community build-up.

Maturity

• Present: Store visual, TestFlight/Play Internal, core product, and clear B2C audience.
• Missing: ASO audit, native-speaker review, beta network, screenshot story, privacy review.

Lead Ask

ASO specialist: ASO specialist for v1.4.2 listing audit: keywords, screenshots, title, subtitle, conversion hypotheses, and review plan.