# karann88/fitbuddy-nextjs-app architecture

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

- Interactive diagram: https://gitdiagram.com/karann88/fitbuddy-nextjs-app
- Repository: https://github.com/karann88/fitbuddy-nextjs-app

## Overview

##### Project type and purpose
- Full-stack health & wellness tracking web application.
- Built with Next.js (React + TypeScript) on the frontend and Next.js serverless functions + Supabase (PostgreSQL) on the backend.
- Tracks mood, water, meals, sleep, exercise, stretching, journal, weight, breathing, etc., with real-time visualization.

##### File structure
- Top-level “app” directory: Next.js App Router pages & layouts (authentication pages, dashboards, per-metric pages).
- “components” directory: Reusable UI and feature widgets (trackers, forms, navigation, theme, timers).
- “lib” directory: Server-side utilities—authentication logic, Supabase client, middleware, validation.
- “hooks” directory: Custom React hooks (e.g., useMobile).
- “supabase” directory: Supabase config & SQL migration scripts.
- Config files: next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs.
- Public assets under “public/images.”

##### Key insights from README
- Frontend: Next.js + React Query + shadcn/ui + Tailwind CSS.
- Backend: Next.js serverless API routes, Supabase serverless PostgreSQL, Zod validation, connect-pg-simple sessions.
- Data flow: React Query → Next.js API → Supabase → PostgreSQL tables (managed via Drizzle Kit migrations).
- Real-time features: timers, live progress updates, optimistic updates.
- Deployment: Vite/ESBuild build chain, environment variables, production serverless deployment.

##### Main components
A. Frontend (Client)
- Next.js App Router (app folder)
- React components & pages (components/, components/ui/)
- State management: React Query + React Hook Form + Zod
- Custom hooks (hooks/)
B. Backend (Server)
- Next.js serverless functions (API routes under app/api or app/…)
- lib/auth-server, lib/supabase, lib/middleware, lib/validation
- Session store: connect-pg-simple in PostgreSQL
- RESTful endpoints for each metric (mood, meals, water, etc.)
C. Database
- Supabase serverless PostgreSQL
- Tables and schema managed via migrations (supabase/migrations/*.sql)
- Drizzle Kit integration for auto-migrations
D. External Services & Tools
- Supabase Auth & remote schemas
- Drizzle Kit migration engine
- Google Fit (future weight sync)
- Vite middleware in dev mode

##### Relationships and data flows
- Client (React Query) ↔ Next.js API (REST) ↔ Supabase client (lib/supabase.ts) ↔ PostgreSQL
- User actions (submit forms, timers) → React Query mutate() → API POST/PUT/DELETE → DB
- API GET endpoints → Data fetched → React Query cache → UI renders
- Authentication: Protected‐route component → Next.js session → PostgreSQL session table
- Migrations: CI/CD triggers supabase migration → DB schema update

##### Architectural patterns & design principles
- Separation of concerns: App Router for navigation, components for UI, lib for server logic, supabase for data.
- Layered architecture: Presentation → API → Database
- Hooks & context providers abstract cross-cutting concerns (theme, auth, session cleanup)
- Modular UI with atomic components (shadcn/ui) for consistency and reusability
- Type safety: TypeScript + Zod validation on both client and server

##### Additional guidance
- Break out per-metric API endpoints in a sub-section if detail is needed.
- Session flow: user login → session cookie → connect-pg-simple → DB.
- Migration workflow separately (CI → supabase/migrations → DB).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Frontend)"
        direction TB
        AppRouter["Next.js App Router"]:::frontend
        LoginPage["Login Page"]:::frontend
        SignupPage["Signup Page"]:::frontend
        ResetPage["Reset Password Page"]:::frontend
        ForgotPage["Forgot Password Page"]:::frontend
        DashboardPages["Dashboard & Metric Pages"]:::frontend
        UIComponents["Reusable UI Components"]:::frontend
        StateMgmt["State Management (React Query, RHF, Zod)"]:::frontend
        Hooks["Custom React Hooks"]:::frontend
    end

    %% Server Layer
    subgraph "Server (Backend)"
        direction TB
        APIRoutes["Next.js Serverless API"]:::backend
        AuthTS["lib/auth.ts"]:::backend
        AuthServer["lib/auth-server.ts"]:::backend
        AuthDebug["lib/auth-debug.ts"]:::backend
        AuthErrors["lib/auth-errors.ts"]:::backend
        SupabaseLib["lib/supabase.ts"]:::backend
        Middleware["lib/middleware.ts"]:::backend
        Validation["lib/validation.ts"]:::backend
        Utils["lib/utils.ts"]:::backend
        SessionStore["Session Store (connect-pg-simple)"]:::backend
    end

    %% Database Layer
    subgraph "Database"
        direction TB
        SupabaseDB["Supabase PostgreSQL"]:::database
        Migrations["SQL Migrations"]:::database
    end

    %% External Services
    subgraph "External Services & Tools"
        direction TB
        SupabaseAuth["Supabase Auth"]:::external
        DrizzleKit["Drizzle Kit Migration Engine"]:::external
        GoogleFit["Google Fit (Future Sync)"]:::external
        ViteDev["Vite/ESBuild Dev"]:::external
    end

    %% Connections
    AppRouter -->|uses| StateMgmt
    StateMgmt -->|"HTTP REST"| APIRoutes
    UIComponents -->|renders UI| AppRouter
    Hooks -->|provides hooks| AppRouter

    APIRoutes -->|calls| AuthTS
    APIRoutes -->|calls| SupabaseLib
    APIRoutes -->|uses| Middleware
    APIRoutes -->|validates via| Validation
    APIRoutes -->|utility| Utils
    APIRoutes -->|session| SessionStore
    SessionStore -->|stores sessions| SupabaseDB
    SupabaseLib -->|queries| SupabaseDB

    Migrations -->|updates schema| SupabaseDB
    DrizzleKit -->|runs migrations| Migrations

    ViteDev -->|dev build| AppRouter
    SupabaseAuth -->|auth service| APIRoutes
    GoogleFit -->|future data| APIRoutes

    %% Click Events - Frontend
    click AppRouter "https://github.com/karann88/fitbuddy-nextjs-app/tree/main/app/"
    click LoginPage "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/app/auth/login/page.tsx"
    click SignupPage "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/app/auth/signup/page.tsx"
    click ResetPage "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/app/auth/reset-password/page.tsx"
    click ForgotPage "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/app/auth/forgot-password/page.tsx"
    click DashboardPages "https://github.com/karann88/fitbuddy-nextjs-app/tree/main/app/dashboard/"
    click UIComponents "https://github.com/karann88/fitbuddy-nextjs-app/tree/main/components/"
    click Hooks "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/hooks/use-mobile.ts"

    %% Click Events - Backend
    click AuthTS "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/auth.ts"
    click AuthServer "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/auth-server.ts"
    click AuthDebug "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/auth-debug.ts"
    click AuthErrors "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/auth-errors.ts"
    click SupabaseLib "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/supabase.ts"
    click Middleware "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/middleware.ts"
    click Validation "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/validation.ts"
    click Utils "https://github.com/karann88/fitbuddy-nextjs-app/blob/main/lib/utils.ts"

    %% Click Events - Database
    click Migrations "https://github.com/karann88/fitbuddy-nextjs-app/tree/main/supabase/migrations/"

    %% Styles
    classDef frontend fill:#bbdefb,stroke:#2196f3,stroke-width:2px
    classDef backend fill:#c8e6c9,stroke:#4caf50,stroke-width:2px
    classDef database fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px
    classDef external fill:#e1bee7,stroke:#9c27b0,stroke-width:2px
```
