# milan-1002/bloom architecture

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

- Interactive diagram: https://gitdiagram.com/milan-1002/bloom
- Repository: https://github.com/milan-1002/bloom

## Overview

1. This repository is a React + TypeScript single-page app built with Vite. The app is structured as a consumer health product centered on cycle-aware nutrition, symptom tracking, recipe generation, and report export.

2. The top-level UI is split into screen-level routes under `src/screens` and reusable feature components under `src/components`. `src/App.tsx` and `src/main.tsx` boot the app, while `src/components/layout` provides the route and access-control shell.

3. Authentication and onboarding are first-class boundaries. `AuthContext` plus `useAuth` manage session state, `RequireAuth` and `RequireProfile` gate protected areas, and onboarding state is also persisted locally via `src/stores/onboardingStore.ts` to control first-run flow.

4. The main domain areas are:
   - food logging and diary views
   - health tracking for symptoms and weight
   - home/dashboard cycle insights
   - recipe discovery and generation
   - reports for clinical or summary export
   - auth and onboarding screens
   Each area has its own screens, hooks, and feature components rather than a single monolithic view layer.

5. Data access is centralized in custom hooks under `src/hooks`. These hooks wrap fetch/mutation behavior for food logs, recipes, weight logs, symptom logs, profile data, report data, and AI target generation. This makes the screens mostly orchestration layers over domain-specific query/mutation hooks.

6. The app’s primary backend is Supabase. `src/lib/supabase.ts` is the client entry point, and `src/lib/database.types.ts` provides typed database access. Supabase migrations define the persistent model for auth-linked profile data, food logs, cycle columns, AI targets, and saved/library recipes.

7. There is a second backend boundary for Supabase Edge Functions under `supabase/functions`. These functions handle server-side integrations and privileged workflows: recipe generation, custom recipe generation, AI target generation, USDA search, and account deletion. The frontend invokes these through the corresponding hooks and then renders the results back into the UI.

8. External data and AI-related flows are important:
   - USDA search is used for food lookup and barcode/food detail workflows.
   - generated targets and recipes are produced by server-side functions rather than directly in the client.
   - validation logic in `src/lib/ai-validation.ts` and `src/lib/targets.ts` suggests the app sanitizes AI outputs before showing them to users.
   This creates a clear client → edge function → data store loop for higher-risk operations.

9. The cycle-aware logic is mostly local and derived. Utilities in `src/lib/cycle.ts`, `src/lib/gl.ts`, `src/lib/rolling-average.ts`, and `src/lib/report-stats.ts` indicate the app computes health insights, symptom summaries, and glucose-related metrics on the client from logged data and profile/cycle metadata.

10. Reporting is a separate aggregation and presentation path. `useReportData` gathers the relevant records, `src/lib/report-stats.ts` and related helpers compute summaries, `GLSymptomChart` renders the visual output, and `src/lib/report-pdf.tsx` supports exportable report generation.

11. The UI layer uses a small design-system style set in `src/components/ui` plus theme tokens in `src/styles/tokens.css` and `src/lib/theme.ts`. This suggests a consistent branded shell around many feature-specific screens, including PWA-oriented polish such as generated brand icons in `scripts/generate-icons.mjs`.

12. State management is intentionally lightweight: most server state is handled through hooks and query utilities, while local app state is reserved for onboarding and transient UI flows. There is no evidence of a large global client store beyond auth/onboarding boundaries.

13. Testing is organized by feature area under `tests/`, with coverage for auth, guards, onboarding, health, logging, dashboard aggregation, and theme behavior. That mirrors the architecture: domain hooks and guard components are the primary units of behavior, not just visual screens.

14. Deployment and build-time concerns are standard Vite app concerns, with `vercel.json` indicating hosting on Vercel and a `supabase/` backend co-located in the same repo. The architecture is therefore a client app plus managed backend services, with edge functions and migrations kept alongside the frontend for tight coupling.

Main entry points: [`src/App.tsx`](https://github.com/milan-1002/bloom/blob/master/src/App.tsx) (App), [`src/hooks/useFoodLogs.ts`](https://github.com/milan-1002/bloom/blob/master/src/hooks/useFoodLogs.ts) (Domain Hooks), [`src/lib/supabase.ts`](https://github.com/milan-1002/bloom/blob/master/src/lib/supabase.ts) (Supabase Client), [`src/contexts/AuthContext.tsx`](https://github.com/milan-1002/bloom/blob/master/src/contexts/AuthContext.tsx) (Auth Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_app["App Shell"]
  node_node_main(("Main<br/>bootstrap<br/>[main.tsx]"))
  node_node_app["App<br/>router shell<br/>[App.tsx]"]
  node_node_auth_ctx[("Auth Context<br/>session state<br/>[AuthContext.tsx]")]
  node_node_auth_layout{{"Auth Gate<br/>access control<br/>[RequireAuth.tsx]"}}
  node_node_profile_gate{{"Profile Gate<br/>access control<br/>[RequireProfile.tsx]"}}
  node_node_onboarding_store[("Onboarding Store<br/>local state<br/>[onboardingStore.ts]")]
end

subgraph group_group_domain["Domain UI"]
  node_node_home["Home<br/>dashboard screen<br/>[HomeScreen.tsx]"]
  node_node_diary["Diary<br/>logging screen<br/>[DiaryScreen.tsx]"]
  node_node_logging["Food Logging<br/>food workflow"]
  node_node_health["Health<br/>tracking screen<br/>[SymptomsScreen.tsx]"]
  node_node_recipes["Recipes<br/>recipe screen<br/>[RecipesScreen.tsx]"]
  node_node_reports["Reports<br/>report screen<br/>[ReportScreen.tsx]"]
  node_node_auth_screens["Auth Screens<br/>auth flow<br/>[SignInScreen.tsx]"]
  node_node_onboarding_screens["Onboarding"]
end

subgraph group_group_data["Data & Logic"]
  node_node_hooks[("Domain Hooks<br/>query/mutation layer<br/>[useFoodLogs.ts]")]
  node_node_cycle_lib{{"Cycle Logic<br/>client derivation<br/>[cycle.ts]"}}
  node_node_report_lib{{"Report Logic<br/>aggregation/export<br/>[report-stats.ts]"}}
  node_node_ai_lib{{"AI Safety<br/>validation<br/>[ai-validation.ts]"}}
end

subgraph group_group_backend["Backend"]
  node_node_supabase[("Supabase Client<br/>backend client<br/>[supabase.ts]")]
  node_node_db_types["DB Types<br/>schema types<br/>[database.types.ts]"]
  node_node_edge_funcs{{"Edge Functions<br/>server workflows<br/>[index.ts]"}}
  node_node_migrations["Migrations<br/>schema evolution"]
end

node_node_main -->|"boots"| node_node_app
node_node_app -->|"wraps"| node_node_auth_ctx
node_node_app -->|"guards"| node_node_auth_layout
node_node_app -->|"gates"| node_node_profile_gate
node_node_auth_ctx -->|"reads session"| node_node_supabase
node_node_auth_ctx -->|"persists flow"| node_node_onboarding_store
node_node_app -->|"routes"| node_node_auth_screens
node_node_app -->|"routes"| node_node_onboarding_screens
node_node_app -->|"routes"| node_node_home
node_node_app -->|"routes"| node_node_diary
node_node_app -->|"routes"| node_node_logging
node_node_app -->|"routes"| node_node_health
node_node_app -->|"routes"| node_node_recipes
node_node_app -->|"routes"| node_node_reports
node_node_home -->|"derives"| node_node_cycle_lib
node_node_health -->|"uses"| node_node_hooks
node_node_logging -->|"uses"| node_node_hooks
node_node_recipes -->|"uses"| node_node_hooks
node_node_reports -->|"aggregates"| node_node_report_lib
node_node_reports -->|"loads data"| node_node_hooks
node_node_hooks -->|"queries"| node_node_supabase
node_node_hooks -->|"invokes"| node_node_edge_funcs
node_node_hooks -->|"sanitizes"| node_node_ai_lib
node_node_cycle_lib -->|"interprets"| node_node_db_types
node_node_report_lib -->|"summarizes"| node_node_db_types
node_node_edge_funcs -->|"writes"| node_node_migrations
node_node_supabase -->|"typed by"| node_node_db_types
node_node_supabase -->|"backed by"| node_node_migrations

click node_node_main "https://github.com/milan-1002/bloom/blob/master/src/main.tsx"
click node_node_app "https://github.com/milan-1002/bloom/blob/master/src/App.tsx"
click node_node_auth_ctx "https://github.com/milan-1002/bloom/blob/master/src/contexts/AuthContext.tsx"
click node_node_auth_layout "https://github.com/milan-1002/bloom/blob/master/src/components/layout/RequireAuth.tsx"
click node_node_profile_gate "https://github.com/milan-1002/bloom/blob/master/src/components/layout/RequireProfile.tsx"
click node_node_onboarding_store "https://github.com/milan-1002/bloom/blob/master/src/stores/onboardingStore.ts"
click node_node_home "https://github.com/milan-1002/bloom/blob/master/src/screens/home/HomeScreen.tsx"
click node_node_diary "https://github.com/milan-1002/bloom/blob/master/src/screens/diary/DiaryScreen.tsx"
click node_node_logging "https://github.com/milan-1002/bloom/blob/master/src/screens/logging/FoodSearchScreen.tsx"
click node_node_health "https://github.com/milan-1002/bloom/blob/master/src/screens/symptoms/SymptomsScreen.tsx"
click node_node_recipes "https://github.com/milan-1002/bloom/blob/master/src/screens/recipes/RecipesScreen.tsx"
click node_node_reports "https://github.com/milan-1002/bloom/blob/master/src/screens/report/ReportScreen.tsx"
click node_node_auth_screens "https://github.com/milan-1002/bloom/blob/master/src/screens/auth/SignInScreen.tsx"
click node_node_onboarding_screens "https://github.com/milan-1002/bloom/blob/master/src/screens/onboarding/OnboardingWelcomeScreen.tsx"
click node_node_hooks "https://github.com/milan-1002/bloom/blob/master/src/hooks/useFoodLogs.ts"
click node_node_cycle_lib "https://github.com/milan-1002/bloom/blob/master/src/lib/cycle.ts"
click node_node_report_lib "https://github.com/milan-1002/bloom/blob/master/src/lib/report-stats.ts"
click node_node_ai_lib "https://github.com/milan-1002/bloom/blob/master/src/lib/ai-validation.ts"
click node_node_supabase "https://github.com/milan-1002/bloom/blob/master/src/lib/supabase.ts"
click node_node_db_types "https://github.com/milan-1002/bloom/blob/master/src/lib/database.types.ts"
click node_node_edge_funcs "https://github.com/milan-1002/bloom/blob/master/supabase/functions/generate-recipes/index.ts"
click node_node_migrations "https://github.com/milan-1002/bloom/blob/master/supabase/migrations/20260518000001_init.sql"

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_node_main,node_node_app,node_node_auth_ctx,node_node_auth_layout,node_node_profile_gate,node_node_onboarding_store toneBlue
class node_node_home,node_node_diary,node_node_logging,node_node_health,node_node_recipes,node_node_reports,node_node_auth_screens,node_node_onboarding_screens toneAmber
class node_node_hooks,node_node_cycle_lib,node_node_report_lib,node_node_ai_lib toneMint
class node_node_supabase,node_node_db_types,node_node_edge_funcs,node_node_migrations toneRose
```

## Components

### App Shell

Bootstrap, routing, auth boundaries, and onboarding flow.

- [Main](https://github.com/milan-1002/bloom/blob/master/src/main.tsx): bootstrap · Vite entry that mounts the app. · `src/main.tsx`
- [App](https://github.com/milan-1002/bloom/blob/master/src/App.tsx): router shell · Top-level app composition and route wiring. · `src/App.tsx`
- [Auth Context](https://github.com/milan-1002/bloom/blob/master/src/contexts/AuthContext.tsx): session state · Session and profile access for the client. · `src/contexts/AuthContext.tsx`
- [Auth Gate](https://github.com/milan-1002/bloom/blob/master/src/components/layout/RequireAuth.tsx): access control · Protected-route and profile gating shell. · `src/components/layout/RequireAuth.tsx`
- [Profile Gate](https://github.com/milan-1002/bloom/blob/master/src/components/layout/RequireProfile.tsx): access control · Ensures onboarding/profile completion before entry. · `src/components/layout/RequireProfile.tsx`
- [Onboarding Store](https://github.com/milan-1002/bloom/blob/master/src/stores/onboardingStore.ts): local state · Persists first-run onboarding state locally. · `src/stores/onboardingStore.ts`

### Domain UI

Screen-level product areas and reusable feature components.

- [Home](https://github.com/milan-1002/bloom/blob/master/src/screens/home/HomeScreen.tsx): dashboard screen · Cycle-aware summary and daily insights. · `src/screens/home/HomeScreen.tsx`
- [Diary](https://github.com/milan-1002/bloom/blob/master/src/screens/diary/DiaryScreen.tsx): logging screen · Food diary and meal log view. · `src/screens/diary/DiaryScreen.tsx`
- [Food Logging](https://github.com/milan-1002/bloom/blob/master/src/screens/logging/FoodSearchScreen.tsx): food workflow · Search, barcode lookup, and food detail entry flows. · `src/screens/logging/FoodSearchScreen.tsx`
- [Health](https://github.com/milan-1002/bloom/blob/master/src/screens/symptoms/SymptomsScreen.tsx): tracking screen · Symptoms and weight tracking screens. · `src/screens/symptoms/SymptomsScreen.tsx`
- [Recipes](https://github.com/milan-1002/bloom/blob/master/src/screens/recipes/RecipesScreen.tsx): recipe screen · Recipe discovery, generation, and detail views. · `src/screens/recipes/RecipesScreen.tsx`
- [Reports](https://github.com/milan-1002/bloom/blob/master/src/screens/report/ReportScreen.tsx): report screen · Clinical and summary export views. · `src/screens/report/ReportScreen.tsx`
- [Auth Screens](https://github.com/milan-1002/bloom/blob/master/src/screens/auth/SignInScreen.tsx): auth flow · Sign-in, sign-up, reset, callback, and welcome screens. · `src/screens/auth/SignInScreen.tsx`
- [Onboarding](https://github.com/milan-1002/bloom/blob/master/src/screens/onboarding/OnboardingWelcomeScreen.tsx): onboarding flow · Profile and PCOS onboarding screens. · `src/screens/onboarding/OnboardingWelcomeScreen.tsx`

### Data & Logic

Client hooks, local stores, and shared domain utilities.

- [Domain Hooks](https://github.com/milan-1002/bloom/blob/master/src/hooks/useFoodLogs.ts): query/mutation layer · Feature hooks for logs, profile, recipes, reports, and AI targets. · `src/hooks/useFoodLogs.ts`
- [Cycle Logic](https://github.com/milan-1002/bloom/blob/master/src/lib/cycle.ts): client derivation · Cycle, glucose, rolling average, and health summary helpers. · `src/lib/cycle.ts`
- [Report Logic](https://github.com/milan-1002/bloom/blob/master/src/lib/report-stats.ts): aggregation/export · Report statistics and PDF generation helpers. · `src/lib/report-stats.ts`
- [AI Safety](https://github.com/milan-1002/bloom/blob/master/src/lib/ai-validation.ts): validation · Validation and target-shaping for generated AI outputs. · `src/lib/ai-validation.ts`

### Backend

Supabase client, schema, migrations, and edge functions.

- [Supabase Client](https://github.com/milan-1002/bloom/blob/master/src/lib/supabase.ts): backend client · Typed Supabase access from the frontend. · `src/lib/supabase.ts`
- [DB Types](https://github.com/milan-1002/bloom/blob/master/src/lib/database.types.ts): schema types · Generated database typings for tables and records. · `src/lib/database.types.ts`
- [Edge Functions](https://github.com/milan-1002/bloom/blob/master/supabase/functions/generate-recipes/index.ts): server workflows · Recipe generation, AI targets, USDA search, and account deletion. · `supabase/functions/generate-recipes/index.ts`
- [Migrations](https://github.com/milan-1002/bloom/blob/master/supabase/migrations/20260518000001_init.sql): schema evolution · Persistent schema for profiles, logs, targets, recipes, and cycles. · `supabase/migrations/20260518000001_init.sql`

## Connections

- Main → App: boots · Application entry mounts the route shell.
- App → Auth Context: wraps · App composition provides session context.
- App → Auth Gate: guards · Protected areas are gated by auth.
- App → Profile Gate: gates · Onboarding/profile completion is enforced.
- Auth Context → Supabase Client: reads session · Auth state is backed by Supabase.
- Auth Context → Onboarding Store: persists flow · Onboarding state is stored locally.
- App → Auth Screens: routes · Authentication screens form a separate route set.
- App → Onboarding: routes · First-run onboarding screens are routed separately.
- App → Home: routes · Dashboard/home is a primary app destination.
- App → Diary: routes · Diary is a primary app destination.
- App → Food Logging: routes · Food logging flows are exposed as screens.
- App → Health: routes · Health tracking screens are exposed as screens.
- App → Recipes: routes · Recipe discovery and generation screens are exposed as screens.
- App → Reports: routes · Report export is a top-level destination.
- Home → Cycle Logic: derives · Dashboard insights are computed from local cycle logic.
- Health → Domain Hooks: uses · Tracking screens rely on log/profile hooks.
- Food Logging → Domain Hooks: uses · Food entry flows use domain hooks for reads and writes.
- Recipes → Domain Hooks: uses · Recipe screens use hooks for fetch and generation.
- Reports → Report Logic: aggregates · Report screen combines stats and export helpers.
- Reports → Domain Hooks: loads data · Report data is fetched through dedicated hooks.
- Domain Hooks → Supabase Client: queries · Most server state is mediated through Supabase.
- Domain Hooks → Edge Functions: invokes · High-risk operations are delegated to edge functions.
- Domain Hooks → AI Safety: sanitizes · Generated content is validated before presentation.
- Cycle Logic → DB Types: interprets · Cycle computations depend on typed data shape.
- Report Logic → DB Types: summarizes · Reporting aggregates typed records.
- Edge Functions → Migrations: writes · Server workflows operate over the persisted schema.
- Supabase Client → DB Types: typed by · Client access is backed by generated types.
- Supabase Client → Migrations: backed by · Client data maps to the migrated schema.