# hmz865/fitguy architecture

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

- Interactive diagram: https://gitdiagram.com/hmz865/fitguy
- Repository: https://github.com/hmz865/fitguy

## Overview

Step 1: Identify the project type and purpose
- This is a full-stack, single-page web application built in React/TypeScript (via Vite) for a fitness and wellness platform (BMI calculators, AI chat coach, nutrition/workout plans, subscription management, admin dashboards).
- The README confirms the tech stack (Vite, React, TypeScript, Tailwind CSS, shadcn-ui) and that the app is backed by Supabase (database, auth, edge functions).

Step 2: Analyze the file structure
- Top-level folders:
- public/ (static assets, robots.txt, index.html)
- src/ (all front-end code, subdivided into components, pages, contexts, hooks, integrations, utils)
- supabase/ (backend-as-a-service config & edge functions)
- Under src/components you see UI slices, feature components (BMI, AIChat, NutritionPlan), admin panel components, dashboard sections, and a UI library scaffold (ui/*).
- src/contexts holds React context providers (AuthContext, SubscriptionContext, ThemeContext).
- src/hooks implements data-fetching and business hooks (useSavedWorkouts, useFeatureAccess, etc.).
- supabase/functions defines serverless edge functions for checkout, subscription checks, AI chat, nutrition recommendations, newsletters.

Step 3: Examine the README for additional insights
- Confirms a Lovable dashboard project, with Git-backed and Lovable-managed workflows.

a. Main components
1. Client (Browser): React SPA served as static assets.
2. Front-end layers:
– UI Components & Pages (src/pages, src/components)
– React Router (ProtectedRoute, PremiumRoute)
– Context Providers & Hooks (AuthContext, SubscriptionContext, custom data hooks)
3. BaaS Back-end: Supabase
– Authentication Service
– PostgreSQL Database
– Edge Functions (check-subscription, create-checkout, AI Chat, nutrition recommendations, send newsletters)
4. External Services
– Stripe (checkout, billing portal)
– OpenAI (fitness-AI chat)
– Email service (newsletter delivery)
b. Relationships and interactions
- Browser loads the SPA and interacts with UI.
- UI uses AuthContext & SubscriptionContext to manage user state.
- Data hooks call the Supabase client (via integrations/supabase/client.ts) for CRUD and auth.
- For specialized tasks (AI chat, nutrition logic, billing), front end invokes Supabase Edge Functions which in turn integrate with external APIs (Stripe, OpenAI, Email).
- Supabase edge functions read/write to the Postgres database.
c. Architectural patterns and design principles
- Single-page application with client-side routing.
- Container/presenter split: pages orchestrate, components render UI.
- Context for global state, custom hooks for data logic.
- BaaS pattern: minimize custom back-end by leveraging Supabase edge functions.
- Feature gating (PremiumRoute, PremiumFeatureGate).
d. Key technologies, frameworks, or libraries
- Vite & TypeScript for build & typing.
- React & shadcn-ui (Tailwind CSS) for UI.
- Supabase for auth, database, and serverless logic.
- Stripe, OpenAI, email service for payments, AI, and mailing.

- Clearly separate the Front-end SPA layer from the Supabase BaaS layer.
- API boundary: Supabase client SDK calls vs. Edge Function HTTP endpoints.
- How context and hooks mediate between UI components and data services.

- Labels for each component (e.g., “React SPA”, “AuthContext”, “Supabase Edge Function: fitness-ai-chat”).
- Front-end (blue rectangles)
- External services (orange clouds)

Step 7: Final guidelines
- Be very detailed: break the front end into UI components, contexts, hooks, and routing layers.
- On the backend side, separate the database, auth, and individual edge functions.
- Don’t overthink it—capture every major directory or module as its own node so the engineer can see how traffic flows through the system from UI to data to external APIs.
- Use a consistent layout: top row for UI, middle for BaaS, bottom for external services.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end Layer
    subgraph "Client (Browser)" 
        direction TB
        HTML["public/index.html"]:::frontend
        Entry["src/main.tsx"]:::frontend
        App["src/App.tsx"]:::frontend
        Router["React Router"]:::frontend
        Guards["ProtectedRoute / PremiumRoute"]:::frontend
        Pages["src/pages/"]:::frontend
        Components["src/components/"]:::frontend
        Contexts["Context Providers"]:::frontend
        Hooks["Custom Hooks"]:::frontend
    end

    HTML -->|"loads"| Entry
    Entry -->|"renders"| App
    App -->|"uses"| Router
    Router -->|"guards via"| Guards
    Guards --> Pages
    Pages --> Components
    Components --> Contexts
    Components --> Hooks

    %% BaaS Layer
    subgraph "Supabase BaaS" 
        direction TB
        SBClient["Supabase Client\nsrc/integrations/supabase/client.ts"]:::backend
        AuthService["Auth Service"]:::backend
        Database["PostgreSQL Database"]:::backend
        subgraph "Edge Functions" 
            direction TB
            CheckSub["check-subscription"]:::backend
            CreateCO["create-checkout"]:::backend
            Portal["customer-portal"]:::backend
            AIChatFn["fitness-ai-chat"]:::backend
            NutritionFn["nutrition-recommendations"]:::backend
            NewsletterFn["send-newsletter-emails"]:::backend
        end
    end

    Hooks -->|"calls"| SBClient
    SBClient --> AuthService
    SBClient --> Database
    SBClient --> EdgeFns[/"Edge Functions"/] 
    EdgeFns --> CheckSub
    EdgeFns --> CreateCO
    EdgeFns --> Portal
    EdgeFns --> AIChatFn
    EdgeFns --> NutritionFn
    EdgeFns --> NewsletterFn
    CheckSub --> Database
    CreateCO --> Database
    Portal --> Database
    AIChatFn --> Database
    NutritionFn --> Database
    NewsletterFn --> Database

    %% External Services
    subgraph "External Services"
        direction TB
        Stripe["Stripe"]:::external
        OpenAI["OpenAI"]:::external
        EmailSvc["Email Service"]:::external
    end

    CreateCO -->|"Stripe API"| Stripe
    Portal -->|"Stripe API"| Stripe
    AIChatFn -->|"OpenAI API"| OpenAI
    NewsletterFn -->|"Email API"| EmailSvc

    %% Click events
    click HTML "https://github.com/hmz865/fitguy/blob/main/public/index.html"
    click Entry "https://github.com/hmz865/fitguy/blob/main/src/main.tsx"
    click App "https://github.com/hmz865/fitguy/blob/main/src/App.tsx"
    click Components "https://github.com/hmz865/fitguy/tree/main/src/components/"
    click Pages "https://github.com/hmz865/fitguy/tree/main/src/pages/"
    click Guards "https://github.com/hmz865/fitguy/blob/main/src/components/ProtectedRoute.tsx"
    click Guards "https://github.com/hmz865/fitguy/blob/main/src/components/PremiumRoute.tsx"
    click Contexts "https://github.com/hmz865/fitguy/blob/main/src/contexts/AuthContext.tsx"
    click Contexts "https://github.com/hmz865/fitguy/blob/main/src/contexts/SubscriptionContext.tsx"
    click Contexts "https://github.com/hmz865/fitguy/blob/main/src/contexts/ThemeContext.tsx"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/useFeatureAccess.ts"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/usePremiumAccess.ts"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/useSavedWorkouts.ts"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/useSavedNutritionPlans.ts"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/useBlogs.ts"
    click Hooks "https://github.com/hmz865/fitguy/blob/main/src/hooks/use-toast.ts"
    click SBClient "https://github.com/hmz865/fitguy/blob/main/src/integrations/supabase/client.ts"

    click CheckSub "https://github.com/hmz865/fitguy/blob/main/supabase/functions/check-subscription/index.ts"
    click CreateCO "https://github.com/hmz865/fitguy/blob/main/supabase/functions/create-checkout/index.ts"
    click Portal "https://github.com/hmz865/fitguy/blob/main/supabase/functions/customer-portal/index.ts"
    click AIChatFn "https://github.com/hmz865/fitguy/blob/main/supabase/functions/fitness-ai-chat/index.ts"
    click NutritionFn "https://github.com/hmz865/fitguy/blob/main/supabase/functions/nutrition-recommendations/index.ts"
    click NewsletterFn "https://github.com/hmz865/fitguy/blob/main/supabase/functions/send-newsletter-emails/index.ts"

    classDef frontend fill:#D6EFFF,stroke:#333,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#333,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#333,stroke-width:1px
```
