How francocabellodev/lifefit works
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: urls.py API router · commands Management jobs · panel Gym portal · panel-saas SaaS console
Components 21
Frontend
Next.js App Router client with tenant and SaaS operator surfaces
- Browser · User entry point for both gym and SaaS experiences
- Gym portal · Tenant-scoped member, coach, and operator UI under /[gymId]/panel
frontend/src/app/[gymId]/panel - SaaS console · Global admin UI under /panel-saas
frontend/src/app/panel-saas - Auth flow · Login, registration, gym join, and Google callback routes
frontend/src/app/ingresar - Shared UI · Reusable dashboard, team, training, nutrition, and admin components
frontend/src/components - Route guards · 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 · Project-level request routing into app URL modules
backend/config/urls.py - Core · Permissions, audit logs, feature flags, constants, tasks, and shared serializers
backend/core - Accounts · Custom user model, profiles, soft delete, and admin bootstrap
backend/accounts - Gyms · Gym tenancy, branches, staff, check-ins, appointments, messages, and gym payments
backend/gyms - Subscriptions · SaaS plans, subscriptions, and payments
backend/subscriptions - Workouts · Routines, exercises, weekly plans, sessions, logs, and workout rewards
backend/workouts - Nutrition · Nutrition plans, foods, meals, meal logs, and approvals
backend/nutrition - Challenges · Challenges, badges, participation, verification, and challenge lifecycle jobs
backend/challenges - Gamification · Points, rewards, redemption, and progression tracking
backend/gamification - Deploy files · Procfile, build script, and Railway config for cloud startup
backend/Procfile - Management jobs · Seed, sync, and maintenance commands across backend apps
backend/core/management/commands
External
Outside services and runtime dependencies
- PostgreSQL · Main shared relational database for tenants, users, plans, logs, and billing
- SQLite fallback · Fallback database when production DB env vars are absent
- Google OAuth · OAuth identity provider used by frontend login callback and backend config
- Email delivery · Onboarding and operational email templates for athletes, gyms, and staff
Connections 33
- 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