fitaiProto/nextsteps.md

Next Steps for FitAI Solution

Last Updated: January 2025
Version: 2.1.0

---

Current State Analysis

✅ Infrastructure Completed

• Database: SQLite with Drizzle ORM fully implemented in packages/database
• Schemas Defined: users, clients, payments, attendance, notifications
• Database Location: apps/admin/data/fitai.db
• Admin App: Next.js with custom database abstraction layer (DatabaseFactory)
• Mobile App: React Native/Expo with tab navigation and authentication
• Authentication: Clerk fully integrated for both admin and mobile apps

✅ Features Already Implemented

• Clerk Authentication: Complete sign-in/sign-up flows with email verification
• Admin Dashboard: Protected routes with Clerk middleware
• Mobile App: Native authentication screens with Clerk Expo SDK
• User management API with full CRUD operations (GET, POST, PUT, DELETE)
• Bulk user operations (bulk delete)
• User filtering by role (admin, trainer, client)
• Client profile association with users
• Analytics dashboard with AG Charts (line, pie, bar charts)
• AG Grid for advanced user data visualization
• Protected routes and session management
• Secure credential storage with expo-secure-store

⚠️ Schemas Exist But Not Implemented

The following database schemas are defined but have NO API endpoints or UI:

1. Payments - Full schema but no endpoints
2. Attendance - Full schema but no endpoints
3. Notifications - Full schema but no endpoints

---

Phase 1: Complete Core Features (HIGH PRIORITY)

1.0 Clerk Authentication Integration ✅ COMPLETED

Status: Fully implemented and documented
Priority: CRITICAL

Completed Tasks:

• ✅ Installed @clerk/nextjs for admin app
• ✅ Installed @clerk/clerk-expo for mobile app
• ✅ Created ClerkProvider wrapper in admin layout
• ✅ Implemented Clerk middleware for route protection
• ✅ Created sign-in and sign-up screens for mobile app
• ✅ Updated profile screen to use Clerk user data
• ✅ Added authentication flow with email verification
• ✅ Created environment variable templates (.env.example)
• ✅ Wrote comprehensive setup guide (CLERK_SETUP.md)
• ✅ Updated README with authentication instructions
• ✅ Implemented protected routes in both apps

Next Steps for Authentication:

• ✅ Sync Clerk users with database via webhooks - COMPLETED
• Add social login providers (Google, GitHub)
• Implement user roles in Clerk metadata
• Add multi-factor authentication (MFA)
• Set up organization/tenant support for gym chains

Webhook Integration Completed:

• ✅ Created webhook handler at /api/webhooks with Svix signature verification
• ✅ Implemented user sync for user.created, user.updated, user.deleted events
• ✅ Updated database schema to make password field optional
• ✅ Created helper utilities for role management (clerk-helpers.ts)
• ✅ Built admin API endpoint for setting user roles (/api/admin/set-role)
• ✅ Wrote comprehensive setup guide (CLERK_WEBHOOK_SETUP.md)
• ✅ Created detailed testing guide (WEBHOOK_TESTING_GUIDE.md)
• ✅ Installed svix package for webhook verification
• ✅ Role syncing from Clerk public_metadata to database

---

Phase 1: Complete Core Features (HIGH PRIORITY) - Continued

1.1 Payment System Implementation

Status: Schema exists, needs API + UI
Priority: CRITICAL

Backend Tasks:

• Create API endpoints in apps/admin/src/app/api/payments/:
  • POST /api/payments - Create new payment record
  • GET /api/payments - List payments (with filtering by clientId, status, date range)
  • GET /api/payments/[id] - Get single payment details
  • PUT /api/payments/[id] - Update payment (e.g., mark as paid)
  • DELETE /api/payments/[id] - Delete payment record
  • GET /api/payments/overdue - Get overdue payments
• Implement payment validation with Zod
• Add payment statistics endpoint for dashboard

Admin Dashboard Tasks:

• Create /apps/admin/src/app/payments/page.tsx:
  • Payment list with AG Grid (sortable, filterable)
  • Payment status indicators (pending, completed, failed, refunded)
  • Add new payment form
  • Edit payment functionality
  • Mark as paid/failed action buttons
• Add payment charts to analytics dashboard:
  • Monthly revenue chart
  • Payment status distribution pie chart
  • Overdue payments alert widget
• Create payment detail modal/page
• Add CSV export for payment records

Mobile App Tasks:

• Create payment history screen at apps/mobile/src/app/(tabs)/payments.tsx
• Display user's payment history
• Show payment status with color coding
• Add payment notifications badge
• Enable payment receipt viewing

1.2 Attendance Tracking System

Status: Schema exists, needs API + UI
Priority: CRITICAL

Backend Tasks:

• Create API endpoints in apps/admin/src/app/api/attendance/:
  • POST /api/attendance/check-in - Record check-in
  • PUT /api/attendance/[id]/check-out - Record check-out
  • GET /api/attendance - List attendance records (filter by client, date range, type)
  • GET /api/attendance/stats - Attendance statistics
  • GET /api/attendance/active - Currently checked-in clients
• Implement attendance validation logic
• Add attendance analytics endpoint

Admin Dashboard Tasks:

• Create /apps/admin/src/app/attendance/page.tsx:
  • Real-time attendance view (who's currently in the gym)
  • Attendance history with AG Grid
  • Attendance statistics (daily, weekly, monthly)
  • Peak hours visualization
  • Client attendance patterns
• Add attendance widget to main dashboard
• Create attendance reports with export functionality

Mobile App Tasks:

• Implement check-in/check-out on apps/mobile/src/app/(tabs)/attendance.tsx:
  • Large check-in button with status indicator
  • Display current check-in status
  • Show check-in/check-out history
  • Display total gym visits this month
  • Add check-in time display
• Add QR code scanning for check-in (Phase 1.3)
• Show attendance streaks and gamification

1.3 Notifications System

Status: Schema exists, needs implementation
Priority: HIGH

Backend Tasks:

• Create API endpoints in apps/admin/src/app/api/notifications/:
  • POST /api/notifications - Create notification
  • GET /api/notifications - List user notifications
  • PUT /api/notifications/[id]/read - Mark as read
  • DELETE /api/notifications/[id] - Delete notification
  • POST /api/notifications/bulk - Send bulk notifications
• Implement notification triggers:
  • Payment due reminders (7 days, 3 days, 1 day before)
  • Payment overdue alerts
  • Attendance milestones
  • Membership expiration warnings

Admin Dashboard Tasks:

• Create notification management page
• Add notification creation form (send to specific user or role)
• Display notification history and delivery status
• Add notification templates system

Mobile App Tasks:

• Implement notification badge on tabs
• Create notifications screen
• Add notification preferences screen
• Integrate push notifications with Expo Notifications
• Handle notification tap actions

---

Phase 2: Enhanced Features (MEDIUM PRIORITY)

2.1 Advanced User Management

• Add user profile editing (admin and self-service)
• Implement user deactivation (soft delete)
• Add user activity logs
• Implement advanced search (by name, email, phone, membership type)
• Add user import from CSV
• Create user onboarding flow

2.2 Membership Management

• Create membership plans configuration
• Add membership upgrade/downgrade functionality
• Implement membership renewal process
• Add trial membership support
• Create membership pricing calculator

2.3 Enhanced Mobile Features

• Add offline mode support with local storage sync
• Implement workout tracking features
• Add progress photos upload functionality
• Create goal setting and tracking
• Add fitness measurements tracking (weight, body fat %, etc.)
• Implement workout plans viewing

2.4 Trainer Features

• Create trainer dashboard
• Implement trainer-client assignment system
• Add workout plan creation and management
• Create progress tracking tools for trainers
• Add trainer-client messaging system
• Implement class scheduling for trainers

2.5 Enhanced Analytics

• Member retention analytics
• Churn prediction dashboard
• Revenue forecasting
• Peak hours and capacity planning
• Client engagement metrics
• Cohort analysis reports

---

Phase 3: Production Readiness (HIGH PRIORITY)

3.1 Testing Infrastructure

• Set up Jest test environment (already configured, needs tests)
• Write unit tests for:
  • Database functions
  • API endpoints
  • Utility functions
  • Form validation
• Write integration tests for:
  • Authentication flow
  • User registration and management
  • Payment processing
  • Attendance check-in/out
• Add E2E tests with Playwright or Detox
• Achieve >80% code coverage

3.2 Security Enhancements

• Implement API rate limiting (using Express rate-limit or similar)
• Add input sanitization for all endpoints
• Implement CSRF protection
• Add security headers (helmet.js)
• Set up SQL injection prevention validation
• Implement role-based access control (RBAC) middleware
• Add 2FA authentication option
• Set up password strength requirements
• Implement session management and timeout

3.3 DevOps & Monitoring

• Set up CI/CD pipeline (GitHub Actions or GitLab CI):
  • Automated testing on PR
  • Linting and type checking
  • Automated deployment to staging
  • Production deployment approval flow
• Implement logging system:
  • Winston or Pino for structured logging
  • Request/response logging
  • Error logging with stack traces
  • Performance metrics logging
• Set up monitoring and alerting:
  • Application performance monitoring (APM)
  • Error tracking (Sentry or similar)
  • Uptime monitoring
  • Database performance monitoring
• Add health check endpoints
• Implement backup strategy for database

3.4 Performance Optimization

• Implement API response caching (Redis)
• Add database query optimization and indexing
• Implement pagination for all list endpoints
• Add image optimization for progress photos
• Implement lazy loading in mobile app
• Add bundle size optimization for web app
• Implement database connection pooling
• Add CDN for static assets

---

Phase 4: Advanced Features (LOW PRIORITY)

4.1 AI Integration

• Workout recommendation engine based on user history
• Progress prediction algorithms
• Personalized nutrition suggestions
• Injury risk assessment using ML
• Automated workout plan generation
• Chatbot for common questions

4.2 Business Intelligence

• Predictive analytics dashboard
• Churn prediction models
• Revenue optimization recommendations
• Capacity planning tools
• Customer lifetime value (CLV) calculation
• Marketing campaign effectiveness tracking

4.3 Integration & Extensibility

• Payment gateway integration (Stripe, PayPal)
• Email service integration (SendGrid, Mailgun)
• SMS service integration (Twilio)
• Calendar integration (Google Calendar, Apple Calendar)
• Wearable device integration (Fitbit, Apple Watch)
• Webhook system for third-party integrations

4.4 Scalability Enhancements

• Migrate to PostgreSQL for better scalability
• Implement microservices architecture
• Add multi-tenant support for gym chains
• Implement horizontal scaling strategy
• Add load balancing
• Database sharding strategy

---

Immediate Action Items (Next Sprint)

Week 1-2: Payment System

1. Create payment API endpoints
2. Build payment management UI in admin dashboard
3. Add payment history to mobile app
4. Implement payment reminders
5. Add payment analytics to dashboard

Week 3-4: Attendance System

1. Create attendance API endpoints
2. Build attendance tracking UI in admin
3. Implement check-in/check-out in mobile app
4. Add real-time attendance dashboard
5. Create attendance reports

Week 5-6: Notifications System

1. Create notifications API
2. Set up push notifications for mobile
3. Implement notification triggers (payments, attendance)
4. Add notification management in admin
5. Create notification preferences

Week 7-8: Testing & Security

1. Write unit tests for critical functionality
2. Add integration tests for API endpoints
3. Implement API rate limiting
4. Add security headers and input sanitization
5. Set up basic CI/CD pipeline

---

Success Metrics

Technical KPIs

• API response time < 200ms (95th percentile)
• Mobile app load time < 3 seconds
• Test coverage > 80%
• Zero critical security vulnerabilities
• 99.9% uptime
• Database query time < 100ms

Business KPIs

• User registration conversion rate > 80%
• Admin task completion time < 2 minutes
• User retention rate > 90%
• Payment collection rate > 95%
• Check-in process time < 30 seconds
• System adoption rate > 95%

---

Known Technical Debt

1. TODO Items in Code:

   • PostgreSQL, MySQL, MongoDB implementations in DatabaseFactory

2. Missing Error Handling:

   • Need comprehensive error boundaries
   • Better error messages for users

3. No Automated Testing:

   • Jest configured but no tests written

4. No Production Deployment:

   • No CI/CD pipeline
   • No staging environment
   • No rollback strategy

5. Performance Concerns:

   • No caching strategy
   • No API rate limiting
   • Queries not optimized with indexes

---

Questions to Address

1. Payment Integration: Which payment gateway to integrate? (Stripe, Square, PayPal?)
2. Notification Service: Use Expo Push Notifications or third-party service?
3. QR Code Check-in: Implement QR code generation for check-ins?
4. Database Migration: Stay with SQLite or migrate to PostgreSQL?
5. Multi-tenant: Will this support multiple gyms or single gym deployment?
6. Localization: Need to support multiple languages?

---

Resources Needed

• Payment gateway account (Stripe/Square)
• Push notification service credentials
• SMS service account (for notifications)
• Email service account
• Production hosting environment
• Domain name and SSL certificate
• Error tracking service account (Sentry)
• APM service account (if using paid service)

---

Next Review Date: After Payment System implementation
Sprint Duration: 2 weeks
Current Sprint: Payment System Implementation