CoachMe Technical Architecture
TypeScript-first DDD modular monolith for coach web, coach mobile, and client mobile.
CoachMe should ship quickly without collapsing domain boundaries. The first implementation should be a modular monolith with explicit bounded contexts, REST contracts, offline-capable mobile apps, and self-hosted infrastructure that can split into services later when a domain earns it.
Product Surfaces
Each app gets its own UX shell, but all apps share contracts, identity, permissions, domain rules, and design tokens where practical.
Coach Web App
Full desktop-optimized coaching workspace for dense workflows, reporting, review, template building, and operations.
- Next.js App Router.
- Server Components for data-heavy pages.
- Client Components for drag-and-drop builders, chat, media, and charts.
Coach Mobile App
Separate Expo app with full coach parity, adapted into mobile-native flows instead of desktop layouts compressed into a phone.
- Program and questionnaire creation/editing.
- Client review, messaging, nutrition, progress, and task inbox.
- SQLite-backed drafts and upload queue.
Client Mobile App
Separate Expo app for onboarding, Today view, workouts, meals, check-ins, progress, messaging, reminders, and motivation.
- Offline workout logging.
- Daily task completion and sync.
- Arabic/English, RTL, dark mode, and accessibility from the start.
Frameworks & Monorepo
The codebase should use one TypeScript ecosystem while keeping platform UI and domain implementation cleanly separated.
| Layer | Choice | Responsibility |
|---|---|---|
| Backend | NestJS modular monolith | REST API, OpenAPI contracts, workers, scheduled jobs, DDD application services. |
| Web | Next.js App Router | Coach/admin workspace, dashboards, builders, reports, settings, operations. |
| Mobile | Expo React Native | Separate coach and client store apps sharing mobile infrastructure packages. |
| API contracts | REST + OpenAPI | Typed client generation, regression tests, portable integration surface. |
| Package manager | pnpm workspace | Monorepo dependency management for apps and shared packages. |
Application Packages
apps/api: NestJS API and workers.apps/web: coach/admin web app.apps/mobile-coach: coach iOS/Android app.apps/mobile-client: client iOS/Android app.
Shared Packages
packages/domain: primitives, value objects, shared constants.packages/contracts: OpenAPI-generated clients and DTOs.packages/mobile-core: auth session, API client, sync, push, RTL.packages/ui-webandpackages/ui-mobile: platform design systems.
DDD Bounded Contexts
Each context owns its domain model, application use cases, persistence adapters, API controllers, events, and tests.
IdentityAccess
Users, auth identities, sessions, provider adapters, roles, invitations, and account linking.
CoachClientManagement
Coach-client relationships, profiles, status, notes, goals, milestones, measurements, and segmentation.
Forms
Questionnaire templates, form versions, assignments, schedules, submissions, and review tasks.
ProgramsAndExercise
Exercise provider integration, program templates, assigned programs, workout structure, alternatives, PRs, RPE/RIR.
DailyExecution
Today view, task generation, quick logs, workout session logs, meal completion, adherence events, offline sync.
Nutrition
Meal plans, recipes, macro targets, supplement schedules, nutrition templates, meal swap requests.
Communication
Conversations, messages, read receipts, voice notes, attachments, push notifications.
ProgressAnalytics
Charts, adherence scoring, progress comparisons, trend detection, weekly recaps, business analytics.
Billing & Integrations
Payments, subscriptions, receipts, referrals, wearables, email, calendar, video calls, cloud storage.
Data & Infrastructure
Self-host the core runtime while allowing external APIs for provider integrations, app-store push delivery, exercise content, food data, and identity provider handshakes.
PostgreSQL Source Of Truth
Use normalized tables for core aggregates and transactions. Use jsonb only where the shape is intentionally flexible: form answers, provider metadata, and versioned template snapshots.
Drizzle ORM
Use Drizzle for SQL-first schema, migrations, and repository implementations. Keep business rules in domain/application layers, not ORM models.
Redis + BullMQ
Use queues for notifications, reminders, media processing, weekly recaps, provider sync, PDF-to-template jobs, and outbox processing.
MinIO Object Storage
Store photos, videos, voice notes, PDFs, receipts, generated assets, and resources through signed URLs. Store metadata and permissions in PostgreSQL.
Offline & Sync
Mobile offline behavior is a first-class design constraint because clients train in weak-signal gyms and coaches may draft changes on mobile.
Client Mobile SQLite
- Assigned Today data cache.
- Offline workout session logs.
- Pending check-in/form submissions.
- Local outbox with retry and idempotency keys.
Coach Mobile SQLite
- Draft program and form edits.
- Client snapshots for review.
- Message and media upload queue.
- Conflict handling for drafts before publishing.
Auth & Access
Identity provider mechanics are separated from CoachMe business identity, role, and relationship rules.
Identity Stack
Use Keycloak as the self-hosted identity base. Store CoachMe-owned User, Coach, Client, CoachClientRelationship, and AuthIdentity records in PostgreSQL.
Provider Adapters
Implement Google, Apple, WhatsApp, and Telegram behind one provider port so registration, login, and onboarding flows do not depend on provider-specific branching.
Invitation Links
Client registration starts from app-owned invitation records with active, expired, consumed, and revoked states. A provider login alone never creates a coach-client relationship.
Authorization
Enforce role and relationship access in application use cases and API guards. Row-level security can be added later as defense in depth.
MVP Build Order
Sequence the build around the core coaching loop before business operations and heavier integrations.
- Foundation: monorepo, auth, PostgreSQL, OpenAPI, shared mobile core, localization/RTL, deployment.
- Identity/onboarding: coach registration, client invitation validation, client onboarding, role-based sessions.
- Coach operations: web and coach mobile dashboard, task inbox, client profiles, status, goals, notes, messaging.
- Forms: reusable builder on web and coach mobile, assignment/scheduling, client mobile submission.
- Programs/exercise: provider adapter, templates, web/mobile coach builders, client workout execution.
- Daily execution: client Today view, quick logs, offline workout logging, sync.
- Nutrition: templates, meal plans, macros, supplements, meal swap requests.
- Progress: measurements, photos, charts, adherence, PRs, weekly recap.
- Later: payments, gamification, wearables, calendar, email, and cloud integrations.
Testing Strategy
Test at domain, API, contract, and product-flow levels so the three app surfaces remain consistent.
Backend Tests
- Domain unit tests for aggregate rules and use cases.
- Integration tests with PostgreSQL, Redis, MinIO, and outbox processing.
- Security tests for invitations, relationship access, signed URLs, and role-specific routes.
Client Tests
- 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, offline sync, uploads, RTL, and push flows.
Feature Technical Pages
These grouped folders are ready for the next pass. Links are shown as planned until each feature page is created.
Authentication
- Coach login and registration ready
- Client invitation link validation planned
- Client login during onboarding planned
- Extensible authentication providers planned
Client Management
- Detailed profiles planned
- Measurements and photo timeline planned
- Questionnaire builder planned
- Onboarding workflow planned
Coach Workflow
- Coach task inbox planned
- Client risk flags planned
- Priority view planned
Workout Programs
- Exercise library planned
- Program builder planned
- Workout logging planned
- PR and RPE/RIR tracking planned
Mobile Experience
- Today view planned
- Quick-log daily tasks planned
- Offline workout mode planned
- Accessibility and dark mode planned
Nutrition
- Macro and micronutrient tracking planned
- Meal plan builder planned
- Supplement schedule planned
- Meal swap requests planned
Communication
- In-app messaging planned
- Voice notes planned
- Media and form attachments planned
- Push notifications planned
Analytics, Payments, Integrations
- Adherence scoring planned
- Progress charts and comparisons planned
- Billing and receipts planned
- Wearables, calendar, email, storage planned