# francocabellodev/lifefit architecture

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

- Interactive diagram: https://gitdiagram.com/francocabellodev/lifefit
- Repository: https://github.com/francocabellodev/lifefit

## Overview

1. **Repository shape: two-tier SaaS product**
   - The repo is split into `backend/` and `frontend/`.
   - The backend is a Django REST-style API, and the frontend is a Next.js App Router client.
   - The product is a multi-tenant gym platform with two major surfaces: a gym operator/member experience and a global SaaS admin console.

2. **Backend runtime and deployment boundary**
   - `backend/` is a Django project (`config/`) running on Python 3.11.
   - It is configured for PostgreSQL by default, with a SQLite fallback if DB env vars are absent.
   - Deployment artifacts include `Procfile`, `build.sh`, and `railway.toml`, which suggests cloud deployment with standard web process startup.
   - API entrypoints are organized through Django `urls.py` per app, plus the project-level router in `config/urls.py`.

3. **Core domain decomposition in Django apps**
   - The backend is split into business-domain apps rather than a single monolith:
     - `accounts` for the custom user model and profile data.
     - `gyms` for gym tenancy, branches, staff assignments, check-ins, appointments, notifications, and gym-level subscription/payment data.
     - `subscriptions` for SaaS subscription plans and payments.
     - `workouts` for routines, exercises, sessions, weekly plans, and logging.
     - `nutrition` for nutrition plans, foods, meals, meal logs, and approvals.
     - `challenges` for challenges, badges, participation, and verification.
     - `gamification` for points and rewards.
     - `core` for cross-cutting concerns such as permissions, audit logs, feature flags, announcements, and shared constants.
   - This modular split is the main architectural boundary on the server side.

4. **Cross-cutting backend layer**
   - `core/` holds shared infrastructure used by multiple apps: permissions, filters, serializers, tasks, and email templates.
   - It also contains seeded/demo data commands and feature-flag seeding, indicating that the app supports configurable rollout or plan-based gating.
   - `core/templates/emails/` contains onboarding email templates for athletes, gyms, and staff, so email is part of the backend workflow.

5. **Tenant and role model**
   - The system is gym-aware: many models and migrations reference `gym_id`, branches, and gym-scoped indexes.
   - The role model is important: the project distinguishes super admin/SaaS operator, gym staff, coaches, nutritionists, and athletes.
   - Access control is enforced through Django permissions and role-aware logic in `core/permissions.py` and frontend route guards.
   - This is not a single-user app; almost every feature is partitioned by role and by gym tenant.

6. **Key business flows on the backend**
   - **Identity/onboarding:** `accounts` manages user creation, profile enrichment, soft deletion, and default admin bootstrap.
   - **Membership and finance:** `subscriptions` and parts of `gyms` handle plans, gym subscriptions, and payments.
   - **Training:** `workouts` stores routines and sessions, plus point rewards for completed workouts.
   - **Nutrition:** `nutrition` covers plans, meal templates, food items, daily logging, and approval status for logs/photos.
   - **Challenges/gamification:** `challenges` and `gamification` award points, track challenge participation, and manage rewards.
   - **Operations:** `gyms` also handles check-ins, staff assignments, availability, appointments, and notifications.

7. **Operational jobs and maintenance flows**
   - The backend includes multiple Django management commands for seeding and synchronization:
     - default admin creation,
     - demo data seeding,
     - plans/payments/challenges/nutrition/workout seeds,
     - challenge closing and progress sync.
   - This indicates that some domain state is periodically reconciled or initialized through server-side jobs rather than only interactive requests.
   - `core/tasks.py` exists, but the tree does not show a separate worker stack; any async processing appears to be lightweight or app-managed within Django.

8. **Frontend structure and surface areas**
   - `frontend/` is a Next.js app using the App Router (`src/app`).
   - The routing is heavily segmented by experience:
     - `/[gymId]/panel/...` for gym-specific dashboards and member/staff tools.
     - `/panel-saas/...` for the SaaS operator console.
     - `/ingresar`, `/registrarse`, `/unirse`, and Google callback routes for auth and onboarding.
   - Shared UI is built from reusable components in `src/components/`, including dashboard, coach, nutritionist, admin, team, workout, and nutrition modules.

9. **Frontend data access and protection**
   - The frontend talks to the backend through `src/lib/api.ts` and related auth utilities.
   - Role and feature boundaries are enforced in the UI with hooks like `useDashboardAuth`, `useRoleGuard`, `useFeatureGuard`, and assignment mutation hooks.
   - This means the frontend is not just presentation; it also enforces navigation and visibility rules based on user role, gym context, and feature availability.

10. **Frontend domain mapping to backend modules**
   - The Next.js pages mirror the backend domains closely:
     - training pages for routines, adherence, and exercises map to `workouts`,
     - nutrition pages map to `nutrition`,
     - challenges and rewards map to `challenges`/`gamification`,
     - finances/subscriptions map to `subscriptions` and gym payment logic,
     - team and scheduling pages map to `gyms`.
   - The `[gymId]` route segment makes tenant context explicit in the UI and is a key architecture clue for diagrams.

11. **Authentication and onboarding flow**
   - The readme shows email/password login plus Google OAuth integration.
   - Frontend auth pages include login, registration, gym selection, and Google callback handling.
   - Backend env vars include Google client ID/secret and redirect URI, so the auth flow spans both frontend and backend.
   - After login, users are redirected based on role, with super-admins going to the SaaS console and gym users to their gym dashboard.

12. **Schema and design artifacts**
   - The repo includes DBML and SQL ERD files (`database_diagram.dbml`, `erd_lifefit.dbml`, `erd_modulos/*`), which document the domain decomposition and relationships.
   - These artifacts are useful for understanding the normalized schema around modules like memberships, workouts, nutrition, gamification, and SaaS administration.
   - For diagramming, the ERD assets reinforce that the system is intentionally modular and tenant-aware.

13. **What to show in an architecture diagram**
   - Put the browser/frontends on one side: Next.js app, split into gym portal and SaaS admin.
   - Put Django API as the middle layer, split into the domain apps above.
   - Put PostgreSQL as the primary shared data store.
   - Show Google OAuth as an external auth dependency, plus email delivery for onboarding/notifications.
   - Show management commands/maintenance jobs as an operational lane alongside the main request path.

Main entry points: [`backend/config/urls.py`](https://github.com/francocabellodev/lifefit/blob/main/backend/config/urls.py) (API router), [`backend/core/management/commands`](https://github.com/francocabellodev/lifefit/tree/main/backend/core/management/commands) (Management jobs), [`frontend/src/app/[gymId]/panel`](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/[gymId]/panel) (Gym portal), [`frontend/src/app/panel-saas`](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/panel-saas) (SaaS console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_gym_portal["Gym portal<br/>nextjs surface"]
  node_saas_console["SaaS console<br/>nextjs surface"]
  node_auth_onboarding["Auth flow<br/>nextjs routes"]
  node_frontend_ui["Shared UI<br/>components"]
  node_frontend_access["Route guards<br/>hooks/lib"]
end

subgraph group_backend["Backend"]
  node_api_gateway["API router<br/>django urls<br/>[urls.py]"]
  node_core["Core<br/>shared infra"]
  node_accounts["Accounts<br/>identity app"]
  node_gyms["Gyms<br/>tenant ops app"]
  node_subscriptions["Subscriptions<br/>saas billing app"]
  node_workouts["Workouts<br/>training app"]
  node_nutrition["Nutrition"]
  node_challenges["Challenges<br/>engagement app"]
  node_gamification["Gamification<br/>points app"]
  node_deploy["Deploy files<br/>runtime/deploy"]
  node_jobs["Management jobs<br/>ops commands"]
end

subgraph group_external["External"]
  node_postgres[("PostgreSQL<br/>primary datastore")]
  node_sqlite_fallback[("SQLite fallback<br/>local datastore")]
  node_google_oauth(("Google OAuth<br/>external auth"))
  node_email_delivery(("Email delivery<br/>notification channel"))
end

node_browser -->|"uses"| node_gym_portal
node_browser -->|"uses"| node_saas_console
node_browser -->|"starts"| node_auth_onboarding
node_gym_portal -->|"composes"| node_frontend_ui
node_saas_console -->|"composes"| node_frontend_ui
node_gym_portal -->|"guards"| node_frontend_access
node_saas_console -->|"guards"| node_frontend_access
node_auth_onboarding -->|"auth"| node_google_oauth
node_frontend_access -->|"calls"| node_api_gateway
node_api_gateway -->|"routes"| node_core
node_api_gateway -->|"routes"| node_accounts
node_api_gateway -->|"routes"| node_gyms
node_api_gateway -->|"routes"| node_subscriptions
node_api_gateway -->|"routes"| node_workouts
node_api_gateway -->|"routes"| node_nutrition
node_api_gateway -->|"routes"| node_challenges
node_api_gateway -->|"routes"| node_gamification
node_core -->|"persists"| node_postgres
node_accounts -->|"persists"| node_postgres
node_gyms -->|"persists"| node_postgres
node_subscriptions -->|"persists"| node_postgres
node_workouts -->|"persists"| node_postgres
node_nutrition -->|"persists"| node_postgres
node_challenges -->|"persists"| node_postgres
node_gamification -->|"persists"| node_postgres
node_core -->|"sends"| node_email_delivery
node_deploy -->|"starts"| node_api_gateway
node_jobs -->|"maintains"| node_gyms
node_jobs -->|"maintains"| node_workouts
node_jobs -->|"maintains"| node_nutrition
node_jobs -->|"maintains"| node_subscriptions
node_jobs -->|"maintains"| node_challenges
node_api_gateway -.->|"falls back to"| node_sqlite_fallback

click node_gym_portal "https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/[gymId]/panel"
click node_saas_console "https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/panel-saas"
click node_auth_onboarding "https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/ingresar"
click node_frontend_ui "https://github.com/francocabellodev/lifefit/tree/main/frontend/src/components"
click node_frontend_access "https://github.com/francocabellodev/lifefit/tree/main/frontend/src/hooks"
click node_api_gateway "https://github.com/francocabellodev/lifefit/blob/main/backend/config/urls.py"
click node_core "https://github.com/francocabellodev/lifefit/tree/main/backend/core"
click node_accounts "https://github.com/francocabellodev/lifefit/tree/main/backend/accounts"
click node_gyms "https://github.com/francocabellodev/lifefit/tree/main/backend/gyms"
click node_subscriptions "https://github.com/francocabellodev/lifefit/tree/main/backend/subscriptions"
click node_workouts "https://github.com/francocabellodev/lifefit/tree/main/backend/workouts"
click node_nutrition "https://github.com/francocabellodev/lifefit/tree/main/backend/nutrition"
click node_challenges "https://github.com/francocabellodev/lifefit/tree/main/backend/challenges"
click node_gamification "https://github.com/francocabellodev/lifefit/tree/main/backend/gamification"
click node_deploy "https://github.com/francocabellodev/lifefit/tree/main/backend/Procfile"
click node_jobs "https://github.com/francocabellodev/lifefit/tree/main/backend/core/management/commands"

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_browser,node_gym_portal,node_saas_console,node_auth_onboarding,node_frontend_ui,node_frontend_access toneBlue
class node_api_gateway,node_core,node_accounts,node_gyms,node_subscriptions,node_workouts,node_nutrition,node_challenges,node_gamification,node_deploy,node_jobs toneAmber
class node_postgres,node_sqlite_fallback,node_google_oauth,node_email_delivery toneMint
```

## Components

### Frontend

Next.js App Router client with tenant and SaaS operator surfaces

- **Browser**: client · User entry point for both gym and SaaS experiences
- [Gym portal](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/[gymId]/panel): nextjs surface · Tenant-scoped member, coach, and operator UI under /[gymId]/panel · `frontend/src/app/[gymId]/panel`
- [SaaS console](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/panel-saas): nextjs surface · Global admin UI under /panel-saas · `frontend/src/app/panel-saas`
- [Auth flow](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/app/ingresar): nextjs routes · Login, registration, gym join, and Google callback routes · `frontend/src/app/ingresar`
- [Shared UI](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/components): components · Reusable dashboard, team, training, nutrition, and admin components · `frontend/src/components`
- [Route guards](https://github.com/francocabellodev/lifefit/tree/main/frontend/src/hooks): hooks/lib · Client-side auth, role, and feature gating plus API access helpers · `frontend/src/hooks`

### Backend

Django API split into domain apps and shared core services

- [API router](https://github.com/francocabellodev/lifefit/blob/main/backend/config/urls.py): django urls · Project-level request routing into app URL modules · `backend/config/urls.py`
- [Core](https://github.com/francocabellodev/lifefit/tree/main/backend/core): shared infra · Permissions, audit logs, feature flags, constants, tasks, and shared serializers · `backend/core`
- [Accounts](https://github.com/francocabellodev/lifefit/tree/main/backend/accounts): identity app · Custom user model, profiles, soft delete, and admin bootstrap · `backend/accounts`
- [Gyms](https://github.com/francocabellodev/lifefit/tree/main/backend/gyms): tenant ops app · Gym tenancy, branches, staff, check-ins, appointments, messages, and gym payments · `backend/gyms`
- [Subscriptions](https://github.com/francocabellodev/lifefit/tree/main/backend/subscriptions): saas billing app · SaaS plans, subscriptions, and payments · `backend/subscriptions`
- [Workouts](https://github.com/francocabellodev/lifefit/tree/main/backend/workouts): training app · Routines, exercises, weekly plans, sessions, logs, and workout rewards · `backend/workouts`
- [Nutrition](https://github.com/francocabellodev/lifefit/tree/main/backend/nutrition): nutrition app · Nutrition plans, foods, meals, meal logs, and approvals · `backend/nutrition`
- [Challenges](https://github.com/francocabellodev/lifefit/tree/main/backend/challenges): engagement app · Challenges, badges, participation, verification, and challenge lifecycle jobs · `backend/challenges`
- [Gamification](https://github.com/francocabellodev/lifefit/tree/main/backend/gamification): points app · Points, rewards, redemption, and progression tracking · `backend/gamification`
- [Deploy files](https://github.com/francocabellodev/lifefit/tree/main/backend/Procfile): runtime/deploy · Procfile, build script, and Railway config for cloud startup · `backend/Procfile`
- [Management jobs](https://github.com/francocabellodev/lifefit/tree/main/backend/core/management/commands): ops commands · Seed, sync, and maintenance commands across backend apps · `backend/core/management/commands`

### External

Outside services and runtime dependencies

- **PostgreSQL**: primary datastore · Main shared relational database for tenants, users, plans, logs, and billing
- **SQLite fallback**: local datastore · Fallback database when production DB env vars are absent
- **Google OAuth**: external auth · OAuth identity provider used by frontend login callback and backend config
- **Email delivery**: notification channel · Onboarding and operational email templates for athletes, gyms, and staff

## Connections

- Browser → Gym portal: uses · Gym-scoped user experience
- Browser → SaaS console: uses · Global operator console
- Browser → Auth flow: starts · Authentication and join flow
- Gym portal → Shared UI: composes · Builds domain screens from reusable components
- SaaS console → Shared UI: composes · Builds admin screens from reusable components
- Gym portal → Route guards: guards · Enforces role and feature visibility in the UI
- SaaS console → Route guards: guards · Restricts operator navigation and actions
- Auth flow → Google OAuth: auth · Google sign-in callback integration
- Route guards → API router: calls · Authenticated API requests
- API router → Core: routes · Shared infrastructure endpoints and permissions
- API router → Accounts: routes · Identity and profile endpoints
- API router → Gyms: routes · Tenant operations endpoints
- API router → Subscriptions: routes · Billing and plan endpoints
- API router → Workouts: routes · Training endpoints
- API router → Nutrition: routes · Nutrition endpoints
- API router → Challenges: routes · Challenge endpoints
- API router → Gamification: routes · Points and rewards endpoints
- Core → PostgreSQL: persists · Shared tables and audit/feature data
- Accounts → PostgreSQL: persists · Users and profile data
- Gyms → PostgreSQL: persists · Tenancy, check-ins, appointments, and gym billing
- Subscriptions → PostgreSQL: persists · SaaS plans and payments
- Workouts → PostgreSQL: persists · Routines, sessions, and logs
- Nutrition → PostgreSQL: persists · Plans, meals, and approvals
- Challenges → PostgreSQL: persists · Challenges and participation state
- Gamification → PostgreSQL: persists · Points and reward records
- Core → Email delivery: sends · Onboarding and notification emails
- Deploy files → API router: starts · Web process startup and deployment entrypoints
- Management jobs → Gyms: maintains · Seed and sync operational data
- Management jobs → Workouts: maintains · Seed initial workout data
- Management jobs → Nutrition: maintains · Seed nutrition plans
- Management jobs → Subscriptions: maintains · Seed plans and payments
- Management jobs → Challenges: maintains · Seed and close challenges
- API router → SQLite fallback: falls back to · Local database when PostgreSQL env vars are missing
