milan-1002/bloom

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.