How karann88/fitbuddy-nextjs-app works
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).