# porta0922/nutripro architecture

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

- Interactive diagram: https://gitdiagram.com/porta0922/nutripro
- Repository: https://github.com/porta0922/nutripro

## Overview

1. **Top-level shape**
   NutriPro is a single Next.js application (Pages Router) backed by Supabase. The app serves multiple user roles from one codebase: nutritionist, patient, student, tutor, university admin, and system admin. The architecture is strongly domain-driven, but not microservice-based.

2. **Entry points and routing**
   The main navigation starts at the landing page and unified sign-in flow, then branches into role-specific route trees under `pages/`. Each role has its own dashboard and subpages, which acts as the primary architectural boundary for UI and data access.

3. **Authentication and route protection**
   Supabase Auth is the identity provider in production. `middleware.ts` enforces access control at the route layer, while `lib/auth.tsx` and related pages manage session state and role-based redirects. There is also a development mock-auth path for local testing, which bypasses real authentication when enabled.

4. **Backend/data layer**
   The persistent backend is Supabase Postgres plus Supabase Storage. Database access is done through the Supabase JS client in `lib/supabaseClient.ts`, with Row Level Security enforcing most authorization rules in the database itself. This means the application trusts both route guards and DB policies, not just UI checks.

5. **Core clinical domain**
   The nutritionist/patient subsystem covers clients, appointments, anthropometrics, body composition, diets, progress photos, and notifications. UI components, hooks, schemas, and Supabase tables line up closely here: forms capture clinical data, hooks fetch/update it, and charts/lists display longitudinal history.

6. **Academic practice domain**
   A second major bounded context handles student, tutor, and university workflows. It includes practice patients, meal plans, tutor reviews, field trips, and institutional administration. This subsystem is separate from the real-patient workflow in both routes and permissions, because practice data is marked and governed differently.

7. **Administration and subscriptions**
   The admin area manages platform-wide concerns such as nutritionist accounts, universities, reports, support, audit, and subscriptions. This is the highest-privilege boundary in the system and is the main place where privileged API routes and database operations are exposed.

8. **Client-side state and shared UI**
   `contexts/` provides cross-cutting state for language and notifications, while `hooks/` encapsulates domain fetch/mutation logic for clients, diets, anthropometrics, food portions, students, tutors, and reviews. `components/` is organized into reusable domain widgets and form panels, so pages mostly compose prebuilt pieces rather than implementing logic inline.

9. **Validation and domain rules**
   Zod schemas in `schemas/` validate key forms such as anthropometrics and appointments before data is submitted. This creates a validation boundary on the client side that complements Supabase constraints and RLS on the server side.

10. **Notifications and scheduled jobs**
   Notifications are a first-class subsystem, with a UI center, database support, and a Supabase Edge Function for appointment reminders. The cron-driven function under `supabase/functions/send-appointment-reminders` is the clearest background process in the repository and is likely the only scheduled automation path.

11. **File and document handling**
   PDFs and images are stored in Supabase Storage buckets, mainly `diets`, `progress_photos`, and `profile_pictures`. Diet plans and patient reports flow from forms/components into storage-backed records, then back out to embedded viewers, downloads, or generated exports.

12. **API routes as server-side escape hatches**
   The app uses Next.js API routes for privileged or orchestration-style tasks such as admin actions, auth/profile helpers, exports, photo deletion, setup flows, and job execution. These routes are the main server-side integration surface outside of direct client-to-Supabase calls.

13. **Utility and rendering support**
   Shared utilities like PDF generation and currency formatting support the clinical and admin workflows. The repo also includes global theming and layout helpers, which suggests most UI consistency is handled centrally rather than per module.

14. **Operational/deployment boundary**
   The repository is productionized with Docker, Nginx config, Next.js config, and extensive Supabase SQL migrations/seeds. The architecture therefore spans frontend, database, storage, and edge automation, with docs and SQL scripts serving as the source of truth for schema, policies, and deployment behavior.

Main entry points: [`middleware.ts`](https://github.com/porta0922/nutripro/blob/main/middleware.ts) (Route guard), [`lib/supabaseClient.ts`](https://github.com/porta0922/nutripro/blob/main/lib/supabaseClient.ts) (Supabase client), [`lib/auth.tsx`](https://github.com/porta0922/nutripro/blob/main/lib/auth.tsx) (Session auth), [`hooks/useClients.ts`](https://github.com/porta0922/nutripro/blob/main/hooks/useClients.ts) (Clients hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["App UI"]
  node_pages_index["Landing<br/>Next page<br/>[index.tsx]"]
  node_pages_signin["Sign in<br/>Auth page<br/>[signin.tsx]"]
  node_pages_nutritionist_dashboard["Nutri dashboard<br/>Role dashboard<br/>[dashboard.tsx]"]
  node_pages_student_dashboard["Student dashboard<br/>Role dashboard<br/>[dashboard.tsx]"]
  node_pages_tutor_dashboard["Tutor dashboard<br/>Role dashboard<br/>[dashboard.tsx]"]
  node_pages_universidad_dashboard["University dashboard<br/>Role dashboard<br/>[dashboard.tsx]"]
  node_pages_admin_index["Admin area<br/>Privileged area<br/>[index.tsx]"]
  node_client_dashboard["Client view<br/>Patient portal<br/>[dashboard.tsx]"]
  node_theme["Theme<br/>[theme.ts]"]
  node_styles_globals["Global styles<br/>Stylesheet<br/>[globals.css]"]
end

subgraph group_domain["Domain Modules"]
  node_components_notification_center["Notifications<br/>UI widget"]
  node_components_diet_plan_builder["Diet builder<br/>Clinical widget"]
  node_components_anthro_form["Anthro form<br/>Clinical form"]
  node_components_student_field_trip["Field trips<br/>Academic form<br/>[FieldTripForm.tsx]"]
  node_components_tutor_review["Meal review<br/>Academic widget"]
  node_components_admin_metrics["Admin metrics<br/>Admin widget"]
  node_utils_diet_pdf["PDF export<br/>Export util<br/>[dietPlanPDF.ts]"]
end

subgraph group_data["Auth & Data"]
  node_middleware["Route guard<br/>Edge middleware<br/>[middleware.ts]"]
  node_lib_auth["Session auth<br/>Auth client<br/>[auth.tsx]"]
  node_supabase_client["Supabase client<br/>DB client<br/>[supabaseClient.ts]"]
  node_use_clients["Clients hook<br/>Data hook<br/>[useClients.ts]"]
  node_use_student_patients["Student hook<br/>Data hook"]
  node_schemas_appointments["Appointment schema<br/>Validation schema<br/>[appointments.ts]"]
end

subgraph group_platform["Platform"]
  node_api_admin_metrics["Metrics API<br/>Admin API<br/>[metrics.ts]"]
  node_api_clients_create["Client API<br/>App API<br/>[create.ts]"]
  node_api_jobs_reminders["Reminder job<br/>Job API"]
  node_api_auth_mock["Mock auth<br/>Dev API<br/>[mock.ts]"]
  node_edge_reminders["Reminder function<br/>Supabase Edge Function<br/>[index.ts]"]
  node_supabase_migrations["Schema & RLS<br/>SQL migrations"]
  node_supabase_schema["DB schema<br/>SQL schema<br/>[schema.sql]"]
end

node_pages_index -->|"start auth"| node_pages_signin
node_pages_signin -->|"session"| node_lib_auth
node_lib_auth -.->|"protect routes"| node_middleware
node_middleware -->|"gate"| node_pages_nutritionist_dashboard
node_middleware -->|"gate"| node_pages_student_dashboard
node_middleware -->|"gate"| node_pages_tutor_dashboard
node_middleware -->|"gate"| node_pages_universidad_dashboard
node_middleware -->|"gate"| node_pages_admin_index
node_lib_auth -.->|"redirects"| node_pages_admin_index
node_supabase_client -->|"data access"| node_use_clients
node_supabase_client -->|"data access"| node_use_student_patients
node_supabase_client -->|"db/storage"| node_api_clients_create
node_supabase_client -->|"db/storage"| node_api_admin_metrics
node_schemas_appointments -->|"validate"| node_components_anthro_form
node_use_clients -->|"feed UI"| node_components_anthro_form
node_use_clients -->|"feed UI"| node_components_diet_plan_builder
node_use_student_patients -->|"feed UI"| node_components_student_field_trip
node_use_student_patients -->|"feed UI"| node_components_tutor_review
node_components_notification_center -.->|"surface"| node_pages_nutritionist_dashboard
node_components_diet_plan_builder -->|"export"| node_utils_diet_pdf
node_theme -.->|"style base"| node_styles_globals
node_api_jobs_reminders -->|"trigger"| node_edge_reminders
node_supabase_migrations -->|"define"| node_supabase_schema
node_supabase_migrations -.->|"persisted model"| node_supabase_client
node_api_admin_metrics -->|"serve"| node_components_admin_metrics
node_api_auth_mock -.->|"dev path"| node_pages_signin

click node_pages_index "https://github.com/porta0922/nutripro/blob/main/pages/index.tsx"
click node_pages_signin "https://github.com/porta0922/nutripro/blob/main/pages/auth/signin.tsx"
click node_pages_nutritionist_dashboard "https://github.com/porta0922/nutripro/blob/main/pages/nutritionist/dashboard.tsx"
click node_pages_student_dashboard "https://github.com/porta0922/nutripro/blob/main/pages/student/dashboard.tsx"
click node_pages_tutor_dashboard "https://github.com/porta0922/nutripro/blob/main/pages/tutor/dashboard.tsx"
click node_pages_universidad_dashboard "https://github.com/porta0922/nutripro/blob/main/pages/universidad/dashboard.tsx"
click node_pages_admin_index "https://github.com/porta0922/nutripro/blob/main/pages/admin/index.tsx"
click node_client_dashboard "https://github.com/porta0922/nutripro/blob/main/pages/client/dashboard.tsx"
click node_middleware "https://github.com/porta0922/nutripro/blob/main/middleware.ts"
click node_lib_auth "https://github.com/porta0922/nutripro/blob/main/lib/auth.tsx"
click node_supabase_client "https://github.com/porta0922/nutripro/blob/main/lib/supabaseClient.ts"
click node_use_clients "https://github.com/porta0922/nutripro/blob/main/hooks/useClients.ts"
click node_use_student_patients "https://github.com/porta0922/nutripro/blob/main/hooks/useStudentPatients.ts"
click node_schemas_appointments "https://github.com/porta0922/nutripro/blob/main/schemas/appointments.ts"
click node_components_notification_center "https://github.com/porta0922/nutripro/blob/main/components/NotificationCenter.tsx"
click node_components_diet_plan_builder "https://github.com/porta0922/nutripro/blob/main/components/DietPlanBuilder.tsx"
click node_components_anthro_form "https://github.com/porta0922/nutripro/blob/main/components/AnthropometricForm.tsx"
click node_components_student_field_trip "https://github.com/porta0922/nutripro/blob/main/components/student/FieldTripForm.tsx"
click node_components_tutor_review "https://github.com/porta0922/nutripro/blob/main/components/tutor/ReviewMealPlanModal.tsx"
click node_components_admin_metrics "https://github.com/porta0922/nutripro/blob/main/components/admin/AdminMetricsCard.tsx"
click node_utils_diet_pdf "https://github.com/porta0922/nutripro/blob/main/utils/dietPlanPDF.ts"
click node_theme "https://github.com/porta0922/nutripro/blob/main/theme.ts"
click node_styles_globals "https://github.com/porta0922/nutripro/blob/main/styles/globals.css"
click node_api_admin_metrics "https://github.com/porta0922/nutripro/blob/main/pages/api/admin/metrics.ts"
click node_api_clients_create "https://github.com/porta0922/nutripro/blob/main/pages/api/clients/create.ts"
click node_api_jobs_reminders "https://github.com/porta0922/nutripro/blob/main/pages/api/jobs/process-reminders.ts"
click node_api_auth_mock "https://github.com/porta0922/nutripro/blob/main/pages/api/auth/mock.ts"
click node_edge_reminders "https://github.com/porta0922/nutripro/blob/main/supabase/functions/send-appointment-reminders/index.ts"
click node_supabase_migrations "https://github.com/porta0922/nutripro/blob/main/supabase/migrations/1 - initial schema.sql"
click node_supabase_schema "https://github.com/porta0922/nutripro/blob/main/supabase/schema.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_pages_index,node_pages_signin,node_pages_nutritionist_dashboard,node_pages_student_dashboard,node_pages_tutor_dashboard,node_pages_universidad_dashboard,node_pages_admin_index,node_client_dashboard,node_theme,node_styles_globals toneBlue
class node_components_notification_center,node_components_diet_plan_builder,node_components_anthro_form,node_components_student_field_trip,node_components_tutor_review,node_components_admin_metrics,node_utils_diet_pdf toneAmber
class node_middleware,node_lib_auth,node_supabase_client,node_use_clients,node_use_student_patients,node_schemas_appointments toneMint
class node_api_admin_metrics,node_api_clients_create,node_api_jobs_reminders,node_api_auth_mock,node_edge_reminders,node_supabase_migrations,node_supabase_schema toneRose
```

## Components

### App UI

Pages, route trees, and shared client-side interface composition.

- [Landing](https://github.com/porta0922/nutripro/blob/main/pages/index.tsx): Next page · Public entry point and navigation into the authenticated flows. · `pages/index.tsx`
- [Sign in](https://github.com/porta0922/nutripro/blob/main/pages/auth/signin.tsx): Auth page · Unified login entry that branches users into role-specific app areas. · `pages/auth/signin.tsx`
- [Nutri dashboard](https://github.com/porta0922/nutripro/blob/main/pages/nutritionist/dashboard.tsx): Role dashboard · Primary workspace for nutritionist clinical workflows. · `pages/nutritionist/dashboard.tsx`
- [Student dashboard](https://github.com/porta0922/nutripro/blob/main/pages/student/dashboard.tsx): Role dashboard · Practice-oriented workspace for student users. · `pages/student/dashboard.tsx`
- [Tutor dashboard](https://github.com/porta0922/nutripro/blob/main/pages/tutor/dashboard.tsx): Role dashboard · Tutor workspace for reviews, students, and practice patients. · `pages/tutor/dashboard.tsx`
- [University dashboard](https://github.com/porta0922/nutripro/blob/main/pages/universidad/dashboard.tsx): Role dashboard · Institutional workspace for university administration. · `pages/universidad/dashboard.tsx`
- [Admin area](https://github.com/porta0922/nutripro/blob/main/pages/admin/index.tsx): Privileged area · Highest-privilege platform administration and subscription boundary. · `pages/admin/index.tsx`
- [Client view](https://github.com/porta0922/nutripro/blob/main/pages/client/dashboard.tsx): Patient portal · Patient-facing dashboard for appointments, plans, and progress. · `pages/client/dashboard.tsx`
- [Theme](https://github.com/porta0922/nutripro/blob/main/theme.ts): UI theme · Global visual tokens and app-wide styling configuration. · `theme.ts`
- [Global styles](https://github.com/porta0922/nutripro/blob/main/styles/globals.css): Stylesheet · Base CSS for application-wide presentation. · `styles/globals.css`

### Domain Modules

Reusable clinical, academic, and admin-facing feature components and hooks.

- [Notifications](https://github.com/porta0922/nutripro/blob/main/components/NotificationCenter.tsx): UI widget · In-app notification center and message surface. · `components/NotificationCenter.tsx`
- [Diet builder](https://github.com/porta0922/nutripro/blob/main/components/DietPlanBuilder.tsx): Clinical widget · Interactive diet-plan composition and template workflow. · `components/DietPlanBuilder.tsx`
- [Anthro form](https://github.com/porta0922/nutripro/blob/main/components/AnthropometricForm.tsx): Clinical form · Capture and edit anthropometric measurements. · `components/AnthropometricForm.tsx`
- [Field trips](https://github.com/porta0922/nutripro/blob/main/components/student/FieldTripForm.tsx): Academic form · Student practice workflow for field trips and related records. · `components/student/FieldTripForm.tsx`
- [Meal review](https://github.com/porta0922/nutripro/blob/main/components/tutor/ReviewMealPlanModal.tsx): Academic widget · Tutor review interface for meal plans and student practice work. · `components/tutor/ReviewMealPlanModal.tsx`
- [Admin metrics](https://github.com/porta0922/nutripro/blob/main/components/admin/AdminMetricsCard.tsx): Admin widget · Platform metrics and administrative overview cards. · `components/admin/AdminMetricsCard.tsx`
- [PDF export](https://github.com/porta0922/nutripro/blob/main/utils/dietPlanPDF.ts): Export util · Generates diet and report PDFs for clinical workflows. · `utils/dietPlanPDF.ts`

### Auth & Data

Authentication, client data access, validation, and shared runtime state.

- [Route guard](https://github.com/porta0922/nutripro/blob/main/middleware.ts): Edge middleware · Enforces route protection and role-aware access control. · `middleware.ts`
- [Session auth](https://github.com/porta0922/nutripro/blob/main/lib/auth.tsx): Auth client · Session state, redirects, and client-side auth coordination. · `lib/auth.tsx`
- [Supabase client](https://github.com/porta0922/nutripro/blob/main/lib/supabaseClient.ts): DB client · Shared Supabase JS entry for database and storage access. · `lib/supabaseClient.ts`
- [Clients hook](https://github.com/porta0922/nutripro/blob/main/hooks/useClients.ts): Data hook · Fetch and mutation logic for nutritionist client records. · `hooks/useClients.ts`
- [Student hook](https://github.com/porta0922/nutripro/blob/main/hooks/useStudentPatients.ts): Data hook · Practice-patient access and updates for student workflows. · `hooks/useStudentPatients.ts`
- [Appointment schema](https://github.com/porta0922/nutripro/blob/main/schemas/appointments.ts): Validation schema · Client-side validation rules for appointment forms. · `schemas/appointments.ts`

### Platform

Supabase backend, server routes, scheduled jobs, and deployment concerns.

- [Metrics API](https://github.com/porta0922/nutripro/blob/main/pages/api/admin/metrics.ts): Admin API · Server-side endpoint for privileged admin reporting. · `pages/api/admin/metrics.ts`
- [Client API](https://github.com/porta0922/nutripro/blob/main/pages/api/clients/create.ts): App API · Server-side helper for creating and inviting clients. · `pages/api/clients/create.ts`
- [Reminder job](https://github.com/porta0922/nutripro/blob/main/pages/api/jobs/process-reminders.ts): Job API · HTTP-triggered job execution for appointment reminders. · `pages/api/jobs/process-reminders.ts`
- [Mock auth](https://github.com/porta0922/nutripro/blob/main/pages/api/auth/mock.ts): Dev API · Development-only authentication bypass for local testing. · `pages/api/auth/mock.ts`
- [Reminder function](https://github.com/porta0922/nutripro/blob/main/supabase/functions/send-appointment-reminders/index.ts): Supabase Edge Function · Scheduled automation that sends appointment reminders. · `supabase/functions/send-appointment-reminders/index.ts`
- [Schema & RLS](https://github.com/porta0922/nutripro/blob/HEAD/supabase/migrations/1%20-%20initial%20schema.sql): SQL migrations · Database schema, permissions, policies, and feature tables. · `supabase/migrations/1 - initial schema.sql`
- [DB schema](https://github.com/porta0922/nutripro/blob/main/supabase/schema.sql): SQL schema · Consolidated database schema and reference definitions. · `supabase/schema.sql`

## Connections

- Landing → Sign in: start auth · Public users move from landing into the sign-in flow.
- Sign in → Session auth: session · Authentication pages rely on shared session and redirect logic.
- Session auth → Route guard: protect routes · Client auth state aligns with route-layer access control.
- Route guard → Nutri dashboard: gate · Role-protected navigation into nutritionist routes.
- Route guard → Student dashboard: gate · Role-protected navigation into student routes.
- Route guard → Tutor dashboard: gate · Role-protected navigation into tutor routes.
- Route guard → University dashboard: gate · Role-protected navigation into university routes.
- Route guard → Admin area: gate · Highest-privilege routes are protected at the edge.
- Session auth → Admin area: redirects · Role-aware redirects steer users to the correct area.
- Supabase client → Clients hook: data access · Client hooks consume the shared Supabase client.
- Supabase client → Student hook: data access · Practice data hooks use the shared Supabase client.
- Supabase client → Client API: db/storage · API routes use the shared client for server-side operations.
- Supabase client → Metrics API: db/storage · Admin endpoints read privileged data through Supabase.
- Appointment schema → Anthro form: validate · Forms are validated before submission.
- Clients hook → Anthro form: feed UI · Clinical forms and lists are driven by client data hooks.
- Clients hook → Diet builder: feed UI · Diet workflows read and mutate client-linked records.
- Student hook → Field trips: feed UI · Student practice components consume student-patient state.
- Student hook → Meal review: feed UI · Tutor review screens consume practice-patient state.
- Notifications → Nutri dashboard: surface · Notifications are a shared cross-cutting UI surface.
- Diet builder → PDF export: export · Diet plans can be rendered into PDF outputs.
- Theme → Global styles: style base · Global theming and CSS form the shared presentation layer.
- Reminder job → Reminder function: trigger · The app-side job endpoint orchestrates the scheduled function.
- Schema & RLS → DB schema: define · Migrations and schema files together define the database boundary.
- Schema & RLS → Supabase client: persisted model · The client reads and writes the schema enforced by migrations and RLS.
- Metrics API → Admin metrics: serve · Admin UI is backed by privileged server data.
- Mock auth → Sign in: dev path · Local testing can bypass production auth flow.
