# CoachMe Architecture Plan With Coach Mobile

## Summary

Build CoachMe as a **TypeScript-first DDD modular monolith** with three product surfaces:

- **Coach Web App:** full desktop-optimized coaching workspace.
- **Coach Mobile App:** full feature parity for coaches, adapted to mobile UX.
- **Client Mobile App:** daily execution, logging, onboarding, progress, and messaging.

Core stack:

- **Backend:** NestJS modular monolith, REST + OpenAPI.
- **Web:** Next.js App Router.
- **Mobile:** two separate Expo React Native apps.
- **Database:** PostgreSQL.
- **Mobile local storage:** SQLite for offline-capable workflows.
- **Queues/cache:** Redis + BullMQ.
- **Files/media:** self-hosted MinIO.
- **Auth:** Keycloak plus provider adapters for Google, Apple, WhatsApp, Telegram.
- **Deployment:** self-hosted VPS with Docker Compose first.

## Key Changes

Use separate mobile apps:

- `apps/mobile-coach`: coach-facing iOS/Android app.
- `apps/mobile-client`: trainee-facing iOS/Android app.
- Shared mobile foundation in `packages/mobile-core`: auth session, API client, offline sync, push handling, localization, RTL, design tokens.
- Shared feature UI where practical, but app-specific navigation and permissions stay separate.

Coach mobile has full parity, but with mobile-native interaction patterns:

- Program builder supports creation/editing on mobile using step-based screens, bottom sheets, reorder handles, and focused exercise search.
- Questionnaire builder supports mobile creation/editing with question list, add-question flow, settings sheets, preview, and publish/assign.
- Nutrition templates, meal plans, supplement schedules, client status, goals, progress reviews, messaging, task inbox, attachments, and notes all exist on coach mobile.
- Web remains the best surface for dense workflows, but mobile must not be read-only.

## Implementation Shape

Monorepo layout:

- `apps/api`: NestJS API, workers, scheduled jobs.
- `apps/web`: coach/admin web app.
- `apps/mobile-coach`: coach mobile app.
- `apps/mobile-client`: client mobile app.
- `packages/domain`: DDD primitives, shared value objects, domain constants.
- `packages/contracts`: OpenAPI-generated clients and DTOs.
- `packages/mobile-core`: shared Expo infrastructure.
- `packages/ui-web`: web design system.
- `packages/ui-mobile`: mobile design system.

Backend DDD bounded contexts:

- `IdentityAccess`
- `CoachClientManagement`
- `Forms`
- `ProgramsAndExercise`
- `DailyExecution`
- `Nutrition`
- `Communication`
- `ProgressAnalytics`
- `Billing`
- `Integrations`

All clients consume the same REST API. Authorization is role- and relationship-based, so the same backend use cases can serve web coach, mobile coach, and mobile client safely.

## Data & Offline

PostgreSQL remains the system of record.

Use SQLite in both mobile apps:

- Client mobile: offline workout logging, Today view cache, pending form/check-in submissions.
- Coach mobile: draft form/program edits, client snapshots, message queue, media upload queue.
- Sync uses a local outbox per app and server-side idempotency keys.
- Conflict policy: server wins for published plans/forms; mobile drafts can be resumed and resubmitted; workout logs/check-ins merge by stable client-generated IDs.

Use MinIO for progress photos, videos, voice notes, documents, receipts, and resource attachments. Mobile apps upload through signed URLs and retry failed uploads through the local outbox.

## MVP Build Order

1. Foundation: monorepo, auth, PostgreSQL, OpenAPI, shared mobile core, localization/RTL, deployment.
2. Identity/onboarding: coach registration, client invitation validation, client onboarding, role-based sessions.
3. Coach operations: web and coach mobile dashboard, task inbox, client profiles, status, goals, notes, messaging.
4. Forms: reusable builder on web and coach mobile, assignment/scheduling, client mobile submission.
5. Programs/exercise: provider adapter, program templates, web/mobile coach builders, client workout execution.
6. Daily execution: client Today view, quick logs, offline workout logging, sync.
7. Nutrition: templates, meal plans, macros, supplements, meal swap requests.
8. Progress: measurements, photos, charts, adherence, PRs, weekly recap.
9. Later: payments, gamification, wearables, calendar/email/cloud integrations.

## Test Plan

- Domain unit tests for each aggregate and use case.
- API integration tests with PostgreSQL, Redis, MinIO, and outbox processing.
- OpenAPI contract tests for web, coach mobile, and client mobile.
- Playwright tests for coach web builders and dashboards.
- Mobile E2E tests for both Expo apps: auth, navigation, offline sync, uploads, RTL, push flows.
- Parity tests for coach web vs coach mobile: create/edit/assign forms, programs, nutrition plans, and client actions.
- Security tests for invitations, coach-client access boundaries, signed media URLs, and role-specific routes.

## Assumptions

- Coach and client mobile apps are separate store apps.
- Coach mobile targets full feature parity, not review-only mode.
- Complex creation workflows may use different UX on mobile, but must support the same domain capabilities.
- Self-hosted VPS remains the deployment target.
- External APIs are acceptable for auth providers, notifications, exercise/food providers, and messaging integrations.